opencode-claude-memory 1.7.6 → 1.7.8

package/dist/extraction/ExtractionCoordinator.d.ts

@@ -0,0 +1,62 @@
+import type { AgentRegistry } from "../agents.js";
+import type { MemoryConfig } from "../config.js";
+import { type ChatMessage, type OpencodeClient, type PluginEvent } from "../sdk.js";
+import type { MemoryStore } from "../store/MemoryStore.js";
+import { type Logger } from "../util/log.js";
+import type { OwnedSessions } from "../util/ownedSessions.js";
+import { AutoDream } from "./autodream.js";
+import { MaintenanceLock } from "./lock.js";
+import { ExtractionStateStore, type SessionExtractionState } from "./state.js";
+export declare const EXTRACTION_TITLE = "opencode-memory extraction";
+export declare const FORK_GRACE_MS = 60000;
+export declare const MAX_EXTRACTION_FAILURES = 3;
+export declare const MIN_CONVERSATION_CHARS = 20;
+export declare const SDK_READ_TIMEOUT_MS = 30000;
+export declare function sliceNewMessages(messages: readonly ChatMessage[], state: SessionExtractionState | undefined): ChatMessage[];
+export declare function trimIncompleteTail(messages: readonly ChatMessage[]): ChatMessage[];
+export declare function hasExtractableUserMessage(messages: readonly ChatMessage[]): boolean;
+export declare function buildConversationForExtraction(messages: readonly ChatMessage[], maxChars: number): string;
+export type ExtractionCoordinatorDeps = {
+    store: MemoryStore;
+    config: MemoryConfig;
+    client: OpencodeClient | undefined;
+    directory: string;
+    owned: OwnedSessions;
+    agents: AgentRegistry;
+    log: Logger;
+    now?: () => number;
+    state?: ExtractionStateStore;
+    lock?: MaintenanceLock;
+};
+export declare class ExtractionCoordinator {
+    private readonly deps;
+    readonly state: ExtractionStateStore;
+    readonly autodream: AutoDream | undefined;
+    private readonly lock;
+    private readonly now;
+    private readonly timers;
+    private readonly busy;
+    private readonly inFlight;
+    private readonly savedByFork;
+    private readonly savedByMainAgent;
+    private queue;
+    private caughtUp;
+    private disposed;
+    constructor(deps: ExtractionCoordinatorDeps);
+    get enabled(): boolean;
+    onEvent(event: PluginEvent): void;
+    onSessionIdle(sessionID: string): void;
+    onSessionStatus(sessionID: string, status: string): void;
+    onSessionDeleted(sessionID: string): void;
+    recordSave(sessionID: string | undefined, fileName: string): string[] | undefined;
+    isOwnedSession(sessionID: string | undefined): boolean;
+    idle(): Promise<void>;
+    catchUp(): Promise<void>;
+    dispose(): void;
+    private clearTimer;
+    private warnLegacyShellHook;
+    private enqueue;
+    private snapshot;
+    private advance;
+    private runIncremental;
+}

package/dist/extraction/ExtractionCoordinator.js

