Skip to content

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

5.6 KB
Raw Blame
/**
 * Kernel update: advance a stored `system_config.yaml` to the current built-in defaults
 * **without losing user customizations** — the smart-merge counterpart of
 * `resetSystemConfigToDefaults` (which overwrites everything; the two actions sit side by
 * side in the Web App).
 *
 * The unit is a **settings tab** (see KERNEL_TABS), matched and written whole:
 *
 * - tab absent from the config → it predates the section, so the defaults are materialized
 *   (reported `advanced`);
 * - tab hashing equal to the current default → untouched, not reported;
 * - tab hashing equal to a **superseded default** (KERNEL_HISTORY.superseded) → an old default
 *   the user never edited: every path the tab owns is rewritten from the current defaults
 *   (`advanced`), which is also how tools added since reach the config;
 * - anything else → the user edited something in that tab, or it comes from a generation too
 *   old to be recorded: the whole tab is conservatively kept (`kept`), edits, additions and
 *   deliberate deletions alike. Restore-default-config remains the full-refresh recourse.
 *
 * Never touched: `name`, `description`, `version` (the optimization counter) and
 * `tools.mcpServers` — identity and user-owned data, none of them owned by a kernel tab. The
 * file is edited via yaml `parseDocument`, so comments and untouched content survive (same
 * mechanism as the config PUT); finally the config is stamped `kernel_version: KERNEL_VERSION`.
 */
import fs from "node:fs/promises";
import { parseDocument, parse as parseYaml } from "yaml";
import { atomicWriteFile } from "../internal/atomic-write.js";
import { defaultSystemConfig } from "./default-config.js";
import {
  KERNEL_SUPERSEDED_TAB_HASHES,
  KERNEL_TABS,
  KERNEL_TAB_KEYS,
  KERNEL_VERSION,
  isSupersededTab,
  kernelTabHash,
  valueAtPath,
  type KernelSupersededTabHashes,
  type KernelTab,
} from "./kernel-history.js";
import { assertValidId } from "./agent-state.js";
import { systemConfigPath } from "./paths.js";

/** Outcome of a kernel update, tab keys in the settings page's tab order (see KERNEL_TABS). */
export interface KernelUpdateResult {
  /** Tabs written to the current defaults (previously absent, or an untouched old default). */
  advanced: KernelTab[];
  /** Tabs left alone because they match no recorded default (customized — and unrecorded old generations, kept conservatively). */
  kept: KernelTab[];
  /** The stamp written: always the current KERNEL_VERSION. */
  kernelVersion: string;
}

/** Test seam: alternate superseded tab hashes (same shape as KERNEL_SUPERSEDED_TAB_HASHES). Production callers never pass it. */
export interface KernelUpdateOptions {
  supersededTabs?: KernelSupersededTabHashes;
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

export async function applyKernelUpdate(
  root: string,
  projectId: string,
  agentId: string,
  options?: KernelUpdateOptions,
): Promise<KernelUpdateResult> {
  // Validate before building paths, to prevent path traversal.
  assertValidId("project_id", projectId);
  assertValidId("agent_id", agentId);
  const configPath = systemConfigPath(root, projectId, agentId);
  let raw: string;
  try {
    raw = await fs.readFile(configPath, "utf8");
  } catch {
    throw new Error(`Agent State config not found: ${configPath} (the Agent does not exist).`);
  }
  const parsed = parseYaml(raw) as unknown;
  const stored = isPlainObject(parsed) ? parsed : {};
  const doc = parseDocument(raw);

  const superseded = options?.supersededTabs ?? KERNEL_SUPERSEDED_TAB_HASHES;
  const advanced: KernelTab[] = [];
  const kept: KernelTab[] = [];

  /**
   * setIn that tolerates an invalid intermediate node — a hand-edited dangling `tools:` key
   * parses as null, and `doc.setIn(["tools", …])` would throw "Expected YAML collection" on
   * it. Such a section is effectively missing on the read side (the tab reads absent and gets
   * materialized), so it is replaced by a map first — once, tracked so a later write to the
   * same section does not wipe the earlier one.
   */
  const replacedSections = new Set<string>();
  const setDeep = (segments: string[], value: unknown): void => {
    for (let i = 1; i < segments.length; i++) {
      const ancestor = segments.slice(0, i);
      const key = ancestor.join(".");
      if (replacedSections.has(key)) continue;
      const existing = valueAtPath(stored, ancestor);
      if (existing !== undefined && !isPlainObject(existing)) {
        // createNode: a bare `{}` would be stored verbatim as a JS object, not a YAMLMap,
        // and the child setIn below would still throw.
        doc.setIn(ancestor, doc.createNode({}));
        replacedSections.add(key);
      }
    }
    doc.setIn(segments, value);
  };

  const defaults = defaultSystemConfig();

  for (const tab of KERNEL_TAB_KEYS) {
    const storedHash = kernelTabHash(stored, tab);
    if (storedHash !== null) {
      if (storedHash === kernelTabHash(defaults, tab)) continue;
      if (!isSupersededTab(tab, storedHash, superseded)) {
        kept.push(tab);
        continue;
      }
    }
    // Absent, or an untouched old default: write every path the tab owns from the defaults.
    for (const path of KERNEL_TABS[tab]) {
      const segments = path.split(".");
      const value = valueAtPath(defaults, segments);
      if (value !== undefined) setDeep(segments, value);
    }
    advanced.push(tab);
  }

  doc.setIn(["kernel_version"], KERNEL_VERSION);
  await atomicWriteFile(configPath, doc.toString(), { followSymlinks: true });
  return { advanced, kept, kernelVersion: KERNEL_VERSION };
}