mulmoclaude 0.1.0

package/server/system/logger/config.ts

@@ -0,0 +1,112 @@
+import path from "path";
+import type { LogFormat, LogLevel } from "./types.js";
+import { LEVEL_PRIORITY } from "./types.js";
+
+export interface FileRotationConfig {
+  kind: "daily";
+  maxFiles: number;
+}
+
+export interface ConsoleSinkConfig {
+  enabled: boolean;
+  level: LogLevel;
+  format: LogFormat;
+}
+
+export interface FileSinkConfig {
+  enabled: boolean;
+  level: LogLevel;
+  format: LogFormat;
+  dir: string;
+  rotation: FileRotationConfig;
+}
+
+export interface TelemetrySinkConfig {
+  enabled: boolean;
+  level: LogLevel;
+  format: LogFormat;
+}
+
+export interface LoggerConfig {
+  sinks: {
+    console: ConsoleSinkConfig;
+    file: FileSinkConfig;
+    telemetry: TelemetrySinkConfig;
+  };
+}
+
+const DEFAULT_FILE_DIR = path.join("server", "system", "logs");
+const DEFAULT_MAX_FILES = 14;
+
+export const DEFAULT_CONFIG: LoggerConfig = {
+  sinks: {
+    console: { enabled: true, level: "info", format: "text" },
+    file: {
+      enabled: true,
+      level: "debug",
+      format: "json",
+      dir: DEFAULT_FILE_DIR,
+      rotation: { kind: "daily", maxFiles: DEFAULT_MAX_FILES },
+    },
+    telemetry: { enabled: false, level: "error", format: "json" },
+  },
+};
+
+function parseLevel(raw: string | undefined): LogLevel | undefined {
+  if (!raw) return undefined;
+  const normalized = raw.toLowerCase();
+  return normalized in LEVEL_PRIORITY ? (normalized as LogLevel) : undefined;
+}
+
+function parseFormat(raw: string | undefined): LogFormat | undefined {
+  if (!raw) return undefined;
+  const normalized = raw.toLowerCase();
+  return normalized === "text" || normalized === "json" ? normalized : undefined;
+}
+
+function parseBool(raw: string | undefined): boolean | undefined {
+  if (raw === undefined) return undefined;
+  const normalized = raw.toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes") return true;
+  if (normalized === "false" || normalized === "0" || normalized === "no") return false;
+  return undefined;
+}
+
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const num = Number(raw);
+  return Number.isInteger(num) && num > 0 ? num : undefined;
+}
+
+export type Env = Partial<Record<string, string>>;
+
+export function resolveConfig(env: Env): LoggerConfig {
+  const coarseLevel = parseLevel(env.LOG_LEVEL);
+  const consoleLevel = parseLevel(env.LOG_CONSOLE_LEVEL) ?? coarseLevel;
+  const fileLevel = parseLevel(env.LOG_FILE_LEVEL) ?? coarseLevel;
+
+  return {
+    sinks: {
+      console: {
+        enabled: parseBool(env.LOG_CONSOLE_ENABLED) ?? DEFAULT_CONFIG.sinks.console.enabled,
+        level: consoleLevel ?? DEFAULT_CONFIG.sinks.console.level,
+        format: parseFormat(env.LOG_CONSOLE_FORMAT) ?? DEFAULT_CONFIG.sinks.console.format,
+      },
+      file: {
+        enabled: parseBool(env.LOG_FILE_ENABLED) ?? DEFAULT_CONFIG.sinks.file.enabled,
+        level: fileLevel ?? DEFAULT_CONFIG.sinks.file.level,
+        format: parseFormat(env.LOG_FILE_FORMAT) ?? DEFAULT_CONFIG.sinks.file.format,
+        dir: env.LOG_FILE_DIR ?? DEFAULT_CONFIG.sinks.file.dir,
+        rotation: {
+          kind: "daily",
+          maxFiles: parsePositiveInt(env.LOG_FILE_MAX_FILES) ?? DEFAULT_CONFIG.sinks.file.rotation.maxFiles,
+        },
+      },
+      telemetry: {
+        enabled: parseBool(env.LOG_TELEMETRY_ENABLED) ?? DEFAULT_CONFIG.sinks.telemetry.enabled,
+        level: parseLevel(env.LOG_TELEMETRY_LEVEL) ?? DEFAULT_CONFIG.sinks.telemetry.level,
+        format: parseFormat(env.LOG_TELEMETRY_FORMAT) ?? DEFAULT_CONFIG.sinks.telemetry.format,
+      },
+    },
+  };
+}

