@oharness/engine 0.4.0 → 0.5.1

package/dist/agent/memory-extract.js

@@ -0,0 +1,169 @@
+import { userMessage, visibleText } from "../core/types.js";
+import { MEMORY_SAFETY, defaultScopeFor, isMemoryScope, isMemoryType } from "./memory-limits.js";
+import { redactSecrets } from "./memory-redact.js";
+/**
+ * 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 const EXTRACTION_PROMPT = `You maintain a set of durable notes an assistant reads in future sessions. Read the conversation and propose notes worth keeping.
+
+Worth keeping:
+- a correction the user gave, or an approach they confirmed (type "feedback");
+- who the user is or how they like to work (type "user");
+- a decision and its reason, a constraint, or ongoing work that the code and git history do not record (type "project");
+- where external information lives: a dashboard, a tracker, a document (type "reference").
+
+Not 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.
+
+Existing 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.
+
+Bodies 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".
+
+Respond with a JSON array and nothing else. Each element:
+{"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":["..."]}
+
+Scope "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 — that is the common case.`;
+/** The conversation as plain text, newest material kept when it has to be cut. */
+export function transcriptText(messages, maxChars = 60_000) {
+    const parts = [];
+    for (const message of messages) {
+        if (message.meta?.compacted)
+            continue;
+        const text = visibleText(message).trim();
+        const calls = message.content.filter((block) => block.type === "tool_call").map((block) => block.name);
+        if (!text && !calls.length)
+            continue;
+        const who = message.role === "user" ? (message.meta?.synthetic ? "Tool results" : "User") : "Assistant";
+        parts.push(`${who}: ${text}${calls.length ? `\n[called ${calls.join(", ")}]` : ""}`);
+    }
+    const joined = parts.join("\n\n");
+    return joined.length > maxChars ? `[earlier conversation omitted]\n${joined.slice(joined.length - maxChars)}` : joined;
+}
+/** Real messages from the user: typed, not tool results or harness summaries. */
+export function countUserTurns(messages) {
+    return messages.filter((message) => message.role === "user" && !message.meta?.synthetic && !message.meta?.compacted &&
+        message.content.some((block) => block.type === "text")).length;
+}
+const LINKISH = /\[\[([^\]\n]{1,140})\]\]/g;
+/**
+ * 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 function parseExtraction(reply, candidates) {
+    const start = reply.indexOf("[");
+    const end = reply.lastIndexOf("]");
+    if (start === -1 || end <= start)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+    const notes = [];
+    const refs = new Set();
+    const updated = new Set();
+    for (const item of raw.slice(0, 50)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const value = item;
+        const summary = typeof value.summary === "string" ? redactSecrets(value.summary.replace(/[\r\n]+/g, " ").trim()).text : "";
+        const body = typeof value.body === "string" ? redactSecrets(value.body.trim()).text : "";
+        if (summary.length < 4 || summary.length > MEMORY_SAFETY.maxSummaryChars || body.length < 4)
+            continue;
+        const type = isMemoryType(value.type) ? value.type : undefined;
+        const tags = Array.isArray(value.tags)
+            ? value.tags.filter((tag) => typeof tag === "string" && MEMORY_SAFETY.tagPattern.test(tag)).slice(0, MEMORY_SAFETY.maxTags)
+            : [];
+        if (value.action === "update") {
+            const target = typeof value.id === "string" ? byId.get(value.id) : undefined;
+            // An id the extractor was not shown is a guess, and updating a guess
+            // would overwrite whatever note happens to have that id.
+            // Nor may it update a note it was only shown the summary of: the reply
+            // replaces the body, and a body written without reading the old one
+            // silently drops whatever the old one said.
+            if (!target || typeof target.body !== "string" || updated.has(target.id))
+                continue;
+            updated.add(target.id);
+            notes.push({ action: "update", id: target.id, summary, body, tags, ...(type ?? target.type ? { type: type ?? target.type } : {}), scope: target.scope });
+            continue;
+        }
+        if (value.action !== "create")
+            continue;
+        const ref = typeof value.ref === "number" && Number.isSafeInteger(value.ref) && value.ref > 0 && !refs.has(value.ref) ? value.ref : undefined;
+        if (ref !== undefined)
+            refs.add(ref);
+        const scope = isMemoryScope(value.scope) ? value.scope : defaultScopeFor(type);
+        notes.push({ action: "create", ...(ref !== undefined ? { ref } : {}), summary, body, tags, ...(type ? { type } : {}), scope });
+    }
+    for (const note of notes) {
+        note.body = note.body.replace(LINKISH, (whole, inner) => {
+            const target = inner.trim();
+            const placeholder = /^new:(\d+)$/.exec(target);
+            if (placeholder && refs.has(Number(placeholder[1])))
+                return `[[new:${placeholder[1]}]]`;
+            if (byId.has(target))
+                return `[[${target}]]`;
+            // Invented: keep the words, drop the link.
+            return target;
+        });
+    }
+    return notes;
+}
+/**
+ * Replace `[[new:N]]` with the id note N was given. A placeholder whose note
+ * was not written becomes plain text.
+ */
+export function resolvePlaceholders(body, ids) {
+    return body.replace(/\[\[new:(\d+)\]\]/g, (_, ref) => {
+        const id = ids.get(Number(ref));
+        return id ? `[[${id}]]` : `note ${ref}`;
+    });
+}
+export async function extractMemories(run) {
+    const transcript = transcriptText(run.messages);
+    if (!transcript.trim())
+        return { created: [], updated: [] };
+    const policy = run.target.policy();
+    const candidates = policy.maxCandidates > 0 ? await run.target.candidates(transcript, policy.maxCandidates) : [];
+    const label = (candidate) => `${candidate.id} (${[candidate.scope, candidate.type].filter(Boolean).join(", ")})`;
+    const editable = candidates.filter((candidate) => typeof candidate.body === "string");
+    const linkOnly = candidates.filter((candidate) => typeof candidate.body !== "string");
+    const listing = [
+        "Notes you may update (full body shown):",
+        editable.length
+            ? editable.map((candidate) => `<note id="${candidate.id}" label="${label(candidate)}">\n${candidate.summary}\n\n${candidate.body}\n</note>`).join("\n\n")
+            : "(none)",
+        "",
+        "Other existing notes (link only, never update):",
+        linkOnly.length ? linkOnly.map((candidate) => `- ${label(candidate)}: ${candidate.summary}`).join("\n") : "(none)",
+    ].join("\n");
+    const request = {
+        model: run.model,
+        system: EXTRACTION_PROMPT,
+        messages: [userMessage(`Existing notes:\n${listing}\n\nConversation:\n<conversation>\n${transcript}\n</conversation>\n\nPropose notes now, as a JSON array.`)],
+        maxOutputTokens: Math.min(4_000, run.model.maxOutputTokens),
+        thinking: { enabled: false, effort: "low" },
+        ...(run.signal ? { signal: run.signal } : {}),
+    };
+    const parts = [];
+    for await (const event of run.provider.stream(request)) {
+        if (event.type === "text_delta")
+            parts.push(event.text);
+    }
+    const notes = parseExtraction(parts.join(""), candidates);
+    if (!notes.length)
+        return { created: [], updated: [] };
+    return run.target.commit(notes);
+}
+//# sourceMappingURL=memory-extract.js.map

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

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

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

