openbot 0.3.0 → 0.3.1

package/src/harness/context.ts

@@ -1,8 +1,16 @@
-import { OpenBotState } from '../app/types.js';
+import { OpenBotEvent, OpenBotState } from '../app/types.js';
 import { Storage } from '../bus/types.js';
 
 /**
  * Represents a piece of context that can be used in a prompt.
+ *
+ * Items flow through the engine in two phases:
+ *   1. Each registered `ContextProvider` emits zero or more items.
+ *   2. Each registered `ContextProcessor` may transform / drop / re-rank
+ *      items (e.g. token-budget enforcement).
+ *
+ * Higher `priority` items appear first in the assembled prompt and are the
+ * last to be dropped under budget pressure.
  */
 export interface ContextItem {
   id: string;
@@ -12,25 +20,33 @@ export interface ContextItem {
   metadata?: Record<string, any>;
 }
 
-/**
- * A provider that can fetch or generate context items.
- */
 export interface ContextProvider {
   name: string;
   provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]>;
 }
 
-/**
- * A processor that can transform or filter context items (e.g., ranking, truncation).
- */
 export interface ContextProcessor {
   name: string;
   process(items: ContextItem[], state: OpenBotState): Promise<ContextItem[]>;
 }
 
 /**
- * The core engine that orchestrates context building.
+ * Cheap, dependency-free token estimator. Roughly char/4 — fine for budget
+ * enforcement; can be swapped for a tokenizer-backed implementation later
+ * without touching providers.
+ */
+export const estimateTokens = (text: string): number =>
+  Math.ceil((text?.length ?? 0) / 4);
+
+/**
+ * Hard cap (in characters) on a single context item. Keeps any one provider
+ * — typically the recent-events feed — from monopolising the prompt budget.
  */
+const ITEM_HARD_CHAR_CAP = 6000;
+
+const truncate = (text: string, maxChars: number): string =>
+  text.length <= maxChars ? text : `${text.slice(0, maxChars)}\n…[truncated]`;
+
 export class ContextEngine {
   private providers: ContextProvider[] = [];
   private processors: ContextProcessor[] = [];
@@ -44,18 +60,18 @@ export class ContextEngine {
   }
 
   async buildContext(state: OpenBotState, storage?: Storage): Promise<string> {
-    // 1. Collect context from all providers
     let items: ContextItem[] = [];
     for (const provider of this.providers) {
       try {
         const providedItems = await provider.provide(state, storage);
-        items.push(...providedItems);
+        for (const item of providedItems) {
+          items.push({ ...item, content: truncate(item.content, ITEM_HARD_CHAR_CAP) });
+        }
       } catch (error) {
         console.warn(`[ContextEngine] Provider ${provider.name} failed:`, error);
       }
     }
 
-    // 2. Run through processors
     for (const processor of this.processors) {
       try {
         items = await processor.process(items, state);
@@ -64,26 +80,29 @@ export class ContextEngine {
       }
     }
 
-    // 3. Format items into a single string
     return items
       .sort((a, b) => b.priority - a.priority)
-      .map(item => item.content)
+      .map((item) => item.content)
       .join('\n\n');
   }
 }
 
 /**
- * Default implementation of a Context Engine with basic providers.
+ * Default context engine. Order of providers is by emit order; final ordering
+ * in the prompt is determined by `priority`. The token-budget processor runs
+ * last so dropping happens after every provider has contributed.
  */
 export function createDefaultContextEngine(): ContextEngine {
   const engine = new ContextEngine();
 
-  // Basic Providers
   engine.registerProvider(new AgentDetailsProvider());
   engine.registerProvider(new ChannelDetailsProvider());
   engine.registerProvider(new ThreadDetailsProvider());
+  engine.registerProvider(new MemoryProvider());
   engine.registerProvider(new RecentEventsProvider());
 
+  engine.registerProcessor(new TokenBudgetProcessor());
+
   return engine;
 }
 
@@ -126,35 +145,149 @@ class ThreadDetailsProvider implements ContextProvider {
   }
 }
 