package/server/system/logger/formatters.ts

@@ -0,0 +1,40 @@
+import type { Formatter, LogRecord } from "./types.js";
+
+function formatData(data: Record<string, unknown> | undefined): string {
+  if (!data) return "";
+  const parts: string[] = [];
+  for (const [key, val] of Object.entries(data)) {
+    parts.push(`${key}=${stringifyScalar(val)}`);
+  }
+  return parts.length ? ` ${parts.join(" ")}` : "";
+}
+
+function stringifyScalar(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") {
+    return /\s/.test(value) ? JSON.stringify(value) : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export const formatText: Formatter = (record: LogRecord): string => {
+  const level = record.level.toUpperCase().padEnd(5);
+  return `${record.time} ${level} [${record.prefix}] ${record.message}${formatData(record.data)}`;
+};
+
+export const formatJson: Formatter = (record: LogRecord): string => {
+  const payload: Record<string, unknown> = {
+    time: record.time,
+    level: record.level,
+    prefix: record.prefix,
+    message: record.message,
+  };
+  if (record.data) payload.data = record.data;
+  return JSON.stringify(payload);
+};

package/server/system/logger/index.ts

@@ -0,0 +1,53 @@
+import type { LoggerConfig } from "./config.js";
+import { resolveConfig } from "./config.js";
+import { createConsoleSink, createFileSink, createTelemetrySink } from "./sinks.js";
+import type { LogLevel, LogRecord, Sink } from "./types.js";
+import { LEVEL_PRIORITY } from "./types.js";
+
+export type { LogLevel, LogRecord } from "./types.js";
+export type { LoggerConfig } from "./config.js";
+export { resolveConfig, DEFAULT_CONFIG } from "./config.js";
+
+export interface Logger {
+  error(prefix: string, message: string, data?: Record<string, unknown>): void;
+  warn(prefix: string, message: string, data?: Record<string, unknown>): void;
+  info(prefix: string, message: string, data?: Record<string, unknown>): void;
+  debug(prefix: string, message: string, data?: Record<string, unknown>): void;
+}
+
+export function createLogger(config: LoggerConfig): Logger {
+  const sinks: Sink[] = [];
+  if (config.sinks.console.enabled) sinks.push(createConsoleSink(config.sinks.console));
+  if (config.sinks.file.enabled) sinks.push(createFileSink(config.sinks.file));
+  if (config.sinks.telemetry.enabled) sinks.push(createTelemetrySink(config.sinks.telemetry));
+
+  function emit(level: LogLevel, prefix: string, message: string, data?: Record<string, unknown>): void {
+    const record: LogRecord = {
+      time: new Date().toISOString(),
+      level,
+      prefix,
+      message,
+      ...(data ? { data } : {}),
+    };
+    const recordPriority = LEVEL_PRIORITY[level];
+    for (const sink of sinks) {
+      if (recordPriority <= LEVEL_PRIORITY[sink.level]) {
+        try {
+          sink.write(record);
+        } catch {
+          // Per contract, sinks swallow their own errors; belt-and-suspenders here.
+        }
+      }
+    }
+  }
+
+  return {
+    error: (prefix, message, data) => emit("error", prefix, message, data),
+    warn: (prefix, message, data) => emit("warn", prefix, message, data),
+    info: (prefix, message, data) => emit("info", prefix, message, data),
+    debug: (prefix, message, data) => emit("debug", prefix, message, data),
+  };
+}
+
+// Default module-level logger resolved from process.env.
+export const log: Logger = createLogger(resolveConfig(process.env));

package/server/system/logger/rotation.ts

@@ -0,0 +1,37 @@
+import { mkdir, readdir, unlink } from "fs/promises";
+import path from "path";
+
+export function dailyFileName(date: Date): string {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `server-${year}-${month}-${day}.log`;
+}
+
+const LOG_FILENAME_RE = /^server-\d{4}-\d{2}-\d{2}\.log$/;
+
+export async function ensureDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+// List log files in `dir`, newest first (by file name — our names are
+// ISO-sortable so string desc = chronological desc).
+export async function listLogFiles(dir: string): Promise<string[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((fileName) => LOG_FILENAME_RE.test(fileName))
+    .sort()
+    .reverse();
+}
+
+export async function enforceMaxFiles(dir: string, maxFiles: number): Promise<void> {
+  if (maxFiles <= 0) return;
+  const files = await listLogFiles(dir);
+  const toDelete = files.slice(maxFiles);
+  await Promise.all(toDelete.map((fileName) => unlink(path.join(dir, fileName)).catch(() => {})));
+}

package/server/system/logger/sinks.ts

@@ -0,0 +1,101 @@
+import { appendFile } from "fs/promises";
+import path from "path";
+import type { ConsoleSinkConfig, FileSinkConfig, TelemetrySinkConfig } from "./config.js";
+import { formatJson, formatText } from "./formatters.js";
+import { dailyFileName, enforceMaxFiles, ensureDir } from "./rotation.js";
+import type { Formatter, LogRecord, Sink } from "./types.js";
+
+function pickFormatter(kind: "text" | "json"): Formatter {
+  return kind === "json" ? formatJson : formatText;
+}
+
+export function createConsoleSink(config: ConsoleSinkConfig): Sink {
+  const fmt = pickFormatter(config.format);
+  return {
+    name: "console",
+    level: config.level,
+    write(record: LogRecord) {
+      const line = fmt(record) + "\n";
+      const stream = record.level === "error" || record.level === "warn" ? process.stderr : process.stdout;
+      stream.write(line);
+    },
+  };
+}
+
+export interface FileSinkDeps {
+  now?: () => Date;
+  writeLine?: (filePath: string, line: string) => Promise<void>;
+  onError?: (err: unknown) => void;
+}
+
+// Factory for the rotating file sink. `deps` is only used by tests to
+// inject a fake clock and an in-memory writer.
+export function createFileSink(config: FileSinkConfig, deps: FileSinkDeps = {}): Sink {
+  const now = deps.now ?? (() => new Date());
+  const writeLine = deps.writeLine ?? ((filePath: string, line: string) => appendFile(filePath, line, "utf-8"));
+  const onError =
+    deps.onError ??
+    ((err: unknown) => {
+      // Fallback — never throw back into the caller.
+      console.error("[logger] file sink error:", err);
+    });
+
+  const fmt = pickFormatter(config.format);
+  let currentDateKey = "";
+  let currentPath = "";
+  // Per-sink write queue: chains all pending I/O so rotations can't
+  // interleave with a previous write.
+  let queue: Promise<void> = Promise.resolve();
+
+  function enqueue(operation: () => Promise<void>): void {
+    queue = queue.then(operation).catch(onError);
+  }
+
+  function dateKey(date: Date): string {
+    return `${date.getUTCFullYear()}-${date.getUTCMonth()}-${date.getUTCDate()}`;
+  }
+
+  function maybeRotate(currentDate: Date): boolean {
+    const key = dateKey(currentDate);
+    if (key === currentDateKey) return false;
+    currentDateKey = key;
+    currentPath = path.join(config.dir, dailyFileName(currentDate));
+    enqueue(async () => {
+      await ensureDir(config.dir);
+    });
+    return true;
+  }
+
+  return {
+    name: "file",
+    level: config.level,
+    write(record: LogRecord) {
+      const nowDate = now();
+      const rotated = maybeRotate(nowDate);
+      const line = fmt(record) + "\n";
+      const filePath = currentPath;
+      enqueue(() => writeLine(filePath, line));
+      // Enforce retention AFTER the write so maxFiles counts include
+      // the file we just touched. Enforcing before rotation would
+      // leave N-1 existing files plus the fresh one (off-by-one).
+      if (rotated) {
+        enqueue(() => enforceMaxFiles(config.dir, config.rotation.maxFiles));
+      }
+    },
+    flush() {
+      return queue;
+    },
+  };
+}
+
+// Telemetry sink is a placeholder for a future remote-shipping
+// implementation. Keeping the interface here so wiring is ready.
+export function createTelemetrySink(config: TelemetrySinkConfig): Sink {
+  return {
+    name: "telemetry",
+    level: config.level,
+    write(__record: LogRecord) {
+      // no-op until a transport is added
+    },
+  };
+}

package/server/system/logger/types.ts

@@ -0,0 +1,29 @@
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+export type LogFormat = "text" | "json";
+
+// Numeric priorities for level filtering. Lower = more important.
+export const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+export interface LogRecord {
+  time: string;
+  level: LogLevel;
+  prefix: string;
+  message: string;
+  data?: Record<string, unknown>;
+}
+
+export interface Sink {
+  name: string;
+  level: LogLevel;
+  write(record: LogRecord): void;
+  // Drains any pending async I/O. Tests call this; production can ignore.
+  flush?(): Promise<void>;
+}
+
+export type Formatter = (record: LogRecord) => string;

package/server/utils/date.ts

@@ -0,0 +1,57 @@
+// Shared date-formatting and date-validation helpers. Previously
+// scattered across workspace/journal/paths.ts, journal/indexFile.ts,
+// and workspace/tool-trace/writeSearch.ts.
+
+/**
+ * YYYY-MM-DD in the LOCAL timezone. Used for journal daily paths
+ * and human-facing date labels — "what did I do on 2026-04-11"
+ * is a wall-clock question, not a UTC question.
+ */
+export function toLocalIsoDate(input: Date | number): string {
+  const d = typeof input === "number" ? new Date(input) : input;
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * YYYY-MM-DD in UTC. Used for tool-trace search directories and
+ * any context where the date must not shift with the server's
+ * local timezone.
+ */
+export function toUtcIsoDate(ts: Date): string {
+  const y = ts.getUTCFullYear();
+  const m = String(ts.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(ts.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+/**
+ * Trim an ISO timestamp string to its YYYY-MM-DD date prefix.
+ * Example: "2026-04-11T08:30:00Z" → "2026-04-11".
+ */
+export function isoDateOnly(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+/**
+ * Strict validation of a YYYY-MM-DD string without regex —
+ * checks length, separator positions, and numeric segments.
+ * Does NOT validate month/day ranges (Feb 30 passes); that's the
+ * caller's or LLM's responsibility.
+ */
+export function isValidIsoDate(s: string): boolean {
+  if (s.length !== 10) return false;
+  if (s[4] !== "-" || s[7] !== "-") return false;
+  return isNumeric(s.slice(0, 4)) && isNumeric(s.slice(5, 7)) && isNumeric(s.slice(8, 10));
+}
+
+function isNumeric(s: string): boolean {
+  if (s.length === 0) return false;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code < 48 || code > 57) return false;
+  }
+  return true;
+}

package/server/utils/errors.ts

@@ -0,0 +1,7 @@
+// Shared error helpers. Use `errorMessage(err)` instead of inlining
+// `err instanceof Error ? err.message : String(err)` — searching for
+// one canonical helper is easier than grepping for the inline form.
+
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/server/utils/fetch.ts

@@ -0,0 +1,27 @@
+// Helpers for server-side fetch() calls. The MCP stdio bridge
+// (`server/agent/mcp-server.ts`) makes multiple fetch calls to
+// the host Express server and repeated the same error-extraction
+// pattern at every call site.
+
+import { isRecord } from "./types.js";
+
+/**
+ * Extract a human-readable error string from a non-ok fetch Response.
+ *
+ * Tries to parse the body as `{ error: string }` (the shape every
+ * MulmoClaude `/api/*` endpoint returns on failure). Falls back to
+ * `"HTTP <status>"` when the body isn't JSON, isn't a plain object,
+ * or doesn't contain an `error` string field.
+ */
+export async function extractFetchError(res: Response): Promise<string> {
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+  if (isRecord(body) && typeof body.error === "string") {
+    return body.error;
+  }
+  return `HTTP ${res.status}`;
+}

package/server/utils/files/atomic.ts

@@ -0,0 +1,125 @@
+// Atomic file-write primitives. rename(2) is atomic on POSIX; Node's
+// Windows implementation falls back to copy+unlink which is still
+// safer than truncating the target in place. Readers always see
+// either the old file or the new file — never a half-written one.
+//
+// Moved from server/utils/file.ts (issue #366 Phase 1). The old
+// file re-exports these for backwards compat.
+
+import fs from "fs";
+import path from "path";
+import { randomUUID } from "crypto";
+
+export interface WriteAtomicOptions {
+  /** File mode for the final file (e.g. `0o600` for secrets). */
+  mode?: number;
+  /**
+   * If true, append a randomUUID to the tmp filename to avoid
+   * collisions at the OS level when multiple writers target the same
+   * final path concurrently (e.g. chat-index has this concern).
+   * Default false — a single `${path}.tmp` is fine for most callers.
+   */
+  uniqueTmp?: boolean;
+}
+
+// ── Windows rename retry ────────────────────────────────────────
+//
+// On Windows, `rename` (MoveFileEx with MOVEFILE_REPLACE_EXISTING) can
+// transiently fail with EPERM or EBUSY when antivirus / Search
+// Indexer / Defender momentarily holds a handle on the tmp file or
+// destination file. The failure window is tiny (usually <100ms) and
+// the rename succeeds on a retry.
+//
+// On POSIX, `rename` is atomic and overwrites unconditionally. EPERM
+// there means a real permission problem (read-only filesystem, sticky
+// bit, cross-device link) — retrying wouldn't help and would only add
+// latency before the inevitable throw. So the retry loop is gated to
+// Windows.
+const IS_WINDOWS = process.platform === "win32";
+const RENAME_RETRY_DELAYS_MS = [30, 100, 300] as const;
+
+function hasErrnoCode(err: unknown): err is { code: string } {
+  return typeof err === "object" && err !== null && "code" in err && typeof (err as { code: unknown }).code === "string";
+}
+
+function isTransientRenameError(err: unknown): boolean {
+  if (!IS_WINDOWS || !hasErrnoCode(err)) return false;
+  return err.code === "EPERM" || err.code === "EBUSY" || err.code === "EACCES";
+}
+
+async function renameWithWindowsRetry(from: string, to: string): Promise<void> {
+  for (const delayMs of RENAME_RETRY_DELAYS_MS) {
+    try {
+      await fs.promises.rename(from, to);
+      return;
+    } catch (err) {
+      if (!isTransientRenameError(err)) throw err;
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+  }
+  // Final attempt — let any error propagate.
+  await fs.promises.rename(from, to);
+}
+
+// Sync sleep that parks the thread instead of burning CPU. Only
+// invoked on the transient-Windows-rename path, so the total worst-
+// case block is the sum of RENAME_RETRY_DELAYS_MS (~430ms) and only
+// triggers under AV/indexer contention.
+const SYNC_SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms: number): void {
+  Atomics.wait(SYNC_SLEEP_BUF, 0, 0, ms);
+}
+
+function renameSyncWithWindowsRetry(from: string, to: string): void {
+  for (const delayMs of RENAME_RETRY_DELAYS_MS) {
+    try {
+      fs.renameSync(from, to);
+      return;
+    } catch (err) {
+      if (!isTransientRenameError(err)) throw err;
+      sleepSync(delayMs);
+    }
+  }
+  fs.renameSync(from, to);
+}
+
+/**
+ * Write `content` to `filePath` atomically. The parent directory is
+ * created if missing. The tmp file is cleaned up on failure so a
+ * crashed partial write can't wedge the next try.
+ */
+export async function writeFileAtomic(filePath: string, content: string, opts: WriteAtomicOptions = {}): Promise<void> {
+  const tmp = opts.uniqueTmp ? `${filePath}.${randomUUID()}.tmp` : `${filePath}.tmp`;
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+  try {
+    await fs.promises.writeFile(tmp, content, {
+      encoding: "utf-8",
+      mode: opts.mode,
+    });
+    await renameWithWindowsRetry(tmp, filePath);
+  } catch (err) {
+    await fs.promises.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Synchronous atomic write for callers that need it (e.g. server
+ * startup, config saves that must complete before the next line).
+ * Same contract as `writeFileAtomic` but blocking.
+ */
+export function writeFileAtomicSync(filePath: string, content: string, opts: WriteAtomicOptions = {}): void {
+  const tmp = opts.uniqueTmp ? `${filePath}.${randomUUID()}.tmp` : `${filePath}.tmp`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  try {
+    fs.writeFileSync(tmp, content, { encoding: "utf-8", mode: opts.mode });
+    renameSyncWithWindowsRetry(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      // best-effort cleanup
+    }
+    throw err;
+  }
+}

package/server/utils/files/html-io.ts

@@ -0,0 +1,20 @@
+// Domain I/O: HTML scratch buffer
+//   artifacts/html-scratch/current.html
+//
+// Optional `root` for test DI.
+
+import path from "node:path";
+import { WORKSPACE_DIRS } from "../../workspace/paths.js";
+import { workspacePath } from "../../workspace/paths.js";
+import { readTextUnder, writeTextUnder } from "./workspace-io.js";
+
+const HTML_REL = path.posix.join(WORKSPACE_DIRS.html, "current.html");
+const root = (r?: string) => r ?? workspacePath;
+
+export async function readCurrentHtml(r?: string): Promise<string | null> {
+  return readTextUnder(root(r), HTML_REL);
+}
+
+export async function writeCurrentHtml(html: string, r?: string): Promise<void> {
+  await writeTextUnder(root(r), HTML_REL, html);
+}

package/server/utils/files/image-store.ts

@@ -0,0 +1,66 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+import { WORKSPACE_DIRS, WORKSPACE_PATHS } from "../../workspace/paths.js";
+import { resolveWithinRoot } from "./safe.js";
+
+const IMAGES_DIR = WORKSPACE_PATHS.images;
+
+// Cached realpath of the images directory. resolveWithinRoot requires
+// its root argument to be a realpath so symlinks are handled correctly.
+let imagesDirReal: string | null = null;
+
+async function ensureImagesDir(): Promise<string> {
+  if (imagesDirReal) return imagesDirReal;
+  await fs.mkdir(IMAGES_DIR, { recursive: true });
+  imagesDirReal = await fs.realpath(IMAGES_DIR);
+  return imagesDirReal;
+}
+
+// Resolve a workspace-relative image path (e.g. "images/abc123.png")
+// into an absolute path that is guaranteed to be inside the images
+// directory. Throws on traversal attempts or non-existent files.
+async function safeResolve(relativePath: string): Promise<string> {
+  const root = await ensureImagesDir();
+  // Strip the leading "images/" prefix so the caller can pass either
+  // "images/abc.png" (the stored form) or just "abc.png".
+  const name = relativePath.replace(new RegExp(`^${WORKSPACE_DIRS.images}/`), "");
+  const result = resolveWithinRoot(root, name);
+  if (!result) {
+    throw new Error(`path traversal rejected: ${relativePath}`);
+  }
+  return result;
+}
+
+/** Save raw base64 (no data URI prefix) as a PNG file. Returns the workspace-relative path. */
+export async function saveImage(base64Data: string): Promise<string> {
+  await ensureImagesDir();
+  const id = crypto.randomUUID().replace(/-/g, "").slice(0, 16);
+  const filename = `${id}.png`;
+  const absPath = path.join(IMAGES_DIR, filename);
+  await fs.writeFile(absPath, Buffer.from(base64Data, "base64"));
+  return path.posix.join(WORKSPACE_DIRS.images, filename);
+}
+
+/** Overwrite an existing image file. The relativePath must start with "images/". */
+export async function overwriteImage(relativePath: string, base64Data: string): Promise<void> {
+  const absPath = await safeResolve(relativePath);
+  await fs.writeFile(absPath, Buffer.from(base64Data, "base64"));
+}
+
+/** Read an image file and return raw base64 (no data URI prefix). */
+export async function loadImageBase64(relativePath: string): Promise<string> {
+  const absPath = await safeResolve(relativePath);
+  const buf = await fs.readFile(absPath);
+  return buf.toString("base64");
+}
+
+/** Convert a data URI to raw base64. */
+export function stripDataUri(dataUri: string): string {
+  return dataUri.replace(/^data:image\/[^;]+;base64,/, "");
+}
+
+/** Check if a string is a file reference (not a data URI). */
+export function isImagePath(value: string): boolean {
+  return value.startsWith(`${WORKSPACE_DIRS.images}/`) && value.endsWith(".png");
+}