@@ -0,0 +1,115 @@
+/**
+ * Every number the memory subsystem runs on, in one place.
+ *
+ * Three kinds live here and they are kept apart on purpose. Policy is the
+ * user's to change and arrives through `memory` in config. Safety bounds are
+ * not configurable, because each one is a defence rather than a preference.
+ * Sync quotas are neither: they belong to whoever runs the sync server, which
+ * announces them in its responses, so no client-side copy exists at all.
+ */
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export declare const MEMORY_SCOPES: readonly ["project", "user"];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+export interface MemoryRecallPolicy {
+    /** Attach relevant notes to each user message. */
+    enabled: boolean;
+    /** Most notes attached to one message. */
+    perTurn: number;
+    /** Characters the attached notes may take up, bodies and related lines together. */
+    budgetChars: number;
+    /** Below this score a note is not attached. */
+    minScore: number;
+}
+export interface MemoryExtractionPolicy {
+    /** Extract candidate notes from the part of a conversation compaction drops. */
+    onCompaction: boolean;
+    /** Extract candidate notes when a run ends. */
+    onStop: boolean;
+    /** Conversations with fewer real user messages than this are skipped. */
+    minUserTurns: number;
+    /** Existing notes shown to the extractor so it can update or link them. */
+    maxCandidates: number;
+}
+export interface MemoryConsolidationPolicy {
+    /**
+     * Merge notes about the same subject in the background, with the small
+     * model. Only duplicates, never the other review findings. `"subscribers"`
+     * means on for an account the sync service reports as paid, off otherwise.
+     */
+    auto: boolean | "subscribers";
+    /** Least time between background passes. */
+    cooldownHours: number;
+    /** Most merges one background pass makes. */
+    maxMerges: number;
+    /** A note neither recalled nor edited for this long is listed for review. */
+    unusedDays: number;
+}
+export interface MemoryPolicy {
+    maxNotes: number;
+    maxNoteBytes: number;
+    /** Characters of note summaries the system prompt index may list. */
+    indexChars: number;
+    recall: MemoryRecallPolicy;
+    autoExtract: MemoryExtractionPolicy;
+    consolidate: MemoryConsolidationPolicy;
+}
+/** The `memory` section of a config file. Every field is optional. */
+export interface MemoryConfig {
+    /** Project-level notes directory, relative to the project root. */
+    dir?: string;
+    maxNotes?: number;
+    maxNoteBytes?: number;
+    indexChars?: number;
+    recall?: Partial<MemoryRecallPolicy>;
+    autoExtract?: Partial<MemoryExtractionPolicy>;
+    consolidate?: Partial<MemoryConsolidationPolicy>;
+}
+export declare const DEFAULT_MEMORY_POLICY: MemoryPolicy;
+/** Defences. Not configurable. */
+export declare const MEMORY_SAFETY: {
+    readonly idPattern: RegExp;
+    readonly reservedIds: readonly string[];
+    readonly maxSummaryChars: 500;
+    readonly maxTags: 30;
+    readonly tagPattern: RegExp;
+    /** A configured note size is clamped to this. */
+    readonly maxNoteBytesCeiling: number;
+    /** Room for frontmatter on top of the body when reading a file. */
+    readonly fileOverheadBytes: number;
+    /** A configured note count is clamped to this. */
+    readonly maxNotesCeiling: 50000;
+    /** Largest sync response a client will buffer. */
+    readonly syncResponseBytes: number;
+    /** Serialized size of one commit request, below the server's body limit. */
+    readonly syncCommitBatchBytes: number;
+    /** Changes per commit when the server has not announced a quota yet. */
+    readonly syncCommitBatchChanges: 500;
+    /** Parallel stats when scanning a notes directory. */
+    readonly statConcurrency: 32;
+    /** Notes shown to an extractor in full, and so the only ones it may update. */
+    readonly extractEditableNotes: 8;
+    /** A note longer than this is shown by summary only, and cannot be updated by extraction. */
+    readonly extractEditableBodyChars: 4000;
+    /** Characters of note bodies one extraction request may carry. */
+    readonly extractBodyBudgetChars: 20000;
+};
+/** Defaults filled in and every number clamped to something that cannot break a run. */
+export declare function resolveMemoryPolicy(config: MemoryConfig | undefined): MemoryPolicy;
+/**
+ * Whether background merging runs. An explicit true or false is the user's
+ * choice; `"subscribers"` follows the plan the sync service last announced,
+ * so an account whose plan is unknown (sync off, not signed in) stays off.
+ */
+export declare function consolidationEnabled(setting: MemoryConsolidationPolicy["auto"], tiers: ReadonlyArray<string | undefined>): boolean;
+export declare function isMemoryType(value: unknown): value is MemoryType;
+export declare function isMemoryScope(value: unknown): value is MemoryScope;
+/**
+ * Where a note of this type goes when nobody said.
+ *
+ * Only facts about the user themselves default to every project. Feedback
+ * usually names this codebase's conventions, and a correction recalled in an
+ * unrelated repository is noise at best and wrong at worst; one that really
+ * holds everywhere is put in the user scope on purpose.
+ */
+export declare function defaultScopeFor(type: MemoryType | undefined): MemoryScope;

