@xfxstudio/claworld 2026.4.21-testing.2 → 2026.4.22-testing.4

package/src/openclaw/runtime/working-memory.js

@@ -0,0 +1,702 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+
+export const CLAWORLD_WORKING_MEMORY_DIR = '.claworld';
+export const CLAWORLD_CONTEXT_DIR = 'context';
+export const CLAWORLD_JOURNAL_DIR = 'journal';
+export const CLAWORLD_REPORTS_DIR = 'reports';
+
+export const CLAWORLD_WORKING_MEMORY_FILES = Object.freeze({
+  index: 'INDEX.md',
+  now: 'context/NOW.md',
+  profile: 'context/PROFILE.md',
+  memory: 'context/MEMORY.md',
+});
+
+export const CLAWORLD_WORKING_MEMORY_DIRECTORIES = Object.freeze([
+  CLAWORLD_WORKING_MEMORY_DIR,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_CONTEXT_DIR}`,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_JOURNAL_DIR}`,
+  `${CLAWORLD_WORKING_MEMORY_DIR}/${CLAWORLD_REPORTS_DIR}`,
+]);
+
+export const CLAWORLD_MAINTENANCE_RUN_TYPES = Object.freeze({
+  L1_NOW_REFRESH: 'L1_NOW_REFRESH',
+  L2_MEMORY_PROFILE_REVIEW: 'L2_MEMORY_PROFILE_REVIEW',
+  L2_PROFILE_MEMORY_REVIEW: 'L2_MEMORY_PROFILE_REVIEW',
+});
+
+const MAINTENANCE_RUN_TYPE_ALIASES = Object.freeze({
+  L1_NOW_REFRESH: CLAWORLD_MAINTENANCE_RUN_TYPES.L1_NOW_REFRESH,
+  L2_MEMORY_PROFILE_REVIEW: CLAWORLD_MAINTENANCE_RUN_TYPES.L2_MEMORY_PROFILE_REVIEW,
+  L2_PROFILE_MEMORY_REVIEW: CLAWORLD_MAINTENANCE_RUN_TYPES.L2_MEMORY_PROFILE_REVIEW,
+});
+
+const FILE_TARGET_ALIASES = Object.freeze({
+  INDEX: CLAWORLD_WORKING_MEMORY_FILES.index,
+  'INDEX.md': CLAWORLD_WORKING_MEMORY_FILES.index,
+  NOW: CLAWORLD_WORKING_MEMORY_FILES.now,
+  'NOW.md': CLAWORLD_WORKING_MEMORY_FILES.now,
+  PROFILE: CLAWORLD_WORKING_MEMORY_FILES.profile,
+  'PROFILE.md': CLAWORLD_WORKING_MEMORY_FILES.profile,
+});
+
+const L1_ALLOWED_TARGETS = new Set([
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+]);
+
+const L2_ALLOWED_TARGETS = new Set([
+  CLAWORLD_WORKING_MEMORY_FILES.now,
+  CLAWORLD_WORKING_MEMORY_FILES.profile,
+  CLAWORLD_WORKING_MEMORY_FILES.memory,
+]);
+
+const MAX_EVENT_EXCERPT_CHARS = 600;
+const MAX_MEMORY_SLICE_CHARS = 4000;
+
+export function buildClaworldContextPointer() {
+  return [
+    '# Claworld Context Pointer',
+    '',
+    'Claworld working memory is available at `.claworld/INDEX.md`.',
+    'When the user asks about Claworld, worlds, A2A conversations, people met in Claworld, activity opportunities, or previous Claworld progress, read `.claworld/INDEX.md` first.',
+    'Do not load raw Claworld transcripts by default.',
+  ].join('\n');
+}
+
+export function buildClaworldWorkingMemoryTemplates() {
+  return {
+    [CLAWORLD_WORKING_MEMORY_FILES.index]: [
+      '# Claworld Working Memory',
+      '',
+      'This directory is the workspace-local private working memory for Claworld.',
+      'Read this file first when the user asks about Claworld, worlds, A2A conversations, people met in Claworld, activity opportunities, or previous Claworld progress.',
+      '',
+      '## Read Order',
+      '- `context/NOW.md` for current Claworld focus, active worlds, and recent progress.',
+      '- `context/MEMORY.md` for durable Claworld facts and decisions.',
+      '- `context/PROFILE.md` for user preferences and profile hints relevant to Claworld.',
+      '- `journal/YYYY-MM.md` for append-only summarized events.',
+      '- `reports/` for generated local progress reports.',
+      '',
+      '## Rules',
+      '- Do not load raw Claworld transcripts by default.',
+      '- Do not write this content into global `MEMORY.md` automatically.',
+      '- Prefer short summaries and references over raw chat history.',
+      '- `context/PROFILE.md` and `context/MEMORY.md` are updated only by L2 maintenance review.',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.now]: [
+      '# Claworld Now',
+      '',
+      '## Current Focus',
+      '- No active Claworld focus recorded yet.',
+      '',
+      '## Recent Activity',
+      '- No recent Claworld activity recorded yet.',
+      '',
+      '## Open Questions',
+      '- none',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.profile]: [
+      '# Claworld Profile',
+      '',
+      '## Stable Preferences',
+      '- No Claworld-specific preferences recorded yet.',
+      '',
+      '## People And Context',
+      '- No Claworld people context recorded yet.',
+      '',
+    ].join('\n'),
+    [CLAWORLD_WORKING_MEMORY_FILES.memory]: [
+      '# Claworld Memory',
+      '',
+      '## Durable Facts',
+      '- No durable Claworld facts recorded yet.',
+      '',
+      '## Decisions',
+      '- No durable Claworld decisions recorded yet.',
+      '',
+    ].join('\n'),
+  };
+}
+
+export function buildClaworldWorkingMemoryFileSpecs() {
+  const templates = buildClaworldWorkingMemoryTemplates();
+  return Object.entries(templates).map(([relativePath, content]) => ({
+    relativePath: `${CLAWORLD_WORKING_MEMORY_DIR}/${relativePath}`,
+    workingMemoryRelativePath: relativePath,
+    policy: 'durable',
+    content,
+  }));
+}
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function expandUserPath(inputPath, homeDir = os.homedir()) {
+  const text = normalizeText(inputPath, null);
+  if (!text) return null;
+  if (text === '~') return homeDir;
+  if (text.startsWith('~/') || text.startsWith('~\\')) {
+    return path.join(homeDir, text.slice(2));
+  }
+  return text;
+}
+
+export function resolveClaworldWorkspaceRoot(options = {}, homeDir = os.homedir()) {
+  const source = typeof options === 'string'
+    ? options
+    : options?.workspaceRoot
+      ?? options?.workspacePath
+      ?? options?.workspaceDir
+      ?? options?.workspace
+      ?? options?.cwd
+      ?? process.cwd();
+  return path.resolve(expandUserPath(source, homeDir) || process.cwd());
+}
+
+export function resolveClaworldMemoryRoot(options = {}, homeDir = os.homedir()) {
+  return path.join(resolveClaworldWorkspaceRoot(options, homeDir), CLAWORLD_WORKING_MEMORY_DIR);
+}
+
+async function readTextIfPresent(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function atomicWriteText(filePath, content, {
+  backup = true,
+  rejectEmptyOverwrite = true,
+} = {}) {
+  const nextContent = String(content ?? '');
+  const currentContent = await readTextIfPresent(filePath);
+  if (
+    rejectEmptyOverwrite
+    && currentContent != null
+    && normalizeText(currentContent, null)
+    && !normalizeText(nextContent, null)
+  ) {
+    throw new Error(`Refusing to overwrite non-empty Claworld memory file with empty content: ${filePath}`);
+  }
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  if (backup && currentContent != null && currentContent !== nextContent) {
+    await fs.writeFile(`${filePath}.bak`, currentContent, 'utf8');
+  }
+
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  await fs.writeFile(tempPath, nextContent, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+export async function ensureClaworldWorkingMemory(options = {}, ensureOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, ensureOptions.homeDir || os.homedir());
+  const memoryRoot = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR);
+  const directories = CLAWORLD_WORKING_MEMORY_DIRECTORIES.map((relativePath) => ({
+    relativePath,
+    absolutePath: path.join(workspaceRoot, relativePath),
+  }));
+  const files = buildClaworldWorkingMemoryFileSpecs().map((file) => ({
+    ...file,
+    absolutePath: path.join(workspaceRoot, file.relativePath),
+  }));
+  const actions = [];
+
+  if (ensureOptions.dryRun === true) {
+    for (const directory of directories) {
+      actions.push(`mkdir -p ${directory.absolutePath}`);
+    }
+    for (const file of files) {
+      actions.push(`seed ${file.absolutePath} if missing`);
+    }
+    return {
+      ok: true,
+      dryRun: true,
+      workspaceRoot,
+      memoryRoot,
+      directories,
+      files,
+      actions,
+    };
+  }
+
+  for (const directory of directories) {
+    await fs.mkdir(directory.absolutePath, { recursive: true });
+    actions.push(`ensured ${directory.absolutePath}`);
+  }
+
+  for (const file of files) {
+    const currentContent = await readTextIfPresent(file.absolutePath);
+    if (currentContent == null) {
+      await atomicWriteText(file.absolutePath, file.content, {
+        backup: false,
+        rejectEmptyOverwrite: false,
+      });
+      actions.push(`created ${file.absolutePath}`);
+    } else {
+      actions.push(`preserved ${file.absolutePath}`);
+    }
+  }
+
+  return {
+    ok: true,
+    dryRun: false,
+    workspaceRoot,
+    memoryRoot,
+    directories,
+    files,
+    actions,
+  };
+}
+
+function toIsoTimestamp(value = null) {
+  const date = value instanceof Date ? value : new Date(value || Date.now());
+  if (Number.isNaN(date.getTime())) return new Date().toISOString();
+  return date.toISOString();
+}
+
+function toMonthKey(timestamp) {
+  return toIsoTimestamp(timestamp).slice(0, 7);
+}
+
+function truncateText(value, maxChars = MAX_EVENT_EXCERPT_CHARS) {
+  const text = normalizeText(value, '');
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+
+function flattenInline(value) {
+  return truncateText(String(value ?? '').replace(/\s+/g, ' ').trim());
+}
+
+export function buildClaworldMaintenanceEvent(input = {}) {
+  const toolName = normalizeText(input.toolName, null);
+  const source = normalizeText(input.source, toolName ? 'claworld_tool' : 'claworld_runtime');
+  const kind = normalizeText(input.kind, toolName || 'milestone');
+  const timestamp = toIsoTimestamp(input.timestamp);
+  const summary = normalizeText(input.summary, toolName ? `${toolName} succeeded.` : 'Claworld milestone recorded.');
+  const refs = input.refs && typeof input.refs === 'object' && !Array.isArray(input.refs)
+    ? Object.fromEntries(
+      Object.entries(input.refs)
+        .map(([key, value]) => [key, normalizeText(value, null)])
+        .filter(([, value]) => value != null),
+    )
+    : {};
+  return {
+    id: normalizeText(input.id, `${source}:${kind}:${timestamp}`),
+    timestamp,
+    source,
+    kind,
+    summary,
+    excerpt: truncateText(input.excerpt || ''),
+    refs,
+  };
+}
+
+export function buildClaworldRuntimeMaintenanceEvent(input = {}) {
+  return buildClaworldMaintenanceEvent({
+    ...input,
+    source: normalizeText(input.source, 'claworld_runtime'),
+    kind: normalizeText(input.kind, 'milestone'),
+  });
+}
+
+function parseToolResultPayload(result) {
+  if (!result || typeof result !== 'object') return null;
+  if (result.payload && typeof result.payload === 'object' && !Array.isArray(result.payload)) {
+    return result.payload;
+  }
+  const textContent = Array.isArray(result.content)
+    ? result.content.find((entry) => entry?.type === 'text' && typeof entry.text === 'string')?.text
+    : null;
+  if (!textContent) return null;
+  try {
+    const parsed = JSON.parse(textContent);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function compactResultPayload(payload = {}) {
+  const keys = [
+    'status',
+    'tool',
+    'accountId',
+    'worldId',
+    'displayName',
+    'chatRequestId',
+    'conversationKey',
+    'candidateId',
+    'feedbackId',
+    'nextAction',
+    'requiredAction',
+    'summary',
+    'message',
+  ];
+  const compact = {};
+  for (const key of keys) {
+    const value = normalizeText(payload[key], null);
+    if (value != null) compact[key] = value;
+  }
+  return compact;
+}
+
+export function buildClaworldToolMaintenanceEvent({
+  toolName,
+  params = {},
+  result = null,
+  timestamp = null,
+} = {}) {
+  const normalizedToolName = normalizeText(toolName, null);
+  if (!normalizedToolName || !normalizedToolName.startsWith('claworld_')) return null;
+  const payload = parseToolResultPayload(result) || {};
+  const compactPayload = compactResultPayload(payload);
+  const refs = {
+    accountId: params.accountId || payload.accountId,
+    worldId: params.worldId || payload.worldId,
+    chatRequestId: params.chatRequestId || payload.chatRequestId,
+    conversationKey: params.conversationKey || payload.conversationKey,
+    candidateId: params.candidateId || payload.candidateId,
+    agentCode: params.agentCode || payload.agentCode,
+  };
+  return buildClaworldMaintenanceEvent({
+    source: 'claworld_tool',
+    kind: normalizedToolName,
+    toolName: normalizedToolName,
+    timestamp,
+    refs,
+    summary: `${normalizedToolName} succeeded.`,
+    excerpt: Object.keys(compactPayload).length > 0
+      ? JSON.stringify(compactPayload)
+      : null,
+  });
+}
+
+function formatRefs(refs = {}) {
+  return Object.entries(refs)
+    .filter(([, value]) => value != null)
+    .map(([key, value]) => `${key}=${flattenInline(value)}`)
+    .join(', ');
+}
+
+export async function appendClaworldJournalEvent(options = {}, event = {}, appendOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, appendOptions.homeDir || os.homedir());
+  await ensureClaworldWorkingMemory(workspaceRoot, appendOptions);
+  const normalizedEvent = buildClaworldMaintenanceEvent(event);
+  const monthKey = toMonthKey(normalizedEvent.timestamp);
+  const journalPath = path.join(
+    workspaceRoot,
+    CLAWORLD_WORKING_MEMORY_DIR,
+    CLAWORLD_JOURNAL_DIR,
+    `${monthKey}.md`,
+  );
+  const currentContent = await readTextIfPresent(journalPath);
+  const refsLine = formatRefs(normalizedEvent.refs);
+  const entry = [
+    `## ${normalizedEvent.timestamp} - ${normalizedEvent.kind}`,
+    `- Source: ${normalizedEvent.source}`,
+    `- Summary: ${flattenInline(normalizedEvent.summary)}`,
+    normalizedEvent.excerpt ? `- Excerpt: ${flattenInline(normalizedEvent.excerpt)}` : null,
+    refsLine ? `- Refs: ${refsLine}` : null,
+    '',
+  ].filter((line) => line != null).join('\n');
+  if (currentContent == null) {
+    await atomicWriteText(journalPath, `# Claworld Journal ${monthKey}\n\n${entry}`, {
+      backup: false,
+      rejectEmptyOverwrite: false,
+    });
+  } else {
+    await fs.appendFile(journalPath, `${currentContent.endsWith('\n') ? '' : '\n'}${entry}`, 'utf8');
+  }
+  return {
+    ok: true,
+    journalPath,
+    event: normalizedEvent,
+  };
+}
+
+export async function readClaworldWorkingMemory(options = {}, readOptions = {}) {
+  const workspaceRoot = resolveClaworldWorkspaceRoot(options, readOptions.homeDir || os.homedir());
+  const maxCharsPerFile = Number.isInteger(readOptions.maxCharsPerFile) && readOptions.maxCharsPerFile > 0
+    ? readOptions.maxCharsPerFile
+    : MAX_MEMORY_SLICE_CHARS;
+  const slices = {};
+  for (const relativePath of Object.values(CLAWORLD_WORKING_MEMORY_FILES)) {
+    const absolutePath = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR, relativePath);
+    const content = await readTextIfPresent(absolutePath);
+    slices[relativePath] = content == null
+      ? null
+      : {
+        content: content.length > maxCharsPerFile ? content.slice(0, maxCharsPerFile) : content,
+        truncated: content.length > maxCharsPerFile,
+      };
+  }
+  return {
+    workspaceRoot,
+    memoryRoot: path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR),
+    slices,
+  };
+}
+
+function normalizePatchOperation(operation) {
+  const normalized = normalizeText(operation, 'replace');
+  if (normalized === 'replace' || normalized === 'append_section' || normalized === 'no_op') {
+    return normalized;
+  }
+  throw new Error(`Unsupported Claworld maintenance patch operation: ${normalized}`);
+}
+
+function normalizeMaintenanceRunType(runType) {
+  const normalized = normalizeText(runType, null);
+  const alias = MAINTENANCE_RUN_TYPE_ALIASES[normalized];
+  if (alias) return alias;
+  throw new Error(`Unsupported Claworld maintenance run type: ${runType}`);
+}
+
+function stripClaworldPrefix(rawTarget) {
+  let target = String(rawTarget || '').replace(/\\/g, '/').trim();
+  target = target.replace(/^\/+/, '');
+  if (target.startsWith(`${CLAWORLD_WORKING_MEMORY_DIR}/`)) {
+    target = target.slice(CLAWORLD_WORKING_MEMORY_DIR.length + 1);
+  }
+  return target;
+}
+
+function normalizePatchTarget(rawTarget) {
+  const stripped = stripClaworldPrefix(rawTarget);
+  const aliasTarget = FILE_TARGET_ALIASES[stripped] || null;
+  if (aliasTarget) return aliasTarget;
+  if (stripped === 'MEMORY.md') {
+    throw new Error('Global MEMORY.md is not a valid Claworld working-memory target; use context/MEMORY.md.');
+  }
+  const normalized = path.posix.normalize(stripped);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.posix.isAbsolute(normalized)) {
+    throw new Error(`Invalid Claworld maintenance patch target: ${rawTarget}`);
+  }
+  return normalized;
+}
+
+function isAllowedTarget(runType, target) {
+  if (target.startsWith(`${CLAWORLD_JOURNAL_DIR}/`) || target.startsWith(`${CLAWORLD_REPORTS_DIR}/`)) {
+    return true;
+  }
+  if (runType === CLAWORLD_MAINTENANCE_RUN_TYPES.L1_NOW_REFRESH) {
+    return L1_ALLOWED_TARGETS.has(target);
+  }
+  if (runType === CLAWORLD_MAINTENANCE_RUN_TYPES.L2_MEMORY_PROFILE_REVIEW) {
+    return L2_ALLOWED_TARGETS.has(target);
+  }
+  return false;
+}
+
+function assertAllowedTarget(runType, target) {
+  if (!isAllowedTarget(runType, target)) {
+    throw new Error(`Claworld maintenance run ${runType} cannot write target ${target}`);
+  }
+}
+
+function normalizeReportPatch(report, index) {
+  const filename = normalizeText(report?.filename ?? report?.name, `report-${index + 1}.md`);
+  const normalizedFilename = path.posix.basename(filename.endsWith('.md') ? filename : `${filename}.md`);
+  return {
+    operation: 'replace',
+    target: `${CLAWORLD_REPORTS_DIR}/${normalizedFilename}`,
+    content: String(report?.md ?? report?.content ?? report?.text ?? ''),
+  };
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function readPatchContent(patch, fieldName) {
+  if (hasOwn(patch, 'content')) return patch.content;
+  if (hasOwn(patch, 'md')) return patch.md;
+  if (hasOwn(patch, 'text')) return patch.text;
+  throw new Error(`Claworld maintenance FilePatch ${fieldName} requires content for replace or append_section.`);
+}
+
+function normalizeFilePatchValue(value, target, fieldName) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const operation = normalizePatchOperation(value.operation);
+    const normalized = {
+      operation,
+      target,
+      content: operation === 'no_op' ? '' : String(readPatchContent(value, fieldName) ?? ''),
+    };
+    const rationale = normalizeText(value.rationale, null);
+    if (rationale) normalized.rationale = rationale;
+    return normalized;
+  }
+  return {
+    operation: 'replace',
+    target,
+    content: String(value ?? ''),
+  };
+}
+
+export function normalizeClaworldMaintenanceOutput(runType, output = {}, options = {}) {
+  if (!output || typeof output !== 'object' || Array.isArray(output)) {
+    throw new Error('Claworld maintenance output must be an object.');
+  }
+  const normalizedRunType = normalizeMaintenanceRunType(runType);
+  const patches = [];
+  if (Object.prototype.hasOwnProperty.call(output, 'nowMd')) {
+    patches.push(normalizeFilePatchValue(output.nowMd, CLAWORLD_WORKING_MEMORY_FILES.now, 'nowMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'profileMd')) {
+    patches.push(normalizeFilePatchValue(output.profileMd, CLAWORLD_WORKING_MEMORY_FILES.profile, 'profileMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'memoryMd')) {
+    patches.push(normalizeFilePatchValue(output.memoryMd, CLAWORLD_WORKING_MEMORY_FILES.memory, 'memoryMd'));
+  }
+  if (Object.prototype.hasOwnProperty.call(output, 'journalAppendMd')) {
+    const monthKey = toMonthKey(options.timestamp || output.timestamp || Date.now());
+    patches.push({
+      operation: 'append_section',
+      target: `${CLAWORLD_JOURNAL_DIR}/${monthKey}.md`,
+      content: String(output.journalAppendMd ?? ''),
+    });
+  }
+  if (Array.isArray(output.reports)) {
+    output.reports.forEach((report, index) => {
+      patches.push(normalizeReportPatch(report, index));
+    });
+  }
+  if (Array.isArray(output.patches)) {
+    for (const patch of output.patches) {
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new Error('Claworld maintenance patches entries must be FilePatch objects.');
+      }
+      const operation = normalizePatchOperation(patch.operation);
+      patches.push({
+        operation,
+        target: normalizePatchTarget(patch.target ?? patch.path ?? patch.relativePath),
+        content: operation === 'no_op' ? '' : String(readPatchContent(patch, 'patches[]') ?? ''),
+        rationale: normalizeText(patch.rationale, null),
+      });
+    }
+  }
+
+  const normalizedPatches = patches.map((patch) => {
+    const target = normalizePatchTarget(patch.target);
+    const operation = normalizePatchOperation(patch.operation);
+    assertAllowedTarget(normalizedRunType, target);
+    const normalizedPatch = {
+      operation,
+      target,
+      content: String(patch.content ?? ''),
+    };
+    const rationale = normalizeText(patch.rationale, null);
+    if (rationale) normalizedPatch.rationale = rationale;
+    return normalizedPatch;
+  });
+
+  return {
+    runType: normalizedRunType,
+    noOpReason: normalizeText(output.noOpReason, null),
+    patches: normalizedPatches,
+  };
+}
+
+export function validateClaworldMaintenanceOutput(runType, output = {}, options = {}) {
+  return normalizeClaworldMaintenanceOutput(runType, output, options);
+}
+
+async function applyMaintenancePatch(workspaceRoot, patch) {
+  if (patch.operation === 'no_op') {
+    return {
+      operation: patch.operation,
+      target: patch.target,
+      applied: false,
+    };
+  }
+  const absolutePath = path.join(workspaceRoot, CLAWORLD_WORKING_MEMORY_DIR, patch.target);
+  if (patch.operation === 'append_section') {
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    const currentContent = await readTextIfPresent(absolutePath);
+    if (currentContent == null) {
+      const monthKey = path.basename(patch.target, '.md');
+      await atomicWriteText(absolutePath, `# Claworld Journal ${monthKey}\n\n${patch.content}`, {
+        backup: false,
+        rejectEmptyOverwrite: false,
+      });
+    } else {
+      await fs.appendFile(
+        absolutePath,
+        `${currentContent.endsWith('\n') ? '' : '\n'}${patch.content}`,
+        'utf8',
+      );
+    }
+    return {
+      operation: patch.operation,
+      target: patch.target,
+      applied: true,
+    };
+  }
+
+  await atomicWriteText(absolutePath, patch.content, {
+    backup: true,
+    rejectEmptyOverwrite: true,
+  });
+  return {
+    operation: patch.operation,
+    target: patch.target,
+    applied: true,
+  };
+}
+
+export async function runClaworldMemoryMaintenance(runType, requestBundle = {}, options = {}) {
+  const normalizedRunType = normalizeMaintenanceRunType(runType);
+  const workspaceRoot = resolveClaworldWorkspaceRoot(
+    options.workspaceRoot || requestBundle.workspaceRoot || requestBundle.workspaceDir || process.cwd(),
+    options.homeDir || os.homedir(),
+  );
+  await ensureClaworldWorkingMemory(workspaceRoot, options);
+  const workingMemory = await readClaworldWorkingMemory(workspaceRoot, options);
+  const request = {
+    ...requestBundle,
+    runType: normalizedRunType,
+    workspaceRoot,
+    workingMemory,
+  };
+  const output = options.output
+    ?? (typeof options.maintenanceRunner === 'function'
+      ? await options.maintenanceRunner(request)
+      : null);
+  if (!output) {
+    return {
+      ok: true,
+      runType: normalizedRunType,
+      noOpReason: 'no_maintenance_runner',
+      request,
+      applied: [],
+    };
+  }
+  const normalized = validateClaworldMaintenanceOutput(normalizedRunType, output, options);
+  const applied = [];
+  for (const patch of normalized.patches) {
+    applied.push(await applyMaintenancePatch(workspaceRoot, patch));
+  }
+  return {
+    ok: true,
+    runType: normalizedRunType,
+    noOpReason: normalized.noOpReason,
+    request,
+    applied,
+  };
+}