+/**
+ * Fetches relevant memories (global + active agent + active channel) and
+ * surfaces them at high priority so the LLM treats them as ground truth
+ * rather than chat history.
+ */
+class MemoryProvider implements ContextProvider {
+  name = 'memory';
+  async provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]> {
+    if (!storage?.listMemories) return [];
+
+    try {
+      const scopes = ['global', `agent:${state.agentId}`];
+      if (state.channelId) scopes.push(`channel:${state.channelId}`);
+
+      const records = await storage.listMemories({ scopes, limit: 50 });
+      if (records.length === 0) return [];
+
+      const formatted = records
+        .map((r) => {
+          const tags = r.tags?.length ? ` [${r.tags.join(', ')}]` : '';
+          const scopeLabel = r.scope === 'global' ? 'global' : r.scope;
+          return `- (${scopeLabel}${tags}) ${r.content}`;
+        })
+        .join('\n');
+
+      return [
+        {
+          id: 'memory',
+          type: 'memory',
+          priority: 95,
+          content: `## REMEMBERED FACTS\nThese are durable facts you previously stored with the \`remember\` tool. Trust them unless contradicted by the user. Use \`forget\` to remove ones that are stale.\n\n${formatted}`,
+        },
+      ];
+    } catch (error) {
+      console.warn('[ContextEngine] MemoryProvider failed:', error);
+      return [];
+    }
+  }
+}
+
+/**
+ * Event types we omit from the recent-events context block. They duplicate
+ * information already in the conversation history, are infrastructural
+ * noise, or are too large to be useful as a tail summary.
+ */
+const NOISY_EVENT_PREFIXES = [
+  'agent:invoke',
+  'agent:output',
+  'agent:run',
+  'agent:active-runs',
+  'client:ui',
+  'stream:',
+  'action:storage:get-',
+  'action:storage:patch-',
+];
+
+const MAX_RECENT_EVENTS = 20;
+const MAX_EVENT_DATA_CHARS = 300;
+
+const isNoisyEvent = (event: OpenBotEvent): boolean =>
+  NOISY_EVENT_PREFIXES.some((prefix) => event.type.startsWith(prefix));
+
+const summarizeEvent = (event: OpenBotEvent): string => {
+  const data = (event as { data?: unknown }).data;
+  if (data === undefined) return `- ${event.type}`;
+  let payload: string;
+  try {
+    payload = typeof data === 'string' ? data : JSON.stringify(data);
+  } catch {
+    payload = '[unserialisable]';
+  }
+  if (payload.length > MAX_EVENT_DATA_CHARS) {
+    payload = `${payload.slice(0, MAX_EVENT_DATA_CHARS)}…`;
+  }
+  return `- ${event.type}: ${payload}`;
+};
+
 class RecentEventsProvider implements ContextProvider {
   name = 'recent-events';
   async provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]> {
     if (!storage) return [];
-    const items: ContextItem[] = [];
 
-    // Fetch channel events if no thread, otherwise fetch thread events
     const channelId = state.channelId;
     const threadId = state.threadId;
 
     try {
       const events = await storage.getEvents({ channelId, threadId });
-      if (events.length > 0) {
-        const formattedEvents = events
-          .slice(-20)
-          .map((e) => `- ${e.type}: ${JSON.stringify((e as any).data || {})}`)
-          .join('\n');
-        
-        items.push({
+      const filtered = events.filter((e) => !isNoisyEvent(e));
+      if (filtered.length === 0) return [];
+
+      const formatted = filtered.slice(-MAX_RECENT_EVENTS).map(summarizeEvent).join('\n');
+
+      return [
+        {
           id: threadId ? 'thread-events' : 'channel-events',
           type: 'events',
           priority: 70,
-          content: `## ${threadId ? 'THREAD' : 'CHANNEL'} RECENT ACTIVITIES (events)\n${formattedEvents}`
-        });
-      }
+          content: `## ${threadId ? 'THREAD' : 'CHANNEL'} RECENT ACTIVITIES (events)\n${formatted}`,
+        },
+      ];
     } catch (error) {
-      console.warn(`[ContextEngine] Failed to fetch events:`, error);
+      console.warn('[ContextEngine] Failed to fetch events:', error);
+      return [];
+    }
+  }
+}
+
+/**
+ * Drops the lowest-priority items until the assembled prompt fits within the
+ * token budget. The first item with priority >= `keepFloor` is always kept,
+ * so the agent's own instructions can never be evicted. Stable on ties:
+ * later-emitted items go first.
+ */
+export class TokenBudgetProcessor implements ContextProcessor {
+  name = 'token-budget';
+  /** Soft prompt budget in tokens (matches gpt-4o-mini's reasonable system slice). */
+  static DEFAULT_BUDGET = 8000;
+  /** Items at or above this priority are never dropped. */
+  static KEEP_FLOOR = 100;
+
+  constructor(
+    private budget: number = TokenBudgetProcessor.DEFAULT_BUDGET,
+    private keepFloor: number = TokenBudgetProcessor.KEEP_FLOOR,
+  ) {}
+
+  async process(items: ContextItem[]): Promise<ContextItem[]> {
+    const sorted = [...items].sort((a, b) => b.priority - a.priority);
+    const out: ContextItem[] = [];
+    let used = 0;
+
+    for (const item of sorted) {
+      const cost = estimateTokens(item.content);
+      if (item.priority >= this.keepFloor) {
+        out.push(item);
+        used += cost;
+        continue;
+      }
+      if (used + cost <= this.budget) {
+        out.push(item);
+        used += cost;
+      }
     }
 
-    return items;
+    return out;
   }
 }