@@ -0,0 +1,386 @@
+import { roleOf } from "../hooks/messages.js";
+import { unwrapData } from "../sdk.js";
+import { findLegacyShellHooks } from "../util/legacyShellHook.js";
+import { getErrorMessage } from "../util/log.js";
+import { TimeoutError, withDeadline } from "../util/timeout.js";
+import { AutoDream } from "./autodream.js";
+import { runForkSession } from "./forkSession.js";
+import { MaintenanceLock } from "./lock.js";
+import { buildExtractionSystemPrompt } from "./prompts.js";
+import { ExtractionStateStore, migrateLegacyAutodreamState } from "./state.js";
+export const EXTRACTION_TITLE = "opencode-memory extraction";
+// Keep the fork in the owned-session guard past delete: its `session.idle` can arrive after the
+// delete HTTP call resolved and would otherwise trigger an extraction of the fork itself.
+export const FORK_GRACE_MS = 60_000;
+export const MAX_EXTRACTION_FAILURES = 3;
+export const MIN_CONVERSATION_CHARS = 20;
+// Deadline for the plain SDK reads (`session.messages`, `session.list`); see util/timeout.ts.
+export const SDK_READ_TIMEOUT_MS = 30_000;
+function messageTime(message) {
+    const time = message.info?.time;
+    return {
+        created: typeof time?.created === "number" ? time.created : undefined,
+        completed: typeof time?.completed === "number" ? time.completed : undefined,
+    };
+}
+// Messages after the watermark. If the watermark message was removed (revert / compaction), fall
+// back to everything created after the watermark message's own time (not the fork's finish time:
+// messages that arrived while the fork ran must not be skipped).
+export function sliceNewMessages(messages, state) {
+    if (!state)
+        return [...messages];
+    if (state.lastExtractedMessageID) {
+        const idx = messages.findIndex((m) => m.info.id === state.lastExtractedMessageID);
+        if (idx >= 0)
+            return messages.slice(idx + 1);
+    }
+    const boundary = state.lastMessageAt ?? state.updatedAt;
+    return messages.filter((m) => (messageTime(m).created ?? 0) > boundary);
+}
+// Drops assistant messages still being generated from the end of the slice: extracting them would
+// record a watermark past content that is not final yet, and the final answer would never be seen.
+export function trimIncompleteTail(messages) {
+    let end = messages.length;
+    while (end > 0) {
+        const message = messages[end - 1];
+        if (!message || roleOf(message) !== "assistant" || messageTime(message).completed !== undefined)
+            break;
+        end -= 1;
+    }
+    return messages.slice(0, end);
+}
+export function hasExtractableUserMessage(messages) {
+    return messages.some((message) => {
+        if (roleOf(message) !== "user" || !Array.isArray(message.parts))
+            return false;
+        return message.parts.some((part) => {
+            const p = part;
+            return p.type === "text" && typeof p.text === "string" && p.text.trim().length > 0 && !p.synthetic;
+        });
+    });
+}
+export function buildConversationForExtraction(messages, maxChars) {
+    const lines = [];
+    for (const message of messages) {
+        const role = roleOf(message);
+        if (!role || !Array.isArray(message.parts))
+            continue;
+        for (const part of message.parts) {
+            const p = part;
+            if (p.type === "text" && typeof p.text === "string" && !p.synthetic) {
+                lines.push(`### ${role === "user" ? "User" : "Assistant"}\n${p.text}`);
+            }
+            else if (p.type === "tool" && p.tool && p.state?.status === "completed" && typeof p.state.output === "string") {
+                const out = p.state.output.length > 300 ? `${p.state.output.slice(0, 300)}…` : p.state.output;
+                lines.push(`_[tool ${p.tool}: ${out}]_`);
+            }
+        }
+    }
+    let text = lines.join("\n\n");
+    // Keep the TAIL (newest turns carry the new facts worth extracting), drop the oldest head.
+    if (text.length > maxChars) {
+        text = `…[older turns truncated]\n\n${text.slice(-maxChars)}`;
+    }
+    return text;
+}
+export class ExtractionCoordinator {
+    deps;
+    state;
+    autodream;
+    lock;
+    now;
+    timers = new Map();
+    busy = new Set();
+    inFlight = new Set();
+    savedByFork = new Map();
+    savedByMainAgent = new Set();
+    queue = Promise.resolve();
+    caughtUp = false;
+    disposed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.state = deps.state ?? new ExtractionStateStore(deps.store.stateDir, this.now);
+        this.lock = deps.lock ?? new MaintenanceLock(this.state.lockPath, this.now);
+        this.autodream = deps.client
+            ? new AutoDream({ ...deps, client: deps.client, state: this.state, now: this.now, lock: this.lock })
+            : undefined;
+    }
+    get enabled() {
+        return this.deps.config.extract.enabled && this.deps.client !== undefined;
+    }
+    onEvent(event) {
+        if (event.type === "session.idle")
+            this.onSessionIdle(event.properties.sessionID);
+        else if (event.type === "session.deleted")
+            this.onSessionDeleted(event.properties.info.id);
+        else if (event.type === "session.status")
+            this.onSessionStatus(event.properties.sessionID, event.properties.status.type);
+    }
+    onSessionIdle(sessionID) {
+        if (!this.enabled || this.disposed || !sessionID)
+            return;
+        if (this.deps.owned.has(sessionID))
+            return;
+        this.busy.delete(sessionID);
+        this.clearTimer(sessionID);
+        const timer = setTimeout(() => {
+            this.timers.delete(sessionID);
+            void this.enqueue(sessionID);
+        }, this.deps.config.extract.debounceMs);
+        timer.unref?.();
+        this.timers.set(sessionID, timer);
+    }
+    // A session that starts a new turn (busy / retry) cancels its pending debounce: the previous
+    // turn is extracted together with the new one once the session is idle again.
+    onSessionStatus(sessionID, status) {
+        if (!sessionID || this.deps.owned.has(sessionID))
+            return;
+        if (status === "idle") {
+            this.busy.delete(sessionID);
+            return;
+        }
+        this.busy.add(sessionID);
+        this.clearTimer(sessionID);
+    }
+    onSessionDeleted(sessionID) {
+        this.clearTimer(sessionID);
+        this.busy.delete(sessionID);
+        this.savedByMainAgent.delete(sessionID);
+    }
+    // memory_save reports every write. Inside an extraction fork the list of files saved so far is
+    // returned so the tool result can carry the done-signal (#35); a save by the main agent marks the
+    // session so the next extraction round is skipped (the agent already curated its memory).
+    recordSave(sessionID, fileName) {
+        if (!sessionID)
+            return undefined;
+        const fork = this.savedByFork.get(sessionID);
+        if (fork) {
+            fork.push(fileName);
+            return fork;
+        }
+        if (!this.deps.owned.has(sessionID))
+            this.savedByMainAgent.add(sessionID);
+        return undefined;
+    }
+    isOwnedSession(sessionID) {
+        return this.deps.owned.has(sessionID);
+    }
+    // Resolves once every queued extraction has finished (tests, dispose).
+    idle() {
+        return this.queue;
+    }
+    // Sessions updated after their watermark (or never extracted) are extracted on start-up. This
+    // covers the TUI user who quits right after the last answer: the debounce timer died with the
+    // process, so the last turn would otherwise never be extracted.
+    async catchUp() {
+        if (this.caughtUp || !this.enabled)
+            return;
+        this.caughtUp = true;
+        const { client, config, directory, store, log } = this.deps;
+        if (!client)
+            return;
+        this.warnLegacyShellHook();
+        migrateLegacyAutodreamState(this.state, `${store.claudeConfigDir}/opencode-memory`, [
+            store.gitRoot ?? store.memoryRoot,
+            store.memoryRoot,
+            store.canonicalRoot,
+        ]);
+        if (config.extract.catchUpLimit <= 0)
+            return;
+        let sessions;
+        try {
+            sessions =
+                unwrapData(await withDeadline("session.list", SDK_READ_TIMEOUT_MS, (signal) => client.session.list({ query: { directory }, signal }))) ?? [];
+        }
+        catch (error) {
+            log("warn", "Extraction catch-up could not list sessions", { error: getErrorMessage(error) });
+            return;
+        }
+        const pending = sessions
+            .filter((session) => !session.parentID && !this.deps.owned.has(session.id))
+            .filter((session) => {
+            const known = this.state.getSession(session.id);
+            // Compare against the watermark *message* time, not the fork's finish time: a turn that
+            // completed while the previous fork was running must still be caught up.
+            const boundary = known?.lastMessageAt ?? known?.updatedAt ?? 0;
+            return (session.time?.updated ?? 0) > boundary;
+        })
+            .sort((a, b) => (b.time?.updated ?? 0) - (a.time?.updated ?? 0))
+            .slice(0, config.extract.catchUpLimit);
+        for (const session of pending)
+            await this.enqueue(session.id);
+    }
+    dispose() {
+        this.disposed = true;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.busy.clear();
+    }
+    clearTimer(sessionID) {
+        const existing = this.timers.get(sessionID);
+        if (existing)
+            clearTimeout(existing);
+        this.timers.delete(sessionID);
+    }
+    warnLegacyShellHook() {
+        let hooks;
+        try {
+            hooks = findLegacyShellHooks(this.deps.config.homeDir);
+        }
+        catch {
+            return;
+        }
+        if (hooks.length === 0)
+            return;
+        this.deps.log("warn", "v1 opencode-memory shell hook is still installed; v2 extracts in-process, so run `opencode-memory uninstall` (or delete the marked block) to avoid a second, competing extraction", {
+            files: hooks,
+        });
+    }
+    enqueue(sessionID) {
+        const run = this.queue.then(() => this.runIncremental(sessionID)).catch(() => { });
+        this.queue = run;
+        return run;
+    }
+    snapshot(messages, previous) {
+        const fresh = trimIncompleteTail(sliceNewMessages(messages, previous));
+        const last = fresh[fresh.length - 1];
+        if (!last || !hasExtractableUserMessage(fresh))
+            return undefined;
+        return { fresh, last, lastMessageAt: messageTime(last).created };
+    }
+    // Persists the watermark unless another process already moved it past this snapshot. Runs inside
+    // the state lock, so the decision is made against the current on-disk state.
+    advance(sessionID, snapshot, extra = {}) {
+        let advanced = false;
+        this.state.update((data) => {
+            const current = data.sessions[sessionID];
+            if (current?.lastMessageAt !== undefined &&
+                snapshot.lastMessageAt !== undefined &&
+                current.lastMessageAt > snapshot.lastMessageAt) {
+                return;
+            }
+            advanced = true;
+            data.sessions[sessionID] = {
+                lastExtractedMessageID: snapshot.last.info.id,
+                ...(snapshot.lastMessageAt !== undefined ? { lastMessageAt: snapshot.lastMessageAt } : {}),
+                updatedAt: this.now(),
+                failures: 0,
+                ...extra,
+            };
+            AutoDream.noteSession(data.autodream, sessionID);
+        });
+        return advanced;
+    }
+    async runIncremental(sessionID) {
+        const { client, config, store, directory, owned, agents, log } = this.deps;
+        if (!client || this.disposed || this.inFlight.has(sessionID))
+            return;
+        // Re-check at dequeue time: the debounce may have fired just before the session went busy, or
+        // the session may have started a new turn while this job waited in the queue.
+        if (this.busy.has(sessionID))
+            return;
+        this.inFlight.add(sessionID);
+        try {
+            const response = await withDeadline("session.messages", SDK_READ_TIMEOUT_MS, (signal) => client.session.messages({ path: { id: sessionID }, query: { directory }, signal }));
+            const messages = unwrapData(response) ?? [];
+            if (this.busy.has(sessionID))
+                return;
+            let snapshot = this.snapshot(messages, this.state.getSession(sessionID));
+            if (!snapshot)
+                return;
+            if (this.savedByMainAgent.delete(sessionID)) {
+                if (this.advance(sessionID, snapshot))
+                    await this.autodream?.maybeRun(sessionID);
+                return;
+            }
+            if (buildConversationForExtraction(snapshot.fresh, config.extract.maxConversationChars).trim().length <
+                MIN_CONVERSATION_CHARS) {
+                this.advance(sessionID, snapshot);
+                return;
+            }
+            // Cross-process serialisation (#30): another OpenCode process on this project is extracting or
+            // consolidating right now. Skip without touching the watermark; the next idle / start-up retries.
+            if (!this.lock.tryAcquire()) {
+                log("info", "Memory extraction skipped: another process holds the maintenance lock", { sessionID });
+                return;
+            }
+            let extracted = false;
+            try {
+                // Recompute against the state as it is *now*: while we waited for the lock another process
+                // may have extracted part (or all) of this slice.
+                const previous = this.state.getSession(sessionID);
+                snapshot = this.snapshot(messages, previous);
+                if (!snapshot)
+                    return;
+                const conversation = buildConversationForExtraction(snapshot.fresh, config.extract.maxConversationChars);
+                if (conversation.trim().length < MIN_CONVERSATION_CHARS) {
+                    this.advance(sessionID, snapshot);
+                    return;
+                }
+                try {
+                    await runForkSession({
+                        client,
+                        directory,
+                        parentSessionID: sessionID,
+                        title: EXTRACTION_TITLE,
+                        agent: config.agents.extract,
+                        system: buildExtractionSystemPrompt(store.manifest()),
+                        tools: agents.toolsFor(config.agents.extract),
+                        parts: [{ type: "text", text: conversation }],
+                        timeoutMs: config.extract.timeoutMs,
+                        onCreated: (forkID) => {
+                            owned.add(forkID);
+                            this.savedByFork.set(forkID, []);
+                        },
+                        onFinished: (forkID) => {
+                            owned.release(forkID, FORK_GRACE_MS);
+                            const cleanup = setTimeout(() => this.savedByFork.delete(forkID), FORK_GRACE_MS);
+                            cleanup.unref?.();
+                        },
+                        onCleanupFailed: (forkID, stage, error) => log("warn", "Extraction fork cleanup failed; the server may still hold the fork session", {
+                            forkID,
+                            stage,
+                            sessionID,
+                            error: getErrorMessage(error),
+                        }),
+                    });
+                }
+                catch (error) {
+                    const failures = (previous?.failures ?? 0) + 1;
+                    log("error", "Memory extraction failed", { error: getErrorMessage(error), sessionID, failures });
+                    if (failures >= MAX_EXTRACTION_FAILURES) {
+                        // Do not stay stuck on a message that keeps failing: move on and reset the counter.
+                        this.advance(sessionID, snapshot);
+                    }
+                    else {
+                        this.state.update((data) => {
+                            data.sessions[sessionID] = {
+                                ...(data.sessions[sessionID] ?? previous ?? { updatedAt: 0 }),
+                                failures,
+                                attemptedAt: this.now(),
+                            };
+                        });
+                    }
+                    return;
+                }
+                // The watermark is committed while the lock is still held, so no other process can run
+                // an extraction between the fork's writes and the watermark that records them.
+                extracted = this.advance(sessionID, snapshot);
+            }
+            finally {
+                this.lock.release();
+            }
+            if (extracted)
+                await this.autodream?.maybeRun(sessionID);
+        }
+        catch (error) {
+            const detail = error instanceof TimeoutError ? error.message : getErrorMessage(error);
+            log("error", "Memory extraction failed", { error: detail, sessionID });
+        }
+        finally {
+            this.inFlight.delete(sessionID);
+        }
+    }
+}