package/dist/agent/memory-limits.js

@@ -0,0 +1,109 @@
+/**
+ * Every number the memory subsystem runs on, in one place.
+ *
+ * Three kinds live here and they are kept apart on purpose. Policy is the
+ * user's to change and arrives through `memory` in config. Safety bounds are
+ * not configurable, because each one is a defence rather than a preference.
+ * Sync quotas are neither: they belong to whoever runs the sync server, which
+ * announces them in its responses, so no client-side copy exists at all.
+ */
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+export const MEMORY_SCOPES = ["project", "user"];
+export const DEFAULT_MEMORY_POLICY = {
+    maxNotes: 5_000,
+    maxNoteBytes: 128 * 1024,
+    indexChars: 4_000,
+    recall: { enabled: true, perTurn: 3, budgetChars: 2_000, minScore: 1.2 },
+    // Off: extraction spends the user's own model credit on every long session.
+    autoExtract: { onCompaction: false, onStop: false, minUserTurns: 3, maxCandidates: 40 },
+    // On only for paid accounts: a merge spends model credit nobody asked to spend
+    // otherwise, and every merge it makes is backed up.
+    consolidate: { auto: "subscribers", cooldownHours: 24, maxMerges: 3, unusedDays: 90 },
+};
+/** Defences. Not configurable. */
+export const MEMORY_SAFETY = {
+    idPattern: /^[a-zA-Z0-9_-]{1,128}$/,
+    reservedIds: ["__proto__", "constructor", "prototype"],
+    maxSummaryChars: 500,
+    maxTags: 30,
+    tagPattern: /^[^\s,\r\n]{1,64}$/,
+    /** A configured note size is clamped to this. */
+    maxNoteBytesCeiling: 1024 * 1024,
+    /** Room for frontmatter on top of the body when reading a file. */
+    fileOverheadBytes: 64 * 1024,
+    /** A configured note count is clamped to this. */
+    maxNotesCeiling: 50_000,
+    /** Largest sync response a client will buffer. */
+    syncResponseBytes: 64 * 1024 * 1024,
+    /** Serialized size of one commit request, below the server's body limit. */
+    syncCommitBatchBytes: 2 * 1024 * 1024,
+    /** Changes per commit when the server has not announced a quota yet. */
+    syncCommitBatchChanges: 500,
+    /** Parallel stats when scanning a notes directory. */
+    statConcurrency: 32,
+    /** Notes shown to an extractor in full, and so the only ones it may update. */
+    extractEditableNotes: 8,
+    /** A note longer than this is shown by summary only, and cannot be updated by extraction. */
+    extractEditableBodyChars: 4_000,
+    /** Characters of note bodies one extraction request may carry. */
+    extractBodyBudgetChars: 20_000,
+};
+const clampInt = (value, fallback, min, max) => typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, Math.floor(value))) : fallback;
+const clampNumber = (value, fallback, min, max) => typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+const flag = (value, fallback) => (typeof value === "boolean" ? value : fallback);
+/** Defaults filled in and every number clamped to something that cannot break a run. */
+export function resolveMemoryPolicy(config) {
+    const d = DEFAULT_MEMORY_POLICY;
+    const recall = config?.recall ?? {};
+    const extract = config?.autoExtract ?? {};
+    const consolidate = config?.consolidate ?? {};
+    return {
+        maxNotes: clampInt(config?.maxNotes, d.maxNotes, 1, MEMORY_SAFETY.maxNotesCeiling),
+        maxNoteBytes: clampInt(config?.maxNoteBytes, d.maxNoteBytes, 1024, MEMORY_SAFETY.maxNoteBytesCeiling),
+        indexChars: clampInt(config?.indexChars, d.indexChars, 0, 100_000),
+        recall: {
+            enabled: flag(recall.enabled, d.recall.enabled),
+            perTurn: clampInt(recall.perTurn, d.recall.perTurn, 0, 20),
+            budgetChars: clampInt(recall.budgetChars, d.recall.budgetChars, 200, 50_000),
+            minScore: clampNumber(recall.minScore, d.recall.minScore, 0, 1_000),
+        },
+        autoExtract: {
+            onCompaction: flag(extract.onCompaction, d.autoExtract.onCompaction),
+            onStop: flag(extract.onStop, d.autoExtract.onStop),
+            minUserTurns: clampInt(extract.minUserTurns, d.autoExtract.minUserTurns, 1, 1_000),
+            maxCandidates: clampInt(extract.maxCandidates, d.autoExtract.maxCandidates, 0, 500),
+        },
+        consolidate: {
+            auto: consolidate.auto === "subscribers" ? "subscribers" : flag(consolidate.auto, d.consolidate.auto),
+            cooldownHours: clampNumber(consolidate.cooldownHours, d.consolidate.cooldownHours, 1, 24 * 365),
+            maxMerges: clampInt(consolidate.maxMerges, d.consolidate.maxMerges, 0, 50),
+            unusedDays: clampInt(consolidate.unusedDays, d.consolidate.unusedDays, 1, 3650),
+        },
+    };
+}
+/**
+ * Whether background merging runs. An explicit true or false is the user's
+ * choice; `"subscribers"` follows the plan the sync service last announced,
+ * so an account whose plan is unknown (sync off, not signed in) stays off.
+ */
+export function consolidationEnabled(setting, tiers) {
+    return setting === "subscribers" ? tiers.includes("paid") : setting;
+}
+export function isMemoryType(value) {
+    return typeof value === "string" && MEMORY_TYPES.includes(value);
+}
+export function isMemoryScope(value) {
+    return typeof value === "string" && MEMORY_SCOPES.includes(value);
+}
+/**
+ * Where a note of this type goes when nobody said.
+ *
+ * Only facts about the user themselves default to every project. Feedback
+ * usually names this codebase's conventions, and a correction recalled in an
+ * unrelated repository is noise at best and wrong at worst; one that really
+ * holds everywhere is put in the user scope on purpose.
+ */
+export function defaultScopeFor(type) {
+    return type === "user" ? "user" : "project";
+}
+//# sourceMappingURL=memory-limits.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * `[[note-id]]` links between memory notes.
+ *
+ * Links live only in note bodies. Nothing about them is stored in frontmatter
+ * or sent to the sync server separately, so the graph is always derived from
+ * what the notes say and can never disagree with them.
+ */
+/** Link targets in order of first appearance, ignoring code. */
+export declare function extractLinks(body: string): string[];
+export interface LinkGraph {
+    /** Resolved targets each note links to. */
+    outgoing: Map<string, string[]>;
+    /** Notes that link to each note. */
+    incoming: Map<string, string[]>;
+    /** Targets each note links to that no note has. */
+    dangling: Map<string, string[]>;
+}
+export declare function buildLinkGraph(notes: ReadonlyArray<{
+    id: string;
+    body: string;
+}>): LinkGraph;

