@oharness/engine 0.5.0 → 0.6.0

package/dist/agent/memory-backup.d.ts

@@ -0,0 +1,38 @@
+import type { MemoryScope } from "./memory-limits.ts";
+import type { MemoryNote, MemoryStore, MemoryStores } from "./memory.ts";
+/**
+ * Copies of notes kept before anything replaces or removes them.
+ *
+ * Every path that makes a note disappear or changes it without the user
+ * looking writes one first: deleting from the page, `forget`, taking the cloud
+ * side of a conflict, an automatic pull, an extractor's rewrite, and a restore
+ * replacing a newer version. They live on this machine only, under
+ * `memory-backups/` in the user directory.
+ */
+export declare const BACKUP_REASONS: readonly ["delete", "forget", "conflict", "conflict-cloud", "auto-merge", "sync-update", "sync-delete", "extract-update", "consolidate", "restore"];
+export type BackupReason = (typeof BACKUP_REASONS)[number];
+export interface MemoryBackup {
+    /** File name inside the backups directory; what a restore names. */
+    file: string;
+    /** Absent on backups written before reasons were recorded. */
+    reason?: BackupReason;
+    scope?: MemoryScope;
+    /** The notes directory the note was in. */
+    location?: string;
+    backedUpAt: number;
+    note: MemoryNote;
+}
+export declare function backupNote(store: MemoryStore, note: MemoryNote, reason: BackupReason): Promise<string>;
+/** The most recent backups, newest first. Unreadable files are skipped. */
+export declare function listBackups(limit?: number): Promise<MemoryBackup[]>;
+/**
+ * Put a backed-up note back where it came from.
+ *
+ * The directory it was in when that is still one of `stores`, then its scope,
+ * then the project. A newer version of the same note is backed up before being
+ * replaced, so a restore can itself be undone. The backup file is kept.
+ */
+export declare function restoreBackup(stores: MemoryStores, file: string): Promise<{
+    id: string;
+    scope: MemoryScope;
+}>;

package/dist/agent/memory-backup.js

