@inceptionstack/roundhouse 0.2.2 → 0.3.0

package/src/index.ts

@@ -8,13 +8,10 @@
  *   TELEGRAM_BOT_TOKEN=... npm start -- --config ./my-config.json
  */
 
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-
-import type { GatewayConfig } from "./types";
 import { getAgentFactory } from "./agents/registry";
 import { SingleAgentRouter } from "./router";
 import { Gateway } from "./gateway";
+import { loadConfig } from "./config";
 
 // ── Crash protection ─────────────────────────────────
 process.on("uncaughtException", (err) => {
@@ -24,60 +21,6 @@ process.on("unhandledRejection", (reason) => {
   console.error("[roundhouse] unhandledRejection:", reason);
 });
 
-// ── Default config ───────────────────────────────────
-const DEFAULT_CONFIG: GatewayConfig = {
-  agent: {
-    type: "pi",
-    cwd: process.cwd(),
-  },
-  chat: {
-    botUsername: process.env.BOT_USERNAME ?? "roundhouse_bot",
-    allowedUsers: process.env.ALLOWED_USERS
-      ? process.env.ALLOWED_USERS.split(",").map((u) => u.trim())
-      : [],
-    adapters: {
-      telegram: { mode: "polling" },
-    },
-  },
-};
-
-async function loadConfig(): Promise<GatewayConfig> {
-  // Check for ROUNDHOUSE_CONFIG env var (set by CLI/daemon)
-  const envConfig = process.env.ROUNDHOUSE_CONFIG;
-  if (envConfig) {
-    try {
-      const raw = await readFile(resolve(envConfig), "utf8");
-      console.log(`[roundhouse] loaded config from ${envConfig}`);
-      return JSON.parse(raw) as GatewayConfig;
-    } catch {
-      // Fall through to other methods
-    }
-  }
-
-  // Check for --config flag
-  const configIdx = process.argv.indexOf("--config");
-  if (configIdx !== -1 && process.argv[configIdx + 1]) {
-    const configPath = resolve(process.argv[configIdx + 1]);
-    console.log(`[roundhouse] loading config from ${configPath}`);
-    const raw = await readFile(configPath, "utf8");
-    return JSON.parse(raw) as GatewayConfig;
-  }
-
-  // Try gateway.config.json in cwd
-  try {
-    const raw = await readFile(
-      resolve(process.cwd(), "gateway.config.json"),
-      "utf8"
-    );
-    console.log("[roundhouse] loaded gateway.config.json");
-    return JSON.parse(raw) as GatewayConfig;
-  } catch {
-    // Fall back to defaults + env vars
-    console.log("[roundhouse] using default config + env vars");
-    return DEFAULT_CONFIG;
-  }
-}
-
 async function main() {
   const config = await loadConfig();
 

package/src/memory/bootstrap.ts

@@ -0,0 +1,98 @@
+/**
+ * memory/bootstrap.ts — Create default memory file templates
+ *
+ * Creates MEMORY.md, memory-rules.md, and daily/ directory if they don't exist.
+ * Mode-aware: writes different memory-rules.md for Full vs Complement mode.
+ */
+
+import { writeFile, mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileExists } from "../config";
+import type { MemoryConfig, MemoryMode } from "./types";
+
+const DEFAULT_MEMORY_MD = `# Memory
+
+Durable facts, preferences, decisions, and stable project context.
+Keep under 100 lines. Prefer editing existing entries over appending duplicates.
+`;
+
+const RULES_FULL = `# Memory Rules
+
+You have no built-in memory extension. Roundhouse manages your memory via workspace files.
+
+## Always-injected files
+- ~/MEMORY.md — durable facts, preferences, decisions, project context
+- Today's daily front page — headlines + leads + article links
+- This file (memory-rules.md)
+
+## MEMORY.md
+- Keep under 100 lines
+- Store user preferences, project conventions, architecture decisions
+- Edit existing entries rather than appending duplicates
+- When the user corrects you or states a preference, ALWAYS write it here
+
+## Daily front pages
+- Keep under 2K tokens
+- Headlines + leads + relative links to articles
+- No long logs, transcripts, or command output
+
+## Articles
+- Full details in daily/YYYY-MM-DD/articles/
+- New article per new durable topic; append for continuing work
+- Agent reads articles on demand with file tools
+`;
+
+const RULES_COMPLEMENT = `# Memory Rules
+
+You have a memory extension installed that handles facts, preferences, and corrections.
+Use memory_remember for discrete facts. Use memory_search to recall them.
+
+Roundhouse manages narrative context separately:
+
+## Always-injected files
+- ~/MEMORY.md — high-level project context, architecture decisions, active investigations
+- Today's daily front page — headlines + leads + article links
+- This file (memory-rules.md)
+
+## MEMORY.md
+- NOT for individual preferences (those go in memory_remember)
+- For ongoing project/architecture context that doesn't fit key-value storage
+- Keep under 100 lines
+
+## Daily front pages
+- Keep under 2K tokens
+- Headlines + leads + relative links to articles
+
+## Articles
+- Full details in daily/YYYY-MM-DD/articles/
+- Agent reads on demand with file tools
+`;
+
+/**
+ * Ensure memory directory structure and default files exist.
+ * Does not overwrite existing files.
+ */
+export async function bootstrapMemoryFiles(rootDir: string, mode: MemoryMode, config?: MemoryConfig): Promise<void> {
+  const mainFile = config?.mainFile ?? "MEMORY.md";
+  const dailyDir = config?.dailyDir ?? "daily";
+
+  // Ensure directories
+  await mkdir(resolve(rootDir, dailyDir), { recursive: true });
+
+  // Create MEMORY.md if missing
+  const memoryPath = resolve(rootDir, mainFile);
+  if (!await fileExists(memoryPath)) {
+    await writeFile(memoryPath, DEFAULT_MEMORY_MD);
+    console.log(`[memory] created ${memoryPath}`);
+  }
+
+  // Create/update memory-rules.md based on mode
+  const rulesPath = resolve(rootDir, "memory-rules.md");
+  const rulesContent = mode === "complement" ? RULES_COMPLEMENT : RULES_FULL;
+
+  // Only write if doesn't exist or mode changed (check first line)
+  if (!await fileExists(rulesPath)) {
+    await writeFile(rulesPath, rulesContent);
+    console.log(`[memory] created ${rulesPath} (mode: ${mode})`);
+  }
+}

package/src/memory/files.ts

@@ -0,0 +1,100 @@
+/**
+ * memory/files.ts — Read memory files and compute digests
+ */
+
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import type { MemoryConfig, MemoryFileSet, MemorySnapshot } from "./types";
+
+const DEFAULTS = {
+  mainFile: "MEMORY.md",
+  dailyDir: "daily",
+  rulesFile: "memory-rules.md",
+};
+
+/** Format a date as YYYY-MM-DD */
+export function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/** Get today and recent dates */
+function getRecentDates(recentDays: number): string[] {
+  const dates: string[] = [];
+  const now = new Date();
+  dates.push(formatDate(now));
+  for (let i = 1; i <= recentDays; i++) {
+    const d = new Date(now);
+    d.setDate(d.getDate() - i);
+    dates.push(formatDate(d));
+  }
+  return dates;
+}
+
+/** Resolve which memory files to load based on config */
+export function resolveMemoryFiles(rootDir: string, config?: MemoryConfig): MemoryFileSet {
+  const mainFile = config?.mainFile ?? DEFAULTS.mainFile;
+  const dailyDir = config?.dailyDir ?? DEFAULTS.dailyDir;
+  const includeToday = config?.inject?.includeToday ?? true;
+  const recentDays = config?.inject?.includeRecentDays ?? 1;
+
+  const files: MemoryFileSet["files"] = [];
+
+  // Always include MEMORY.md
+  files.push({ label: mainFile, path: resolve(rootDir, mainFile) });
+
+  // Always include memory-rules.md
+  files.push({ label: DEFAULTS.rulesFile, path: resolve(rootDir, DEFAULTS.rulesFile) });
+
+  // Daily notes
+  if (includeToday) {
+    const dates = getRecentDates(recentDays);
+    for (const date of dates) {
+      const dailyPath = resolve(rootDir, dailyDir, `${date}.md`);
+      files.push({ label: `${dailyDir}/${date}.md`, path: dailyPath });
+    }
+  }
+
+  return { files };
+}
+
+/** Read memory files, skip missing ones, return snapshot with digest */
+export async function readMemorySnapshot(fileSet: MemoryFileSet, maxBytes?: number): Promise<MemorySnapshot> {
+  const entries: MemorySnapshot["entries"] = [];
+  let totalBytes = 0;
+  const limit = maxBytes ?? 48_000;
+
+  for (const file of fileSet.files) {
+    try {
+      const content = await readFile(file.path, "utf8");
+      if (totalBytes + content.length > limit) {
+        // Truncate to fit budget
+        const remaining = limit - totalBytes;
+        if (remaining > 100) {
+          entries.push({ label: file.label, content: content.slice(0, remaining) + "\n\n(truncated)" });
+          totalBytes = limit;
+        }
+        break;
+      }
+      entries.push({ label: file.label, content });
+      totalBytes += content.length;
+    } catch {
+      // File doesn't exist — skip silently
+    }
+  }
+
+  const digest = hashEntries(entries);
+  return { entries, digest };
+}
+
+/** Compute a fast hash of memory entries */
+function hashEntries(entries: MemorySnapshot["entries"]): string {
+  const h = createHash("sha256");
+  for (const e of entries) {
+    h.update(e.label);
+    h.update("\0");
+    h.update(e.content);
+    h.update("\0");
+  }
+  return h.digest("hex").slice(0, 16);
+}

package/src/memory/inject.ts

@@ -0,0 +1,41 @@
+/**
+ * memory/inject.ts — Build memory injection blocks for agent messages
+ */
+
+import type { MemorySnapshot } from "./types";
+import type { AgentMessage } from "../types";
+
+/**
+ * Build a memory injection text block from a snapshot.
+ * Includes version/date so the agent knows it supersedes prior blocks.
+ */
+export function buildMemoryInjection(snapshot: MemorySnapshot, reason: string): string {
+  if (snapshot.entries.length === 0) return "";
+
+  const date = new Date().toISOString().slice(0, 19) + "Z";
+  const sections = snapshot.entries.map(
+    (e) => `## ${e.label}\n${e.content}`
+  ).join("\n\n");
+
+  return [
+    `<roundhouse_memory v="${snapshot.digest}" date="${date}" reason="${reason}">`,
+    `This is your current workspace memory. It supersedes any prior roundhouse_memory blocks.`,
+    ``,
+    sections,
+    `</roundhouse_memory>`,
+  ].join("\n");
+}
+
+/**
+ * Prepend memory injection to a user message.
+ * Returns a new AgentMessage with memory block + original text.
+ */
+export function injectMemoryIntoMessage(message: AgentMessage, injection: string): AgentMessage {
+  if (!injection) return message;
+
+  const combinedText = message.text
+    ? `${injection}\n\n${message.text}`
+    : injection;
+
+  return { ...message, text: combinedText };
+}

package/src/memory/lifecycle.ts

@@ -0,0 +1,245 @@
+/**
+ * memory/lifecycle.ts — Memory lifecycle for gateway turns
+ *
+ * Two modes:
+ * - Full: inject memory, track digest, flush before compact
+ * - Complement: only flush before compact (agent extension handles memory)
+ *
+ * Both modes share proactive compaction logic.
+ */
+
+import type { AgentAdapter, AgentMessage } from "../types";
+import type { MemoryConfig, MemoryMode, PreparedTurn, PressureLevel, ThreadMemoryState } from "./types";
+import { resolveMemoryFiles, readMemorySnapshot, formatDate } from "./files";
+import { loadThreadMemoryState, saveThreadMemoryState } from "./state";
+import { shouldInjectMemory, classifyContextPressure, isSoftFlushOnCooldown } from "./policy";
+import { buildMemoryInjection, injectMemoryIntoMessage } from "./inject";
+import { buildFlushPrompt } from "./prompts";
+import { bootstrapMemoryFiles } from "./bootstrap";
+
+// ── Memory mode detection ────────────────────────────
+
+/**
+ * Determine memory mode from agent info.
+ * Returns "unknown" if agent info isn't available yet (before first session).
+ */
+export function determineMemoryMode(agentInfo: Record<string, unknown>): MemoryMode {
+  const has = agentInfo.hasMemoryExtension;
+  if (has === true) return "complement";
+  if (has === false) return "full";
+  return "unknown";
+}
+
+// ── Pre-turn: prepare memory ─────────────────────────
+
+/**
+ * Prepare memory for a turn. Called before sending prompt to agent.
+ *
+ * In Full mode: may inject memory into the message.
+ * In Complement mode: passes message through unchanged.
+ * In Unknown mode: defaults to Full behavior.
+ */
+export async function prepareMemoryForTurn(
+  threadId: string,
+  message: AgentMessage,
+  agent: AgentAdapter,
+  rootDir: string,
+  config?: MemoryConfig,
+): Promise<PreparedTurn> {
+  if (config?.enabled === false) {
+    return { message, beforeDigest: null, injected: false };
+  }
+
+  const mode = getMode(agent);
+
+  // Complement mode: no injection, just track digest for finalize
+  // Unknown mode: also skip — we can't inject correctly before knowing if agent has memory extension
+  // (mode is detected during session creation, which happens inside promptStream)
+  if (mode === "complement" || mode === "unknown") {
+    return { message, beforeDigest: null, injected: false };
+  }
+
+  // Full mode: inject if needed
+  try {
+    // Bootstrap memory files on first use
+    await bootstrapMemoryFiles(rootDir, "full", config);
+
+    const fileSet = resolveMemoryFiles(rootDir, config);
+    const snapshot = await readMemorySnapshot(fileSet, config?.inject?.maxBytes);
+    const state = await loadThreadMemoryState(threadId);
+
+    // Check pending compact from interrupted flush — surface to gateway
+    let pendingCompactLevel: PreparedTurn["pendingCompact"];
+    if (state.pendingCompact) {
+      pendingCompactLevel = state.pendingCompact;
+      state.pendingCompact = undefined;
+      await saveThreadMemoryState(threadId, state);
+      console.log(`[memory] pending compact (${pendingCompactLevel}) cleared for ${threadId} — gateway will retry`);
+    }
+
+    const decision = shouldInjectMemory(state, snapshot.digest);
+
+    if (decision.inject) {
+      const injection = buildMemoryInjection(snapshot, decision.reason);
+      const injectedMessage = injectMemoryIntoMessage(message, injection);
+
+      // Update state
+      state.lastInjectedDigest = snapshot.digest;
+      state.lastInjectedAt = new Date().toISOString();
+      state.lastSeenLocalDate = formatDate(new Date());
+      state.forceInjectReason = undefined;
+      await saveThreadMemoryState(threadId, state);
+
+      console.log(`[memory] injected into ${threadId} (reason: ${decision.reason}, ${snapshot.entries.length} files, digest: ${snapshot.digest})`);
+      return { message: injectedMessage, beforeDigest: snapshot.digest, injected: true, pendingCompact: pendingCompactLevel };
+    }
+
+    return { message, beforeDigest: snapshot.digest, injected: false, pendingCompact: pendingCompactLevel };
+  } catch (err) {
+    console.error(`[memory] prepareMemoryForTurn error:`, (err as Error).message);
+    return { message, beforeDigest: null, injected: false };
+  }
+}
+
+// ── Post-turn: finalize and check pressure ───────────
+
+/**
+ * Finalize memory after a turn. Called after agent response.
+ *
+ * In Full mode: check if agent wrote memory files (update digest).
+ * Both modes: check context pressure for proactive compaction.
+ *
+ * Returns the pressure level for the gateway to act on.
+ */
+export async function finalizeMemoryForTurn(
+  threadId: string,
+  beforeDigest: string | null,
+  agent: AgentAdapter,
+  rootDir: string,
+  config?: MemoryConfig,
+): Promise<PressureLevel> {
+  if (config?.enabled === false) return "none";
+
+  const mode = getMode(agent);
+
+  // In Full mode: check if agent modified memory files
+  if (mode !== "complement" && beforeDigest) {
+    try {
+      const fileSet = resolveMemoryFiles(rootDir, config);
+      const snapshot = await readMemorySnapshot(fileSet, config?.inject?.maxBytes);
+      if (snapshot.digest !== beforeDigest) {
+        const state = await loadThreadMemoryState(threadId);
+        state.lastInjectedDigest = snapshot.digest;
+        state.lastKnownDigest = snapshot.digest;
+        await saveThreadMemoryState(threadId, state);
+        console.log(`[memory] agent updated memory files (new digest: ${snapshot.digest})`);
+      }
+    } catch (err) {
+      console.error(`[memory] finalizeMemoryForTurn digest check error:`, (err as Error).message);
+    }
+  }
+
+  // Check context pressure (both modes)
+  if (config?.compact?.enabled === false) return "none";
+
+  try {
+    const info = agent.getInfo?.(threadId) ?? {};
+    const pressure = classifyContextPressure(
+      {
+        contextTokens: typeof info.contextTokens === "number" ? info.contextTokens : null,
+        contextWindow: typeof info.contextWindow === "number" ? info.contextWindow : null,
+        contextPercent: typeof info.contextPercent === "number" ? info.contextPercent : null,
+      },
+      config?.compact,
+    );
+    return pressure;
+  } catch {
+    return "none";
+  }
+}
+
+// ── Flush + compact (atomic operation) ───────────────
+
+/**
+ * Flush memory then compact. Used for proactive compaction and /compact command.
+ *
+ * 1. Send maintenance prompt (agent saves important context)
+ * 2. Compact the session
+ * 3. Mark force re-inject for Full mode
+ *
+ * Returns compaction result or null if nothing to compact.
+ */
+export async function flushMemoryThenCompact(
+  threadId: string,
+  agent: AgentAdapter,
+  rootDir: string,
+  level: "soft" | "hard" | "emergency" | "manual",
+  config?: MemoryConfig,
+): Promise<{ tokensBefore: number; tokensAfter: number | null } | null> {
+  const mode = getMode(agent);
+
+  // Soft flush: just prompt to save, don't compact
+  if (level === "soft") {
+    const state = await loadThreadMemoryState(threadId);
+    if (isSoftFlushOnCooldown(state, config?.compact)) {
+      console.log(`[memory] soft flush skipped for ${threadId} — cooldown`);
+      return null;
+    }
+
+    try {
+      const flushText = buildFlushPrompt(mode === "unknown" ? "full" : mode, "soft");
+      await agent.prompt(threadId, { text: flushText });
+      state.lastSoftFlushAt = new Date().toISOString();
+      await saveThreadMemoryState(threadId, state);
+      console.log(`[memory] soft flush completed for ${threadId}`);
+    } catch (err) {
+      console.error(`[memory] soft flush failed for ${threadId}:`, (err as Error).message);
+    }
+    return null;
+  }
+
+  // Hard/emergency/manual: flush then compact
+  if (!agent.compact) return null;
+
+  const effectiveLevel = level === "manual" ? "hard" : level;
+
+  try {
+    // Step 1: flush
+    const flushText = buildFlushPrompt(mode === "unknown" ? "full" : mode, effectiveLevel);
+    console.log(`[memory] flushing memory for ${threadId} (level: ${level})`);
+    await agent.prompt(threadId, { text: flushText });
+
+    // Step 2: compact
+    console.log(`[memory] compacting ${threadId}`);
+    const result = await agent.compact(threadId);
+    if (!result) return null;
+
+    // Step 3: mark force re-inject (Full mode only)
+    if (mode !== "complement") {
+      const state = await loadThreadMemoryState(threadId);
+      state.forceInjectReason = "after-compact";
+      state.lastCompactAt = new Date().toISOString();
+      state.pendingCompact = undefined;
+      await saveThreadMemoryState(threadId, state);
+    }
+
+    console.log(`[memory] flush+compact done for ${threadId}: ${result.tokensBefore} → ${result.tokensAfter ?? "?"} tokens`);
+    return result;
+  } catch (err) {
+    console.error(`[memory] flush+compact failed for ${threadId}:`, (err as Error).message);
+    // Mark pending so we retry on next turn
+    try {
+      const state = await loadThreadMemoryState(threadId);
+      state.pendingCompact = effectiveLevel;
+      await saveThreadMemoryState(threadId, state);
+    } catch {}
+    return null;
+  }
+}
+
+// ── Helper ───────────────────────────────────────────
+
+function getMode(agent: AgentAdapter): MemoryMode {
+  const info = agent.getInfo?.() ?? {};
+  return determineMemoryMode(info);
+}

package/src/memory/policy.ts

@@ -0,0 +1,122 @@
+/**
+ * memory/policy.ts — Memory injection and compaction policy decisions
+ *
+ * Pure functions — no side effects, easy to test.
+ */
+
+import type { MemoryConfig, ThreadMemoryState, PressureLevel } from "./types";
+import { formatDate } from "./files";
+
+// ── Defaults ─────────────────────────────────────────
+
+const DEFAULT_SOFT_PERCENT = 0.45;
+const DEFAULT_SOFT_TOKENS = 180_000;
+const DEFAULT_HARD_PERCENT = 0.50;
+const DEFAULT_HARD_TOKENS = 200_000;
+const DEFAULT_EMERGENCY_THRESHOLD = 32_768;
+const DEFAULT_COOLDOWN_MS = 10 * 60_000; // 10 minutes
+
+// ── Injection policy ─────────────────────────────────
+
+export interface InjectionDecision {
+  inject: boolean;
+  reason: string;
+}
+
+/**
+ * Decide whether to inject memory into this turn.
+ * Called ONLY in Full mode (when agent has no memory extension).
+ */
+export function shouldInjectMemory(
+  state: ThreadMemoryState,
+  currentDigest: string,
+  now: Date = new Date(),
+): InjectionDecision {
+  // Force flag (after compact, new session, manual)
+  if (state.forceInjectReason) {
+    return { inject: true, reason: state.forceInjectReason };
+  }
+
+  // No previous injection — first time for this thread
+  if (!state.lastInjectedDigest) {
+    return { inject: true, reason: "first-injection" };
+  }
+
+  // Memory files changed (cron wrote, another thread wrote, user edited)
+  if (currentDigest !== state.lastInjectedDigest) {
+    return { inject: true, reason: "changed" };
+  }
+
+  // Date boundary — new daily note
+  const today = formatDate(now);
+  if (state.lastSeenLocalDate && state.lastSeenLocalDate !== today) {
+    return { inject: true, reason: "date-boundary" };
+  }
+
+  return { inject: false, reason: "unchanged" };
+}
+
+// ── Context pressure ─────────────────────────────────
+
+export interface ContextInfo {
+  contextTokens: number | null;
+  contextWindow: number | null;
+  contextPercent: number | null;
+}
+
+/**
+ * Classify context pressure level.
+ * Used in BOTH modes (complement and full) for proactive compaction.
+ */
+export function classifyContextPressure(
+  info: ContextInfo,
+  config?: MemoryConfig["compact"],
+): PressureLevel {
+  const tokens = info.contextTokens;
+  const window = info.contextWindow;
+  const percent = info.contextPercent;
+
+  // Can't classify without data
+  if (tokens == null || window == null) return "none";
+
+  const remaining = window - tokens;
+  const emergencyThreshold = config?.emergencyThresholdTokens ?? DEFAULT_EMERGENCY_THRESHOLD;
+
+  // Emergency: running out of room
+  if (remaining <= emergencyThreshold) return "emergency";
+
+  const pctDecimal = percent != null ? percent / 100 : tokens / window;
+
+  // Hard threshold
+  const hardPct = config?.hardPercent ?? DEFAULT_HARD_PERCENT;
+  const hardTok = config?.hardTokens ?? DEFAULT_HARD_TOKENS;
+  if (pctDecimal >= hardPct || tokens >= hardTok) return "hard";
+
+  // Soft threshold
+  const softPct = config?.softPercent ?? DEFAULT_SOFT_PERCENT;
+  const softTok = config?.softTokens ?? DEFAULT_SOFT_TOKENS;
+  if (pctDecimal >= softPct || tokens >= softTok) return "soft";
+
+  return "none";
+}
+
+/**
+ * Check whether a soft flush should be skipped due to cooldown.
+ */
+export function isSoftFlushOnCooldown(state: ThreadMemoryState, config?: MemoryConfig["compact"]): boolean {
+  if (!state.lastSoftFlushAt) return false;
+  const cooldownMs = config?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  const elapsed = Date.now() - new Date(state.lastSoftFlushAt).getTime();
+  return elapsed < cooldownMs;
+}
+
+// ── Pressure comparison ───────────────────────────────────
+
+const PRESSURE_SEVERITY: Record<PressureLevel, number> = { none: 0, soft: 1, hard: 2, emergency: 3 };
+
+/** Return the higher-severity pressure level. */
+export function maxPressure(a: PressureLevel | undefined, b: PressureLevel): PressureLevel {
+  const sa = PRESSURE_SEVERITY[a ?? "none"] ?? 0;
+  const sb = PRESSURE_SEVERITY[b] ?? 0;
+  return sa > sb ? (a ?? "none") : b;
+}