package/dist/agent/memory-links.js

@@ -0,0 +1,45 @@
+/**
+ * `[[note-id]]` links between memory notes.
+ *
+ * Links live only in note bodies. Nothing about them is stored in frontmatter
+ * or sent to the sync server separately, so the graph is always derived from
+ * what the notes say and can never disagree with them.
+ */
+const LINK = /\[\[([a-zA-Z0-9_-]{1,128})\]\]/g;
+const FENCE = /^(```|~~~)[^\n]*\n[\s\S]*?^\1[ \t]*$/gm;
+const INLINE_CODE = /`[^`\n]*`/g;
+/** Link targets in order of first appearance, ignoring code. */
+export function extractLinks(body) {
+    const prose = body.replace(FENCE, "").replace(INLINE_CODE, "");
+    const seen = new Set();
+    for (const match of prose.matchAll(LINK))
+        seen.add(match[1]);
+    return [...seen];
+}
+export function buildLinkGraph(notes) {
+    const ids = new Set(notes.map((note) => note.id));
+    const graph = { outgoing: new Map(), incoming: new Map(), dangling: new Map() };
+    for (const note of notes) {
+        const resolved = [];
+        const missing = [];
+        for (const target of extractLinks(note.body)) {
+            if (target === note.id)
+                continue;
+            if (ids.has(target))
+                resolved.push(target);
+            else
+                missing.push(target);
+        }
+        if (resolved.length)
+            graph.outgoing.set(note.id, resolved);
+        if (missing.length)
+            graph.dangling.set(note.id, missing);
+        for (const target of resolved) {
+            const list = graph.incoming.get(target) ?? [];
+            list.push(note.id);
+            graph.incoming.set(target, list);
+        }
+    }
+    return graph;
+}
+//# sourceMappingURL=memory-links.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-links.js","sourceRoot":"","sources":["../../src/agent/memory-links.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,IAAI,GAAG,iCAAiC,CAAC;AAC/C,MAAM,KAAK,GAAG,wCAAwC,CAAC;AACvD,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AACnB,CAAC;AAWD,MAAM,UAAU,cAAc,CAAC,KAAkD;IAC/E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,KAAK,GAAc,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC3F,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7C,IAAI,MAAM,KAAK,IAAI,CAAC,EAAE;gBAAE,SAAS;YACjC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;;gBACtC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAC3D,IAAI,OAAO,CAAC,MAAM;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACzD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,34 @@
+import type { MemoryNote } from "./memory.ts";
+/**
+ * Combining two edits of one note, against the version both started from.
+ *
+ * Sync calls this when a note changed on this machine and in the cloud since
+ * the last sync. Changes that do not touch are combined; changes that do are
+ * reported by field and left to a person. Nothing here guesses: two different
+ * summaries, or two edits to neighbouring lines, are a conflict rather than a
+ * choice made on someone's behalf. Pure functions, so every rule is a test.
+ */
+export type MergeField = "summary" | "type" | "body" | "content";
+export type MergeResult = {
+    note: MemoryNote;
+} | {
+    conflict: MergeField[];
+};
+/**
+ * Tags as sets: what either side added is kept, what either side removed is
+ * gone. Order follows this machine's list, then the cloud's additions.
+ */
+export declare function mergeTags(base: readonly string[], local: readonly string[], cloud: readonly string[]): string[];
+/**
+ * A three-way merge of note bodies by line.
+ *
+ * Changes on the two sides combine when they are apart. Overlapping changes,
+ * changes to adjacent lines and insertions at the same place conflict, unless
+ * both sides made exactly the same change. Returns undefined on a conflict.
+ */
+export declare function mergeLines(base: string, local: string, cloud: string): string | undefined;
+/**
+ * Merge two edits of a note. Without the last synced version there is nothing
+ * to tell an edit from an original, so that is a conflict too.
+ */
+export declare function mergeNotes(base: MemoryNote | undefined, local: MemoryNote, cloud: MemoryNote): MergeResult;