@@ -0,0 +1,126 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeUserFile } from "../config-files.js";
+import { userPath } from "../paths.js";
+import { MEMORY_SAFETY, isMemoryScope } from "./memory-limits.js";
+import { memoryNote, noteHash, validateNote } from "./memory.js";
+/**
+ * Copies of notes kept before anything replaces or removes them.
+ *
+ * Every path that makes a note disappear or changes it without the user
+ * looking writes one first: deleting from the page, `forget`, taking the cloud
+ * side of a conflict, an automatic pull, an extractor's rewrite, and a restore
+ * replacing a newer version. They live on this machine only, under
+ * `memory-backups/` in the user directory.
+ */
+export const BACKUP_REASONS = ["delete", "forget", "conflict", "conflict-cloud", "auto-merge", "sync-update", "sync-delete", "extract-update", "consolidate", "restore"];
+const DIRECTORY = "memory-backups";
+const FILE = /^[a-zA-Z0-9_-]{1,160}\.json$/;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const object = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+export async function backupNote(store, note, reason) {
+    const at = Date.now();
+    const file = `${at}-${createHash("sha256").update(`${store.location}\0${note.id}\0${randomUUID()}`).digest("hex").slice(0, 16)}.json`;
+    await writeUserFile(`${DIRECTORY}/${file}`, {
+        version: 1, reason, scope: store.scope, location: store.location, backedUpAt: at, note: clean(note),
+    });
+    return file;
+}
+function clean(note) {
+    return {
+        id: note.id, summary: note.summary, body: note.body, tags: [...note.tags], createdAt: note.createdAt,
+        ...(note.updatedAt ? { updatedAt: note.updatedAt } : {}),
+        ...(note.type ? { type: note.type } : {}),
+    };
+}
+/** Backups in either format: the current wrapped one, or the bare note written before it. */
+function parse(file, raw, mtimeMs) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!object(value))
+        return undefined;
+    const wrapped = value.version === 1 && object(value.note);
+    const note = (wrapped ? value.note : value);
+    try {
+        validateNote(note, MEMORY_SAFETY.maxNoteBytesCeiling);
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        file,
+        backedUpAt: wrapped && Number.isSafeInteger(value.backedUpAt) ? value.backedUpAt : Math.floor(mtimeMs),
+        note: clean(note),
+        ...(wrapped && BACKUP_REASONS.includes(value.reason) ? { reason: value.reason } : {}),
+        ...(wrapped && isMemoryScope(value.scope) ? { scope: value.scope } : {}),
+        ...(wrapped && typeof value.location === "string" ? { location: value.location } : {}),
+    };
+}
+/** The most recent backups, newest first. Unreadable files are skipped. */
+export async function listBackups(limit = 100) {
+    const directory = userPath(DIRECTORY);
+    let names;
+    try {
+        names = (await readdir(directory)).filter((name) => FILE.test(name));
+    }
+    catch {
+        return [];
+    }
+    const stats = (await Promise.all(names.map(async (name) => {
+        try {
+            const info = await lstat(path.join(directory, name));
+            return info.isFile() && info.size <= MAX_FILE_BYTES ? { name, mtimeMs: info.mtimeMs } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }))).filter((item) => item !== undefined);
+    stats.sort((a, b) => b.mtimeMs - a.mtimeMs || b.name.localeCompare(a.name));
+    const backups = [];
+    for (const item of stats) {
+        if (backups.length >= limit)
+            break;
+        const raw = await readFile(path.join(directory, item.name), "utf8").catch(() => undefined);
+        const backup = raw === undefined ? undefined : parse(item.name, raw, item.mtimeMs);
+        if (backup)
+            backups.push(backup);
+    }
+    return backups.sort((a, b) => b.backedUpAt - a.backedUpAt);
+}
+/**
+ * Put a backed-up note back where it came from.
+ *
+ * The directory it was in when that is still one of `stores`, then its scope,
+ * then the project. A newer version of the same note is backed up before being
+ * replaced, so a restore can itself be undone. The backup file is kept.
+ */
+export async function restoreBackup(stores, file) {
+    if (!FILE.test(file))
+        throw new Error("Invalid backup file");
+    const full = path.join(userPath(DIRECTORY), file);
+    const info = await lstat(full).catch(() => undefined);
+    if (!info?.isFile() || info.size > MAX_FILE_BYTES)
+        throw new Error("Invalid backup file");
+    const backup = parse(file, await readFile(full, "utf8"), info.mtimeMs);
+    if (!backup)
+        throw new Error("Backup cannot be read");
+    const store = stores.user && backup.location === stores.user.location ? stores.user
+        : backup.location === stores.project.location ? stores.project
+            : backup.scope === "user" && stores.user ? stores.user
+                : stores.project;
+    const current = (await store.load()).find((entry) => entry.id === backup.note.id);
+    const currentNote = current ? memoryNote(current) : undefined;
+    if (currentNote && noteHash(currentNote) === noteHash(backup.note))
+        return { id: backup.note.id, scope: store.scope };
+    if (currentNote)
+        await backupNote(store, currentNote, "restore");
+    await store.apply(backup.note.id, { ...backup.note, updatedAt: Date.now() }, noteHash(currentNote));
+    return { id: backup.note.id, scope: store.scope };
+}
+//# sourceMappingURL=memory-backup.js.map

package/dist/agent/memory-backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-backup.js","sourceRoot":"","sources":["../../src/agent/memory-backup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,CAAU,CAAC;AAelL,MAAM,SAAS,GAAG,gBAAgB,CAAC;AACnC,MAAM,IAAI,GAAG,8BAA8B,CAAC;AAC5C,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AACvC,MAAM,MAAM,GAAG,CAAC,CAAU,EAA4B,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE3G,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAkB,EAAE,IAAgB,EAAE,MAAoB;IACzF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACtB,MAAM,IAAI,GAAG,GAAG,EAAE,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,EAAE,KAAK,UAAU,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;IACtI,MAAM,aAAa,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,EAAE;QAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;KACpG,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,IAAgB;IAC7B,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS;QACpG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,SAAS,KAAK,CAAC,IAAY,EAAE,GAAW,EAAE,OAAe;IACvD,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAe,CAAC;IAC1D,IAAI,CAAC;QAAC,YAAY,CAAC,IAAI,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;IAC1F,OAAO;QACL,IAAI;QACJ,UAAU,EAAE,OAAO,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QACtG,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;QACjB,GAAG,CAAC,OAAO,IAAK,cAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAsB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7H,GAAG,CAAC,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,OAAO,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvF,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAK,GAAG,GAAG;IAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QAAC,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;IAClG,MAAM,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACxD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACpG,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,SAAS,CAAC;QAAC,CAAC;IAC/B,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAA6C,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,MAAM,IAAI,KAAK;YAAE,MAAM;QACnC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnF,IAAI,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAoB,EAAE,IAAY;IACpE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,GAAG,cAAc;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI;QACjF,CAAC,CAAC,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO;YAC9D,CAAC,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI;gBACtD,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IACnB,MAAM,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClF,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,IAAI,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IACtH,IAAI,WAAW;QAAE,MAAM,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IACjE,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;IACpG,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;AACpD,CAAC"}

package/dist/agent/memory-consolidate.d.ts

@@ -0,0 +1,47 @@
+import type { MemoryScope, MemoryType } from "./memory-limits.ts";
+import type { MemoryNote } from "./memory.ts";
+/**
+ * Merging notes that say the same thing into one.
+ *
+ * The model only writes the combined text. Which notes go, which one stays,
+ * and how links elsewhere follow are decided here, by code that can be tested:
+ * the kept note is the oldest, so an id other notes and transcripts already
+ * cite keeps working, and every `[[removed]]` link in the scope is pointed at it.
+ */
+export interface MergeDraft {
+    summary: string;
+    body: string;
+    tags: string[];
+    type?: MemoryType;
+}
+export type ScopedMemoryNote = MemoryNote & {
+    scope: MemoryScope;
+};
+/** One write of a merge. `expectedHash` is the version the plan was made from. */
+export interface MergeEdit {
+    scope: MemoryScope;
+    id: string;
+    note?: MemoryNote;
+    expectedHash: string | null;
+}
+export declare const CONSOLIDATE_PROMPT = "You merge notes an assistant keeps across sessions. The notes you are given overlap. Write one note that keeps every distinct fact, instruction and caveat from all of them, drops repetition, and never adds anything that is not in them. Where two notes contradict each other, keep both statements and say which is newer by the updated time given.\n\nKeep [[id]] links that appear in the notes. Do not invent links.\n\nReply with only a JSON object:\n{\"summary\": \"one line, under 150 characters, naming what the note is about\", \"body\": \"the merged note, Markdown\", \"tags\": [\"lowercase\", \"synonyms\"], \"type\": \"user|feedback|project|reference\"}";
+export declare function mergePrompt(notes: readonly MemoryNote[]): string;
+/** The model's reply as a draft, or undefined when it is not one. */
+export declare function parseMergeReply(reply: string): MergeDraft | undefined;
+/** A starting point for merging by hand: the oldest summary, every body, every tag. */
+export declare function draftByHand(notes: readonly MemoryNote[]): MergeDraft;
+/** Point `[[old]]` links at their new targets. */
+export declare function rewriteLinks(body: string, targets: ReadonlyMap<string, string>): string;
+/**
+ * Every write a merge makes: the kept note replaced by the draft, the others
+ * deleted, and notes in either scope that linked to a deleted one relinked.
+ * `ids` are merged in the order given; the first is kept.
+ */
+export declare function planMerge(input: {
+    all: readonly ScopedMemoryNote[];
+    scope: MemoryScope;
+    ids: readonly string[];
+    draft: MergeDraft;
+    hash(note: MemoryNote): string | null;
+    now?: number;
+}): MergeEdit[];

package/dist/agent/memory-consolidate.js

@@ -0,0 +1,118 @@
+import { MemoryError } from "./memory-errors.js";
+import { MEMORY_SAFETY, isMemoryType } from "./memory-limits.js";
+import { redactSecrets } from "./memory-redact.js";
+export const CONSOLIDATE_PROMPT = `You merge notes an assistant keeps across sessions. The notes you are given overlap. Write one note that keeps every distinct fact, instruction and caveat from all of them, drops repetition, and never adds anything that is not in them. Where two notes contradict each other, keep both statements and say which is newer by the updated time given.
+
+Keep [[id]] links that appear in the notes. Do not invent links.
+
+Reply with only a JSON object:
+{"summary": "one line, under 150 characters, naming what the note is about", "body": "the merged note, Markdown", "tags": ["lowercase", "synonyms"], "type": "user|feedback|project|reference"}`;
+export function mergePrompt(notes) {
+    const blocks = notes.map((note) => {
+        const when = new Date(note.updatedAt ?? note.createdAt).toISOString();
+        const meta = [`id=${note.id}`, `updated=${when}`, note.type ? `type=${note.type}` : "", note.tags.length ? `tags=${note.tags.join(",")}` : ""].filter(Boolean).join(" ");
+        return `<note ${meta}>\n${note.summary}\n\n${note.body}\n</note>`;
+    });
+    return `Notes to merge:\n\n${blocks.join("\n\n")}\n\nReply with the merged note as JSON now.`;
+}
+function cleanTags(tags) {
+    if (!Array.isArray(tags))
+        return [];
+    const out = [];
+    for (const tag of tags) {
+        if (typeof tag !== "string")
+            continue;
+        const value = tag.trim().toLowerCase();
+        if (MEMORY_SAFETY.tagPattern.test(value) && !out.includes(value))
+            out.push(value);
+        if (out.length >= MEMORY_SAFETY.maxTags)
+            break;
+    }
+    return out;
+}
+/** The model's reply as a draft, or undefined when it is not one. */
+export function parseMergeReply(reply) {
+    const start = reply.indexOf("{"), end = reply.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    const summary = typeof raw.summary === "string" ? raw.summary.replace(/[\r\n]+/g, " ").trim().slice(0, MEMORY_SAFETY.maxSummaryChars) : "";
+    const body = typeof raw.body === "string" ? redactSecrets(raw.body).text.trim() : "";
+    if (!summary || !body)
+        return undefined;
+    return { summary: redactSecrets(summary).text, body, tags: cleanTags(raw.tags), ...(isMemoryType(raw.type) ? { type: raw.type } : {}) };
+}
+/** A starting point for merging by hand: the oldest summary, every body, every tag. */
+export function draftByHand(notes) {
+    const first = notes[0];
+    const bodies = [];
+    for (const note of notes)
+        if (!bodies.includes(note.body))
+            bodies.push(note.body);
+    return {
+        summary: first.summary,
+        body: bodies.join("\n\n"),
+        tags: cleanTags(notes.flatMap((note) => note.tags)),
+        ...(first.type ? { type: first.type } : {}),
+    };
+}
+/** Point `[[old]]` links at their new targets. */
+export function rewriteLinks(body, targets) {
+    return body.replace(/\[\[([a-zA-Z0-9_-]{1,128})\]\]/g, (whole, id) => {
+        const target = targets.get(id);
+        return target ? `[[${target}]]` : whole;
+    });
+}
+/**
+ * Every write a merge makes: the kept note replaced by the draft, the others
+ * deleted, and notes in either scope that linked to a deleted one relinked.
+ * `ids` are merged in the order given; the first is kept.
+ */
+export function planMerge(input) {
+    const group = input.ids.map((id) => input.all.find((note) => note.id === id && note.scope === input.scope));
+    if (group.length < 2 || group.some((note) => !note) || new Set(input.ids).size !== input.ids.length) {
+        throw new MemoryError("mergeGone");
+    }
+    const notes = group;
+    const keep = notes[0];
+    const targets = new Map(notes.slice(1).map((note) => [note.id, keep.id]));
+    const merged = {
+        id: keep.id,
+        summary: input.draft.summary,
+        body: rewriteLinks(input.draft.body, targets).trim(),
+        tags: [...input.draft.tags],
+        createdAt: Math.min(...notes.map((note) => note.createdAt)),
+        updatedAt: input.now ?? Date.now(),
+    };
+    if (input.draft.type)
+        merged.type = input.draft.type;
+    const edits = [
+        { scope: input.scope, id: keep.id, note: merged, expectedHash: input.hash(stripScope(keep)) },
+        ...notes.slice(1).map((note) => ({ scope: input.scope, id: note.id, expectedHash: input.hash(stripScope(note)) })),
+    ];
+    // Only the scope a note is in holds its links to rewrite, so a user note
+    // linking into this project is relinked in the user scope.
+    for (const other of input.all) {
+        if (other.scope === input.scope && (other.id === keep.id || targets.has(other.id)))
+            continue;
+        const body = rewriteLinks(other.body, other.scope === input.scope ? targets : new Map());
+        if (body === other.body)
+            continue;
+        edits.push({ scope: other.scope, id: other.id, note: { ...stripScope(other), body, updatedAt: input.now ?? Date.now() }, expectedHash: input.hash(stripScope(other)) });
+    }
+    return edits;
+}
+function stripScope(note) {
+    const { scope: _scope, ...rest } = note;
+    return rest;
+}
+//# sourceMappingURL=memory-consolidate.js.map

package/dist/agent/memory-consolidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-consolidate.js","sourceRoot":"","sources":["../../src/agent/memory-consolidate.ts"],"names":[],"mappings":"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"}

package/dist/agent/memory-errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Errors the memory subsystem shows to people, by code.
+ *
+ * The engine does not choose a language. The message here is an English
+ * default for callers with no strings of their own (logs, the terminal, a
+ * model reading a tool error); a frontend with its own strings translates by
+ * `code` and `params` instead, as the web page does with `memory.err.*`.
+ * Codes are stable. Wording may change.
+ */
+declare const MESSAGES: {
+    readonly configInvalid: "Memory sync settings are invalid, so sync has stopped.";
+    readonly stopped: "Memory sync has stopped.";
+    readonly disabledHere: "Cloud sync was turned off for these notes.";
+    readonly accountChanged: "The signed-in account or Cloud address changed, so memory sync is paused.";
+    readonly settingsChanged: "Memory sync settings changed.";
+    readonly localUnreadable: "Notes on this machine cannot be read or are invalid. Check the memory folder. Sync is paused and no file was changed.";
+    readonly signInFirst: "Sign in to OHarness first.";
+    readonly boundElsewhere: "This notes folder is already bound to another account or Cloud. Use a separate notes folder so notes are not uploaded across accounts.";
+    readonly verifyFailed: "Account verification failed.";
+    readonly syncFailed: "Sync failed.";
+    readonly invalidVersion: "The sync service returned an invalid version.";
+    readonly waitForSync: "Wait for the current sync to finish.";
+    readonly stale: "Notes changed on this machine or another device. Sync, then try again.";
+    readonly invalidBatch: "Invalid batch change.";
+    readonly batchTooLarge: "Too many notes changed at once. Change them in smaller batches.";
+    readonly serverTooOld: "The sync service is too old to sync your own notes. Upgrade the sync service.";
+    readonly accountSwitched: "The account changed.";
+    readonly invalidChoice: "Invalid conflict choice.";
+    readonly localChanged: "Notes on this machine changed. Sync again.";
+    readonly oneSideDeleted: "One side deleted this note, so both copies cannot be kept.";
+    readonly mergedMissing: "The merged note is missing.";
+    readonly secret: "The note seems to contain a credential, so it was not saved.";
+    readonly secretFound: "The note seems to contain a credential ({kinds}), so it was not saved.";
+    readonly mergedSecret: "The merged note seems to contain a credential, so it was not saved.";
+    readonly conflictsPending: "{count} notes were changed on both sides in overlapping ways and could not be merged automatically. Choose which version to keep. Everything else is synced.";
+    readonly conflictsRemain: "Some conflicts still need resolving.";
+    readonly invalidResponse: "The sync service returned invalid data.";
+    readonly signInAgain: "Sign in to OHarness again.";
+    readonly requestFailed: "The memory sync request failed or was cancelled. You can try again.";
+    readonly cloudChanged: "The cloud version changed. Sync again.";
+    readonly rateLimited: "Syncing too often. It will retry automatically.";
+    readonly serverNotConfigured: "The sync service has not set up memory sign-in or R2 storage.";
+    readonly quotaExceeded: "Over the sync service's memory quota.";
+    readonly rejected: "The sync request was refused. Check your account and sync settings.";
+    readonly planLimit: "Free cloud sync for memory is full: at most {notes} project notes and {notes} of your own, {kb} KB each. Upgrading removes these limits. Notes on this machine are not affected.";
+    readonly planLimitPlain: "Free cloud sync for memory is full. Upgrading removes the limits. Notes on this machine are not affected.";
+    readonly responseTooLarge: "The sync response was too large.";
+    readonly principalMismatch: "The sync response is for a different account.";
+    readonly mergeGone: "The notes to merge no longer exist or have changed.";
+    readonly modelNoDraft: "The model did not return a usable merge. You can merge by hand instead.";
+    readonly mergeStale: "Notes changed. Suggest the merge again.";
+    readonly editStale: "The note changed. Refresh, then edit again.";
+    readonly deleteStale: "The note changed. Refresh the page.";
+    readonly mergeEmpty: "The merged summary and body cannot be empty.";
+    readonly unknownAction: "Unknown memory action.";
+};
+export type MemoryErrorCode = keyof typeof MESSAGES;
+export type MemoryErrorParams = Record<string, string | number>;
+/** Every code and its English message, for frontends that check their strings cover them. */
+export declare const MEMORY_ERROR_MESSAGES: Readonly<Record<MemoryErrorCode, string>>;
+export declare class MemoryError extends Error {
+    readonly code: MemoryErrorCode;
+    readonly params: MemoryErrorParams;
+    constructor(code: MemoryErrorCode, params?: MemoryErrorParams);
+}
+/** What a status report carries about a failure: the message, and the code when there is one. */
+export interface MemoryFailureInfo {
+    message: string;
+    code?: MemoryErrorCode;
+    params?: MemoryErrorParams;
+}
+export declare function memoryFailure(error: unknown): MemoryFailureInfo;
+export {};

package/dist/agent/memory-errors.js

@@ -0,0 +1,74 @@
+/**
+ * Errors the memory subsystem shows to people, by code.
+ *
+ * The engine does not choose a language. The message here is an English
+ * default for callers with no strings of their own (logs, the terminal, a
+ * model reading a tool error); a frontend with its own strings translates by
+ * `code` and `params` instead, as the web page does with `memory.err.*`.
+ * Codes are stable. Wording may change.
+ */
+const MESSAGES = {
+    configInvalid: "Memory sync settings are invalid, so sync has stopped.",
+    stopped: "Memory sync has stopped.",
+    disabledHere: "Cloud sync was turned off for these notes.",
+    accountChanged: "The signed-in account or Cloud address changed, so memory sync is paused.",
+    settingsChanged: "Memory sync settings changed.",
+    localUnreadable: "Notes on this machine cannot be read or are invalid. Check the memory folder. Sync is paused and no file was changed.",
+    signInFirst: "Sign in to OHarness first.",
+    boundElsewhere: "This notes folder is already bound to another account or Cloud. Use a separate notes folder so notes are not uploaded across accounts.",
+    verifyFailed: "Account verification failed.",
+    syncFailed: "Sync failed.",
+    invalidVersion: "The sync service returned an invalid version.",
+    waitForSync: "Wait for the current sync to finish.",
+    stale: "Notes changed on this machine or another device. Sync, then try again.",
+    invalidBatch: "Invalid batch change.",
+    batchTooLarge: "Too many notes changed at once. Change them in smaller batches.",
+    serverTooOld: "The sync service is too old to sync your own notes. Upgrade the sync service.",
+    accountSwitched: "The account changed.",
+    invalidChoice: "Invalid conflict choice.",
+    localChanged: "Notes on this machine changed. Sync again.",
+    oneSideDeleted: "One side deleted this note, so both copies cannot be kept.",
+    mergedMissing: "The merged note is missing.",
+    secret: "The note seems to contain a credential, so it was not saved.",
+    secretFound: "The note seems to contain a credential ({kinds}), so it was not saved.",
+    mergedSecret: "The merged note seems to contain a credential, so it was not saved.",
+    conflictsPending: "{count} notes were changed on both sides in overlapping ways and could not be merged automatically. Choose which version to keep. Everything else is synced.",
+    conflictsRemain: "Some conflicts still need resolving.",
+    invalidResponse: "The sync service returned invalid data.",
+    signInAgain: "Sign in to OHarness again.",
+    requestFailed: "The memory sync request failed or was cancelled. You can try again.",
+    cloudChanged: "The cloud version changed. Sync again.",
+    rateLimited: "Syncing too often. It will retry automatically.",
+    serverNotConfigured: "The sync service has not set up memory sign-in or R2 storage.",
+    quotaExceeded: "Over the sync service's memory quota.",
+    rejected: "The sync request was refused. Check your account and sync settings.",
+    planLimit: "Free cloud sync for memory is full: at most {notes} project notes and {notes} of your own, {kb} KB each. Upgrading removes these limits. Notes on this machine are not affected.",
+    planLimitPlain: "Free cloud sync for memory is full. Upgrading removes the limits. Notes on this machine are not affected.",
+    responseTooLarge: "The sync response was too large.",
+    principalMismatch: "The sync response is for a different account.",
+    mergeGone: "The notes to merge no longer exist or have changed.",
+    modelNoDraft: "The model did not return a usable merge. You can merge by hand instead.",
+    mergeStale: "Notes changed. Suggest the merge again.",
+    editStale: "The note changed. Refresh, then edit again.",
+    deleteStale: "The note changed. Refresh the page.",
+    mergeEmpty: "The merged summary and body cannot be empty.",
+    unknownAction: "Unknown memory action.",
+};
+/** Every code and its English message, for frontends that check their strings cover them. */
+export const MEMORY_ERROR_MESSAGES = MESSAGES;
+export class MemoryError extends Error {
+    code;
+    params;
+    constructor(code, params = {}) {
+        super(MESSAGES[code].replace(/\{([a-z]+)\}/g, (whole, name) => (params[name] === undefined ? whole : String(params[name]))));
+        this.name = "MemoryError";
+        this.code = code;
+        this.params = params;
+    }
+}
+export function memoryFailure(error) {
+    if (error instanceof MemoryError)
+        return { message: error.message, code: error.code, params: error.params };
+    return error instanceof Error ? { message: error.message } : { message: MESSAGES.syncFailed, code: "syncFailed" };
+}
+//# sourceMappingURL=memory-errors.js.map

package/dist/agent/memory-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-errors.js","sourceRoot":"","sources":["../../src/agent/memory-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,QAAQ,GAAG;IACf,aAAa,EAAE,wDAAwD;IACvE,OAAO,EAAE,0BAA0B;IACnC,YAAY,EAAE,4CAA4C;IAC1D,cAAc,EAAE,2EAA2E;IAC3F,eAAe,EAAE,+BAA+B;IAChD,eAAe,EAAE,uHAAuH;IACxI,WAAW,EAAE,4BAA4B;IACzC,cAAc,EAAE,wIAAwI;IACxJ,YAAY,EAAE,8BAA8B;IAC5C,UAAU,EAAE,cAAc;IAC1B,cAAc,EAAE,+CAA+C;IAC/D,WAAW,EAAE,sCAAsC;IACnD,KAAK,EAAE,wEAAwE;IAC/E,YAAY,EAAE,uBAAuB;IACrC,aAAa,EAAE,iEAAiE;IAChF,YAAY,EAAE,+EAA+E;IAC7F,eAAe,EAAE,sBAAsB;IACvC,aAAa,EAAE,0BAA0B;IACzC,YAAY,EAAE,4CAA4C;IAC1D,cAAc,EAAE,4DAA4D;IAC5E,aAAa,EAAE,6BAA6B;IAC5C,MAAM,EAAE,8DAA8D;IACtE,WAAW,EAAE,wEAAwE;IACrF,YAAY,EAAE,qEAAqE;IACnF,gBAAgB,EAAE,8JAA8J;IAChL,eAAe,EAAE,sCAAsC;IACvD,eAAe,EAAE,yCAAyC;IAC1D,WAAW,EAAE,4BAA4B;IACzC,aAAa,EAAE,qEAAqE;IACpF,YAAY,EAAE,wCAAwC;IACtD,WAAW,EAAE,iDAAiD;IAC9D,mBAAmB,EAAE,+DAA+D;IACpF,aAAa,EAAE,uCAAuC;IACtD,QAAQ,EAAE,qEAAqE;IAC/E,SAAS,EAAE,kLAAkL;IAC7L,cAAc,EAAE,2GAA2G;IAC3H,gBAAgB,EAAE,kCAAkC;IACpD,iBAAiB,EAAE,+CAA+C;IAClE,SAAS,EAAE,qDAAqD;IAChE,YAAY,EAAE,yEAAyE;IACvF,UAAU,EAAE,yCAAyC;IACrD,SAAS,EAAE,6CAA6C;IACxD,WAAW,EAAE,qCAAqC;IAClD,UAAU,EAAE,8CAA8C;IAC1D,aAAa,EAAE,wBAAwB;CAC/B,CAAC;AAKX,6FAA6F;AAC7F,MAAM,CAAC,MAAM,qBAAqB,GAA8C,QAAQ,CAAC;AAEzF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IACtB,MAAM,CAAoB;IACnC,YAAY,IAAqB,EAAE,SAA4B,EAAE;QAC/D,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrI,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AASD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,WAAW;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC5G,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AACpH,CAAC"}

package/dist/agent/memory-extract.d.ts

@@ -0,0 +1,36 @@
+import type { Message } from "../core/types.ts";
+import type { ModelSpec, Provider } from "../providers/types.ts";
+import type { ExtractedNote, ExtractionResult, MemoryCandidate, MemoryExtractionTarget } from "./memory-provider.ts";
+/**
+ * Notes proposed by a model reading a finished stretch of conversation.
+ *
+ * The complement to `remember`, which depends on the agent noticing in the
+ * moment. Off by default, because every pass is a model call on the user's
+ * own credit. What comes back is treated as untrusted: ids it was not shown
+ * are dropped, links it invents are unlinked, credentials are redacted, and
+ * everything lands through the same store paths a human edit takes.
+ */
+export declare const EXTRACTION_PROMPT = "You maintain a set of durable notes an assistant reads in future sessions. Read the conversation and propose notes worth keeping.\n\nWorth keeping:\n- a correction the user gave, or an approach they confirmed (type \"feedback\");\n- who the user is or how they like to work (type \"user\");\n- a decision and its reason, a constraint, or ongoing work that the code and git history do not record (type \"project\");\n- where external information lives: a dashboard, a tracker, a document (type \"reference\").\n\nNot worth keeping: anything the code or git history already records, anything only relevant to the task in progress, small talk, credentials or secrets of any kind.\n\nExisting notes come in two lists. Notes shown with their full body may be updated: if a proposal covers the same subject as one of them, use \"action\": \"update\" with its \"id\" and write the complete new body, keeping every detail of the existing body that is still true. Notes listed by summary only may be linked but never updated; propose a new note instead if one of them needs changing.\n\nBodies state the fact, then a line starting \"Why:\" and a line starting \"How to apply:\". Tags carry the words someone might search with instead of the summary's own: synonyms, and the term in the other language the conversation uses. Link related notes as [[id]] using only the ids listed. A new note in this batch can be linked from another new note as [[new:N]], where N is that note's \"ref\".\n\nRespond with a JSON array and nothing else. Each element:\n{\"action\":\"create\"|\"update\",\"id\":\"<existing id, for update>\",\"ref\":<number, for create>,\"summary\":\"<one concrete line>\",\"body\":\"<markdown>\",\"type\":\"user\"|\"feedback\"|\"project\"|\"reference\",\"scope\":\"user\"|\"project\",\"tags\":[\"...\"]}\n\nScope \"project\" is the default, including for feedback about how this codebase is worked on. Use scope \"user\" for facts about the user and for preferences that plainly hold in every project. Return [] when nothing qualifies \u2014 that is the common case.";
+/** The conversation as plain text, newest material kept when it has to be cut. */
+export declare function transcriptText(messages: readonly Message[], maxChars?: number): string;
+/** Real messages from the user: typed, not tool results or harness summaries. */
+export declare function countUserTurns(messages: readonly Message[]): number;
+/**
+ * Validate an extractor's reply. Returns only well-formed notes; a reply that
+ * is not JSON at all yields none rather than an error, since a model that
+ * rambles instead of answering has proposed nothing.
+ */
+export declare function parseExtraction(reply: string, candidates: readonly MemoryCandidate[]): ExtractedNote[];
+/**
+ * Replace `[[new:N]]` with the id note N was given. A placeholder whose note
+ * was not written becomes plain text.
+ */
+export declare function resolvePlaceholders(body: string, ids: ReadonlyMap<number, string>): string;
+export interface ExtractionRun {
+    messages: readonly Message[];
+    provider: Provider;
+    model: ModelSpec;
+    target: MemoryExtractionTarget;
+    signal?: AbortSignal;
+}
+export declare function extractMemories(run: ExtractionRun): Promise<ExtractionResult>;