package/dist/extraction/autodream.d.ts

@@ -0,0 +1,33 @@
+import type { AgentRegistry } from "../agents.js";
+import type { MemoryConfig } from "../config.js";
+import type { OpencodeClient } from "../sdk.js";
+import type { MemoryStore } from "../store/MemoryStore.js";
+import { type Logger } from "../util/log.js";
+import type { OwnedSessions } from "../util/ownedSessions.js";
+import { MaintenanceLock } from "./lock.js";
+import type { AutodreamState, ExtractionStateStore } from "./state.js";
+export declare const AUTODREAM_TITLE = "opencode-memory auto-dream";
+export declare const AUTODREAM_FORK_GRACE_MS = 60000;
+export type AutodreamGate = Pick<MemoryConfig["autodream"], "minHours" | "minSessions">;
+export declare function shouldRunAutodream(state: AutodreamState, gate: AutodreamGate, now: number): boolean;
+export type AutoDreamDeps = {
+    store: MemoryStore;
+    config: MemoryConfig;
+    client: OpencodeClient;
+    directory: string;
+    state: ExtractionStateStore;
+    owned: OwnedSessions;
+    agents: AgentRegistry;
+    log: Logger;
+    now?: () => number;
+    lock?: MaintenanceLock;
+};
+export declare class AutoDream {
+    private readonly deps;
+    private readonly now;
+    private readonly lock;
+    constructor(deps: AutoDreamDeps);
+    static noteSession(state: AutodreamState, sessionID: string): void;
+    shouldRun(): boolean;
+    maybeRun(parentSessionID: string): Promise<boolean>;
+}