package/src/plugins/ai-sdk/runtime.ts

@@ -42,6 +42,78 @@ const asRecord = (value: unknown): Record<string, unknown> =>
     ? (value as Record<string, unknown>)
     : {};
 
+/** Per-message hard cap (in characters) on tool-result payloads we feed back
+ *  to the model. Prevents one huge tool output from eating the context window;
+ *  the original event remains intact in storage. */
+const TOOL_RESULT_MAX_CHARS = 8000;
+
+/** Sliding window: max number of messages we replay to the model on each
+ *  invocation. Older turns stay on disk but are not sent. Keeps both the
+ *  recent prompts and the prompt token budget bounded. */
+const MAX_WINDOW_MESSAGES = 80;
+
+const truncateToolPayload = (raw: unknown): string => {
+  const serialized = typeof raw === 'string' ? raw : JSON.stringify(raw);
+  if (serialized.length <= TOOL_RESULT_MAX_CHARS) return serialized;
+  const dropped = serialized.length - TOOL_RESULT_MAX_CHARS;
+  return `${serialized.slice(0, TOOL_RESULT_MAX_CHARS)}\n…[truncated ${dropped} chars]`;
+};
+
+/**
+ * Trim the message history to a sliding window while preserving tool-call
+ * integrity. Drops any leading orphan `tool` messages whose matching
+ * assistant call was sliced off, since most providers reject that.
+ */
+const buildMessageWindow = (messages: ShortTermMessage[]): ShortTermMessage[] => {
+  if (messages.length <= MAX_WINDOW_MESSAGES) return messages;
+  const tail = messages.slice(-MAX_WINDOW_MESSAGES);
+  const knownAssistantCallIds = new Set<string>();
+  for (const m of tail) {
+    if (m.role === 'assistant' && m.toolCalls) {
+      for (const tc of m.toolCalls) knownAssistantCallIds.add(tc.id);
+    }
+  }
+  return tail.filter((m) => m.role !== 'tool' || knownAssistantCallIds.has(m.toolCallId));
+};
+
+/**
+ * Self-healing pass: every assistant tool_call must have a matching tool
+ * result before the next user/assistant turn, or providers (OpenAI in
+ * particular) reject the request with "Tool result is missing for tool call".
+ *
+ * This can happen when a handler emits a `:result` event without `meta`
+ * (orphaning the call), the process restarts mid-run, or a tool handler
+ * crashes. Rather than refuse to continue, we inject synthetic tool messages
+ * with a clear error payload — the LLM can then explain the failure to the
+ * user and proceed.
+ */
+const repairOpenToolCalls = (messages: ShortTermMessage[]): ShortTermMessage[] => {
+  const fulfilled = new Set<string>();
+  for (const m of messages) {
+    if (m.role === 'tool') fulfilled.add(m.toolCallId);
+  }
+
+  const repaired: ShortTermMessage[] = [];
+  for (const m of messages) {
+    repaired.push(m);
+    if (m.role !== 'assistant' || !m.toolCalls) continue;
+    for (const tc of m.toolCalls) {
+      if (fulfilled.has(tc.id)) continue;
+      repaired.push({
+        role: 'tool',
+        toolCallId: tc.id,
+        toolName: tc.function.name,
+        content: JSON.stringify({
+          success: false,
+          error: 'Tool result was lost (handler did not emit a matching :result event).',
+        }),
+      });
+      fulfilled.add(tc.id);
+    }
+  }
+  return repaired;
+};
+
 const readPersistedShortTermMessages = (state: OpenBotState): ShortTermMessage[] => {
   const source = state.threadDetails?.state ?? state.channelDetails?.state;
   const record = asRecord(source);
@@ -161,7 +233,9 @@ export const aiSdkRuntime =
         contextEngine,
       );
 