package/dist/extraction/autodream.js

@@ -0,0 +1,85 @@
+import { getErrorMessage } from "../util/log.js";
+import { runForkSession } from "./forkSession.js";
+import { MaintenanceLock } from "./lock.js";
+import { AUTODREAM_PROMPT, AUTODREAM_USER_MESSAGE } from "./prompts.js";
+export const AUTODREAM_TITLE = "opencode-memory auto-dream";
+export const AUTODREAM_FORK_GRACE_MS = 60_000;
+export function shouldRunAutodream(state, gate, now) {
+    const hoursSince = (now - state.lastConsolidatedAt) / (60 * 60 * 1000);
+    if (hoursSince < gate.minHours)
+        return false;
+    return state.sessionsSince.length >= gate.minSessions;
+}
+export class AutoDream {
+    deps;
+    now;
+    lock;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.lock = deps.lock ?? new MaintenanceLock(deps.state.lockPath, this.now);
+    }
+    // Called from the extraction coordinator's persisted update after a session was extracted.
+    static noteSession(state, sessionID) {
+        if (!state.sessionsSince.includes(sessionID))
+            state.sessionsSince.push(sessionID);
+    }
+    shouldRun() {
+        const { config, state } = this.deps;
+        if (!config.autodream.enabled)
+            return false;
+        return shouldRunAutodream(state.read().autodream, config.autodream, this.now());
+    }
+    // Runs a consolidation fork when the gate passes. Success resets the gate; failure leaves the
+    // gate untouched so the next extracted session retries.
+    async maybeRun(parentSessionID) {
+        if (!this.shouldRun())
+            return false;
+        if (!this.lock.tryAcquire()) {
+            this.deps.log("info", "Auto-dream skipped: another process holds the maintenance lock");
+            return false;
+        }
+        const { client, config, directory, owned, agents, state, log } = this.deps;
+        try {
+            // Re-check under the lock: another process may have consolidated while we waited to acquire.
+            if (!this.shouldRun())
+                return false;
+            const autodream = state.read().autodream;
+            log("info", "Auto-dream consolidation starting", {
+                sessionsSince: autodream.sessionsSince.length,
+                lastConsolidatedAt: autodream.lastConsolidatedAt,
+            });
+            await runForkSession({
+                client,
+                directory,
+                parentSessionID,
+                title: AUTODREAM_TITLE,
+                agent: config.agents.dream,
+                system: AUTODREAM_PROMPT,
+                tools: agents.toolsFor(config.agents.dream),
+                parts: [{ type: "text", text: AUTODREAM_USER_MESSAGE }],
+                timeoutMs: config.autodream.timeoutMs,
+                onCreated: (id) => owned.add(id),
+                onFinished: (id) => owned.release(id, AUTODREAM_FORK_GRACE_MS),
+                onCleanupFailed: (id, stage, error) => log("warn", "Auto-dream fork cleanup failed; the server may still hold the fork session", {
+                    forkID: id,
+                    stage,
+                    error: getErrorMessage(error),
+                }),
+            });
+            state.update((data) => {
+                data.autodream.lastConsolidatedAt = this.now();
+                data.autodream.sessionsSince = [];
+            });
+            log("info", "Auto-dream consolidation completed");
+            return true;
+        }
+        catch (error) {
+            log("error", "Auto-dream consolidation failed", { error: getErrorMessage(error) });
+            return false;
+        }
+        finally {
+            this.lock.release();
+        }
+    }
+}

package/dist/extraction/forkSession.d.ts

@@ -0,0 +1,37 @@
+import { type OpencodeClient } from "../sdk.js";
+export declare const FORK_CREATE_TIMEOUT_MS = 30000;
+export declare const FORK_CLEANUP_TIMEOUT_MS = 15000;
+export type ForkCleanupStage = "abort" | "delete";
+export type ForkSessionInput = {
+    client: OpencodeClient;
+    directory: string;
+    parentSessionID?: string;
+    title: string;
+    agent: string;
+    system?: string;
+    parts: Array<{
+        type: "text";
+        text: string;
+    }>;
+    tools?: Record<string, boolean>;
+    format?: unknown;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+    timeoutMs: number;
+    createTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    onCreated?: (forkID: string) => void;
+    onFinished?: (forkID: string) => void;
+    onCleanupFailed?: (forkID: string, stage: ForkCleanupStage, error: unknown) => void;
+};
+export declare class ForkSessionTimeoutError extends Error {
+    constructor(title: string, timeoutMs: number);
+}
+export declare function extractSessionID(response: unknown): string | undefined;
+export declare function forkFailure(response: unknown): string | undefined;
+export declare class ForkSessionError extends Error {
+    constructor(title: string, detail: string);
+}
+export declare function runForkSession(input: ForkSessionInput): Promise<unknown>;