-      const coreMessages = mapToCoreMessages(context.state.shortTermMessages || []);
+      const coreMessages = mapToCoreMessages(
+        buildMessageWindow(repairOpenToolCalls(context.state.shortTermMessages || [])),
+      );
 
       try {
         const result = await generateText({
@@ -311,7 +385,7 @@ export const aiSdkRuntime =
 
       const toolName = event.type.replace(/^action:/, '').replace(/:result$/, '');
       const resultData = (event as { data?: unknown }).data;
-      const content = typeof resultData === 'string' ? resultData : JSON.stringify(resultData);
+      const content = truncateToolPayload(resultData);
 
       context.state.shortTermMessages = [
         ...(context.state.shortTermMessages ?? []),

package/src/plugins/memory/index.ts

@@ -0,0 +1,85 @@
+import z from 'zod';
+import type { Plugin } from '../../bus/plugin.js';
+
+/**
+ * `memory` — exposes the global memory store as agent tools.
+ *
+ * The actual handlers live in `bus/services.ts` because memory is platform
+ * infrastructure (shared across every agent on the bus); this plugin only
+ * contributes the tool definitions so a runtime plugin (e.g. `ai-sdk`) can
+ * surface them to the LLM.
+ *
+ * Scopes
+ * ------
+ * - `global`  (default) — visible to every agent and channel.
+ * - `agent`   — visible only to the agent that wrote it.
+ * - `channel` — visible only inside the active channel.
+ */
+const memoryToolDefinitions = {
+  remember: {
+    description:
+      'Persist a durable fact, preference, or note to long-term memory so it can be recalled in future turns and runs. Use for stable information (user preferences, project conventions, contact details, decisions); avoid using it for transient chatter or per-step scratch state — that belongs in thread state. Keep entries short and self-contained.',
+    inputSchema: z.object({
+      content: z
+        .string()
+        .min(1)
+        .describe(
+          'The fact to remember, written so it makes sense out of context (e.g. "User prefers TypeScript over JavaScript.").',
+        ),
+      scope: z
+        .enum(['global', 'agent', 'channel'])
+        .optional()
+        .describe(
+          'Visibility: `global` (default, all agents everywhere), `agent` (only this agent), `channel` (only this channel).',
+        ),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe('Optional tags for filtering with `recall`.'),
+    }),
+  },
+  recall: {
+    description:
+      'Search long-term memory for facts you previously stored with `remember`. Returns up to `limit` matching records with their ids so you can `forget` stale ones.',
+    inputSchema: z.object({
+      query: z
+        .string()
+        .optional()
+        .describe('Case-insensitive substring filter against memory content.'),
+      tag: z.string().optional().describe('Only return memories that include this tag.'),
+      scope: z
+        .enum(['global', 'agent', 'channel', 'all'])
+        .optional()
+        .describe(
+          'Restrict the search to a single scope. Default `all` returns global + this agent + this channel.',
+        ),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .max(50)
+        .optional()
+        .describe('Maximum records to return (default 20, max 50).'),
+    }),
+  },
+  forget: {
+    description:
+      'Delete a memory by id. Use after the user asks to forget something or when a previously remembered fact is now wrong. Get ids from `recall`.',
+    inputSchema: z.object({
+      id: z.string().describe('The memory record id (returned by `recall`/`remember`).'),
+    }),
+  },
+};
+
+export const memoryPlugin: Plugin = {
+  id: 'memory',
+  name: 'Memory',
+  description:
+    'Global long-term memory: remember/recall/forget facts across runs and agents.',
+  toolDefinitions: memoryToolDefinitions,
+  factory: () => () => {
+    // Handlers live in bus/services.ts; this plugin only contributes tool definitions.
+  },
+};
+
+export default memoryPlugin;

package/src/registry/plugins.ts

@@ -9,6 +9,7 @@ import { delegationPlugin } from '../plugins/delegation/index.js';
 import { storageToolsPlugin } from '../plugins/storage-tools/index.js';
 import { uiPlugin } from '../plugins/ui/index.js';
 import { approvalPlugin } from '../plugins/approval/index.js';
+import { memoryPlugin } from '../plugins/memory/index.js';
 import { DEFAULT_PLUGINS_DIR, DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
 
 let pluginsDir: string | null = null;
@@ -23,6 +24,7 @@ const BUILT_IN: Record<string, Plugin> = {
   [storageToolsPlugin.id]: storageToolsPlugin,
   [uiPlugin.id]: uiPlugin,
   [approvalPlugin.id]: approvalPlugin,
+  [memoryPlugin.id]: memoryPlugin,
 };
 
 /**

package/src/services/memory.ts

@@ -0,0 +1,213 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
+
+/**
+ * Global memory service.
+ *
+ * Persistent, agent-shared knowledge store that lives outside of any single
+ * channel/thread conversation. Designed as a stable foundation we can extend
+ * later with embeddings, retrieval ranking, TTLs, etc.
+ *
+ * Storage format
+ * --------------
+ * `~/.openbot/memory/log.jsonl` — append-only log. Each line is one of:
+ *
+ *   { "op": "add", "record": MemoryRecord }
+ *   { "op": "delete", "id": string, "at": ISO }
+ *   { "op": "update", "id": string, "patch": Partial<MemoryRecord>, "at": ISO }
+ *
+ * Reads replay the log into an in-memory map. The log is append-only so
+ * concurrent writers are line-atomic on every POSIX filesystem we target.
+ *
+ * Scopes
+ * ------
+ * `global`            — visible to every agent everywhere.
+ * `agent:<agentId>`   — visible only when that agent is running.
+ * `channel:<channelId>` — visible only inside that channel.
+ *
+ * Scope strings are opaque to the store; new scopes can be introduced without
+ * a migration.
+ */
+export interface MemoryRecord {
+  id: string;
+  scope: string;
+  content: string;
+  tags?: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ListMemoriesArgs {
+  /** Exact scope match (e.g. `global`, `agent:foo`, `channel:bar`). */
+  scope?: string;
+  /** Multiple scopes — OR'd together. Useful for "global + agent:X + channel:Y". */
+  scopes?: string[];
+  /** Substring match (case-insensitive) against `content`. */
+  query?: string;
+  /** Match if any of these tags is present. */
+  tag?: string;
+  /** Default 50, hard cap 500. */
+  limit?: number;
+}
+
+interface AddEntry { op: 'add'; record: MemoryRecord }
+interface DeleteEntry { op: 'delete'; id: string; at: string }
+interface UpdateEntry { op: 'update'; id: string; patch: Partial<MemoryRecord>; at: string }
+type LogEntry = AddEntry | DeleteEntry | UpdateEntry;
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+const getMemoryDir = (): string => {
+  const config = loadConfig();
+  return path.join(resolvePath(config.baseDir || DEFAULT_BASE_DIR), 'memory');
+};
+
+const getLogPath = (): string => path.join(getMemoryDir(), 'log.jsonl');
+
+const ensureDir = async (): Promise<void> => {
+  await fs.mkdir(getMemoryDir(), { recursive: true });
+};
+
+const readLog = async (): Promise<LogEntry[]> => {
+  try {
+    const raw = await fs.readFile(getLogPath(), 'utf-8');
+    return raw
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line) as LogEntry;
+        } catch {
+          return null;
+        }
+      })
+      .filter((e): e is LogEntry => !!e);
+  } catch (e: unknown) {
+    if ((e as { code?: string })?.code === 'ENOENT') return [];
+    throw e;
+  }
+};
+
+const replay = (entries: LogEntry[]): Map<string, MemoryRecord> => {
+  const out = new Map<string, MemoryRecord>();
+  for (const entry of entries) {
+    if (entry.op === 'add') {
+      out.set(entry.record.id, entry.record);
+    } else if (entry.op === 'delete') {
+      out.delete(entry.id);
+    } else if (entry.op === 'update') {
+      const existing = out.get(entry.id);
+      if (!existing) continue;
+      out.set(entry.id, {
+        ...existing,
+        ...entry.patch,
+        id: existing.id,
+        updatedAt: entry.at,
+      });
+    }
+  }
+  return out;
+};
+
+const appendEntry = async (entry: LogEntry): Promise<void> => {
+  await ensureDir();
+  await fs.appendFile(getLogPath(), `${JSON.stringify(entry)}\n`, 'utf-8');
+};
+
+const matchesQuery = (record: MemoryRecord, query?: string, tag?: string): boolean => {
+  if (tag) {
+    if (!record.tags || !record.tags.includes(tag)) return false;
+  }
+  if (query) {
+    const q = query.toLowerCase();
+    if (!record.content.toLowerCase().includes(q)) return false;
+  }
+  return true;
+};
+
+export const memoryService = {
+  appendMemory: async (args: {
+    scope: string;
+    content: string;
+    tags?: string[];
+  }): Promise<MemoryRecord> => {
+    const now = new Date().toISOString();
+    const record: MemoryRecord = {
+      id: crypto.randomUUID(),
+      scope: args.scope,
+      content: args.content,
+      tags: args.tags?.length ? args.tags : undefined,
+      createdAt: now,
+      updatedAt: now,
+    };
+    await appendEntry({ op: 'add', record });
+    return record;
+  },
+
+  updateMemory: async (args: {
+    id: string;
+    content?: string;
+    tags?: string[];
+  }): Promise<boolean> => {
+    const entries = await readLog();
+    const map = replay(entries);
+    if (!map.has(args.id)) return false;
+    const at = new Date().toISOString();
+    const patch: Partial<MemoryRecord> = {};
+    if (args.content !== undefined) patch.content = args.content;
+    if (args.tags !== undefined) patch.tags = args.tags.length ? args.tags : undefined;
+    if (Object.keys(patch).length === 0) return true;
+    await appendEntry({ op: 'update', id: args.id, patch, at });
+    return true;
+  },
+
+  deleteMemory: async (args: { id: string }): Promise<boolean> => {
+    const entries = await readLog();
+    const map = replay(entries);
+    if (!map.has(args.id)) return false;
+    await appendEntry({ op: 'delete', id: args.id, at: new Date().toISOString() });
+    return true;
+  },
+
+  listMemories: async (args: ListMemoriesArgs = {}): Promise<MemoryRecord[]> => {
+    const entries = await readLog();
+    const map = replay(entries);
+    const limit = Math.min(Math.max(args.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+
+    const scopeSet = (() => {
+      if (args.scope) return new Set([args.scope]);
+      if (args.scopes && args.scopes.length > 0) return new Set(args.scopes);
+      return null;
+    })();
+
+    const filtered: MemoryRecord[] = [];
+    for (const record of map.values()) {
+      if (scopeSet && !scopeSet.has(record.scope)) continue;
+      if (!matchesQuery(record, args.query, args.tag)) continue;
+      filtered.push(record);
+    }
+
+    filtered.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return filtered.slice(0, limit);
+  },
+
+  /**
+   * Compact the log into a single `add` per surviving record. Cheap to call
+   * occasionally; not required for correctness.
+   */
+  compact: async (): Promise<number> => {
+    const entries = await readLog();
+    const map = replay(entries);
+    const surviving = Array.from(map.values());
+    await ensureDir();
+    const tmp = `${getLogPath()}.tmp`;
+    const body = surviving.map((record) => JSON.stringify({ op: 'add', record })).join('\n');
+    await fs.writeFile(tmp, body ? `${body}\n` : '', 'utf-8');
+    await fs.rename(tmp, getLogPath());
+    return surviving.length;
+  },
+};