opencode-claude-memory 2.0.2 → 2.1.0

package/dist/host/v2/events.js

@@ -0,0 +1,137 @@
+import { SESSION_STATE_TTL_MS } from "../../recall/RecallCoordinator.js";
+import { surfaceKey } from "../../store/scan.js";
+const IDLE_EVENTS = [
+    "session.execution.succeeded",
+    "session.execution.failed",
+    "session.execution.interrupted",
+    "session.idle",
+];
+export class V2SessionEvents {
+    deps;
+    // Tracked sessions → last time a hook or event saw them. Entries idle for longer than
+    // SESSION_STATE_TTL_MS are evicted so a long-running server does not leak; the next prompt or
+    // context hook tracks the session again.
+    sessions = new Map();
+    // Memories recalled per session, keyed by `surfaceKey`. V2 rebuilds the system prompt for every
+    // model request and does not keep it in the history, so the recalled section is re-injected on
+    // every request (not only the first one of a turn) and its keys are what the selector skips.
+    recalled = new Map();
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    track(sessionID) {
+        if (this.deps.owned.has(sessionID))
+            return;
+        const now = this.now();
+        this.evictStale(now);
+        this.sessions.set(sessionID, now);
+    }
+    isTracked(sessionID) {
+        return this.sessions.has(sessionID);
+    }
+    surfacedKeys(sessionID) {
+        return new Set(this.recalled.get(sessionID)?.keys() ?? []);
+    }
+    // Adds the memories recalled for this request and returns everything recalled so far in the session.
+    remember(sessionID, memories) {
+        let session = this.recalled.get(sessionID);
+        if (!session && memories.length > 0) {
+            session = new Map();
+            this.recalled.set(sessionID, session);
+        }
+        for (const memory of memories) {
+            session?.set(surfaceKey({ name: memory.name, type: memory.type }), memory);
+        }
+        return [...(session?.values() ?? [])];
+    }
+    evictStale(now) {
+        const cutoff = now - SESSION_STATE_TTL_MS;
+        for (const [id, seenAt] of this.sessions) {
+            if (seenAt >= cutoff)
+                continue;
+            this.sessions.delete(id);
+            this.recalled.delete(id);
+        }
+    }
+    handle(event) {
+        const type = event?.type;
+        const data = event?.data;
+        if (!type || !data)
+            return;
+        const sessionID = typeof data.sessionID === "string" ? data.sessionID : undefined;
+        if (!sessionID)
+            return;
+        if (type === "session.deleted") {
+            this.deps.owned.release(sessionID, 5_000);
+            this.forget(sessionID);
+            return;
+        }
+        if (type === "session.created") {
+            const directory = data.location?.directory ?? event.location?.directory;
+            if (directory === this.deps.directory && !data.parentID)
+                this.track(sessionID);
+            return;
+        }
+        if (this.deps.owned.has(sessionID) || !this.sessions.has(sessionID))
+            return;
+        this.sessions.set(sessionID, this.now());
+        if (type === "session.execution.started") {
+            this.deps.extraction.onSessionStatus(sessionID, "busy");
+        }
+        else if (IDLE_EVENTS.includes(type)) {
+            this.deps.extraction.onSessionIdle(sessionID);
+        }
+        else if (type === "session.status") {
+            const status = data.status?.type;
+            if (status === "idle")
+                this.deps.extraction.onSessionIdle(sessionID);
+            else if (typeof status === "string")
+                this.deps.extraction.onSessionStatus(sessionID, status);
+        }
+    }
+    forget(sessionID) {
+        this.sessions.delete(sessionID);
+        this.recalled.delete(sessionID);
+        this.deps.recall.forget(sessionID);
+        this.deps.extraction.onSessionDeleted(sessionID);
+    }
+}
+export const RESUBSCRIBE_MIN_MS = 1_000;
+export const RESUBSCRIBE_MAX_MS = 30_000;
+// Consumes the event stream until `signal` aborts. A stream that fails (a slow consumer overflows
+// it) is re-opened with a capped backoff.
+export async function consumeEvents(subscribe, signal, onEvent, onError, backoff = { minMs: RESUBSCRIBE_MIN_MS, maxMs: RESUBSCRIBE_MAX_MS }) {
+    let delay = backoff.minMs;
+    while (!signal.aborted) {
+        try {
+            for await (const event of subscribe({ signal })) {
+                if (signal.aborted)
+                    return;
+                delay = backoff.minMs;
+                try {
+                    onEvent(event);
+                }
+                catch (error) {
+                    onError(error);
+                }
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            onError(error);
+        }
+        if (signal.aborted)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, delay);
+            signal.addEventListener("abort", () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        });
+        delay = Math.min(delay * 2, backoff.maxMs);
+    }
+}

package/dist/host/v2/fork.d.ts

@@ -0,0 +1,76 @@
+import type { ForkInput } from "../types.js";
+export declare const FORK_CREATE_TIMEOUT_MS = 30000;
+export declare const FORK_CLEANUP_TIMEOUT_MS = 15000;
+export declare const FORK_READ_TIMEOUT_MS = 30000;
+export declare const FORK_SETTLE_POLL_MS = 250;
+export type PermissionRule = {
+    action: string;
+    resource: string;
+    effect: "allow" | "deny" | "ask";
+};
+export type ModelRef = {
+    id: string;
+    providerID: string;
+    variant?: string;
+};
+export type V2Message = {
+    id: string;
+    type: string;
+    time?: {
+        created?: number;
+        completed?: number;
+    };
+    text?: string;
+    finish?: string;
+    error?: unknown;
+    content?: unknown;
+};
+export type V2SessionApi = {
+    create(input: {
+        parentID?: string;
+        title?: string;
+        agent?: string;
+        model?: ModelRef;
+        permissions?: PermissionRule[];
+    }): Promise<{
+        id: string;
+    }>;
+    prompt(input: {
+        sessionID: string;
+        text: string;
+    }): Promise<unknown>;
+    wait(input: {
+        sessionID: string;
+    }): Promise<unknown>;
+    context(input: {
+        sessionID: string;
+    }): Promise<readonly V2Message[]>;
+    interrupt(input: {
+        sessionID: string;
+    }): Promise<unknown>;
+    remove(input: {
+        sessionID: string;
+    }): Promise<unknown>;
+};
+export type V2ForkInput = ForkInput & {
+    permissions: PermissionRule[];
+    model?: ModelRef;
+    createTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    pollMs?: number;
+};
+export declare class ForkSessionTimeoutError extends Error {
+    constructor(title: string, timeoutMs: number);
+}
+export declare class ForkSessionError extends Error {
+    constructor(title: string, detail: string);
+}
+type Outcome = {
+    done: true;
+    failure?: string;
+} | {
+    done: false;
+};
+export declare function forkOutcome(messages: readonly V2Message[], promptID: string | undefined): Outcome;
+export declare function runV2Fork(session: V2SessionApi, input: V2ForkInput): Promise<readonly V2Message[]>;
+export {};

package/dist/host/v2/fork.js

@@ -0,0 +1,136 @@
+// Lifecycle of a plugin-owned V2 child session: create(agent) → prompt → wait → context → remove.
+// `prompt` only enqueues the message and `wait` resolves once the session loop is idle again, so the
+// outcome is read back from the context: the fork succeeded when the last assistant message is
+// complete and carries no error. On timeout the fork is interrupted before it is removed.
+//
+// The plugin-facing session API takes no AbortSignal, so every call is bounded with withTimeout; a
+// hung host call must never pin the extraction queue or the maintenance lock.
+import { TimeoutError, withDeadline } from "../../util/timeout.js";
+export const FORK_CREATE_TIMEOUT_MS = 30_000;
+export const FORK_CLEANUP_TIMEOUT_MS = 15_000;
+export const FORK_READ_TIMEOUT_MS = 30_000;
+// `wait` can return before an enqueued prompt was admitted; re-check this often until the deadline.
+export const FORK_SETTLE_POLL_MS = 250;
+export class ForkSessionTimeoutError extends Error {
+    constructor(title, timeoutMs) {
+        super(`${title} timed out after ${timeoutMs}ms`);
+        this.name = "ForkSessionTimeoutError";
+    }
+}
+export class ForkSessionError extends Error {
+    constructor(title, detail) {
+        super(`${title}: ${detail}`);
+        this.name = "ForkSessionError";
+    }
+}
+function describeError(error) {
+    if (error && typeof error === "object") {
+        const named = error;
+        const kind = typeof named.type === "string" ? named.type : named.name;
+        if (typeof named.message === "string")
+            return typeof kind === "string" ? `${kind}: ${named.message}` : named.message;
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
+// The V2 session API takes no AbortSignal; withDeadline only bounds the wait.
+function deadline(what, timeoutMs, call) {
+    return withDeadline(what, timeoutMs, () => call());
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// The fork is settled once an assistant message answers the prompt and it is complete.
+export function forkOutcome(messages, promptID) {
+    const promptIndex = promptID ? messages.findIndex((message) => message.id === promptID) : -1;
+    const answers = messages.slice(promptIndex + 1).filter((message) => message.type === "assistant");
+    const last = answers[answers.length - 1];
+    if (!last)
+        return { done: false };
+    if (last.error !== undefined && last.error !== null)
+        return { done: true, failure: describeError(last.error) };
+    if (last.time?.completed === undefined)
+        return { done: false };
+    if (last.finish === "error")
+        return { done: true, failure: "model finished with an error" };
+    return { done: true };
+}
+// Security: forks run on raw, potentially untrusted transcript content. The agent's ruleset and the
+// explicit session ruleset restrict them to the memory tools; the deadlines guarantee the caller gets
+// control back even when the fork hangs on a permission prompt or the server stops answering.
+export async function runV2Fork(session, input) {
+    const createTimeoutMs = input.createTimeoutMs ?? FORK_CREATE_TIMEOUT_MS;
+    const cleanupTimeoutMs = input.cleanupTimeoutMs ?? FORK_CLEANUP_TIMEOUT_MS;
+    const pollMs = input.pollMs ?? FORK_SETTLE_POLL_MS;
+    const created = await deadline(`${input.title} session.create`, createTimeoutMs, () => session.create({
+        ...(input.parentSessionID ? { parentID: input.parentSessionID } : {}),
+        title: input.title,
+        agent: input.agent,
+        ...(input.model ? { model: input.model } : {}),
+        permissions: input.permissions,
+    }));
+    const forkID = created?.id;
+    if (typeof forkID !== "string")
+        throw new ForkSessionError(input.title, "session.create returned no session id");
+    input.onCreated?.(forkID);
+    const cleanup = async (stage) => {
+        try {
+            await deadline(`${input.title} session.${stage}`, cleanupTimeoutMs, () => stage === "abort" ? session.interrupt({ sessionID: forkID }) : session.remove({ sessionID: forkID }));
+        }
+        catch (error) {
+            input.onCleanupFailed?.(forkID, stage, error);
+        }
+    };
+    let timedOut = false;
+    try {
+        const started = Date.now();
+        const remaining = () => input.timeoutMs - (Date.now() - started);
+        const guarded = async (what, call, cap) => {
+            const left = remaining();
+            if (left <= 0) {
+                timedOut = true;
+                throw new ForkSessionTimeoutError(input.title, input.timeoutMs);
+            }
+            try {
+                return await deadline(`${input.title} ${what}`, Math.min(left, cap ?? left), call);
+            }
+            catch (error) {
+                if (error instanceof TimeoutError && remaining() <= 0) {
+                    timedOut = true;
+                    throw new ForkSessionTimeoutError(input.title, input.timeoutMs);
+                }
+                throw error;
+            }
+        };
+        const queued = await guarded("session.prompt", () => session.prompt({ sessionID: forkID, text: input.text }));
+        const promptID = queued && typeof queued === "object" && typeof queued.id === "string"
+            ? queued.id
+            : undefined;
+        for (;;) {
+            await guarded("session.wait", () => session.wait({ sessionID: forkID }));
+            const messages = await guarded("session.context", () => session.context({ sessionID: forkID }), FORK_READ_TIMEOUT_MS);
+            const outcome = forkOutcome(messages, promptID);
+            if (outcome.done) {
+                if (outcome.failure)
+                    throw new ForkSessionError(input.title, outcome.failure);
+                return messages;
+            }
+            // `wait` returned before the prompt was admitted or the answer completed.
+            await guarded("settle", () => sleep(pollMs));
+        }
+    }
+    finally {
+        try {
+            // On timeout the server is still running the fork: stop it before removing the session.
+            if (timedOut)
+                await cleanup("abort");
+            await cleanup("delete");
+        }
+        finally {
+            input.onFinished?.(forkID);
+        }
+    }
+}

package/dist/host/v2/host.d.ts

@@ -0,0 +1,33 @@
+import { type GenerateInput, type MemoryHost } from "../types.js";
+import { type ModelRef, type PermissionRule, type V2SessionApi } from "./fork.js";
+export type V2AgentInfo = {
+    model?: ModelRef;
+    permissions?: readonly PermissionRule[];
+};
+export type V2HostOptions = {
+    session: V2SessionApi;
+    generateText: (input: {
+        prompt: string;
+        model?: ModelRef;
+    }) => Promise<{
+        text: string;
+    }>;
+    getAgent: (name: string) => Promise<V2AgentInfo | undefined>;
+    sandboxFor: (name: string) => PermissionRule[];
+};
+export declare function buildGeneratePrompt(input: Pick<GenerateInput, "system" | "text" | "schema">): string;
+export declare class V2Host implements MemoryHost {
+    private readonly options;
+    private readonly forkSystems;
+    constructor(options: V2HostOptions);
+    systemFor(sessionID: string): string | undefined;
+    readTranscript(sessionID: string, afterMessageID?: string): Promise<{
+        messages: import("../types.js").TranscriptMessage[];
+        truncated: boolean;
+    }>;
+    listSessions(): Promise<undefined>;
+    runFork(input: Parameters<MemoryHost["runFork"]>[0]): Promise<void>;
+    generate(input: GenerateInput): Promise<string>;
+    private agent;
+    private fork;
+}

package/dist/host/v2/host.js

@@ -0,0 +1,87 @@
+// MemoryHost over the V2 plugin context (`setup` entry).
+//
+// Differences from V1 that the coordinators see through the interface:
+// - readTranscript only has the messages after the last compaction (`session.context`), so a
+//   watermark message that was compacted away yields `truncated: true`;
+// - listSessions is unavailable (the plugin API cannot list sessions);
+// - generate is a one-shot `generate.text` call: no system prompt, no structured output, so both
+//   are folded into the prompt and the caller parses the text.
+import { withDeadline } from "../../util/timeout.js";
+import { SDK_READ_TIMEOUT_MS } from "../types.js";
+import { runV2Fork } from "./fork.js";
+import { toTranscript } from "./transcript.js";
+// The V2 plugin calls take no AbortSignal; withDeadline only bounds the wait.
+function bounded(what, timeoutMs, call) {
+    return withDeadline(what, timeoutMs, () => call());
+}
+export function buildGeneratePrompt(input) {
+    const sections = [input.system?.trim(), input.text];
+    if (input.schema) {
+        sections.push(`Respond with only a JSON object matching this JSON schema, without code fences or commentary:\n${JSON.stringify(input.schema)}`);
+    }
+    return sections.filter((section) => Boolean(section)).join("\n\n");
+}
+export class V2Host {
+    options;
+    // Per-fork system prompt, injected by the context hook (V2 prompts carry no system field).
+    forkSystems = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    systemFor(sessionID) {
+        return this.forkSystems.get(sessionID);
+    }
+    async readTranscript(sessionID, afterMessageID) {
+        const messages = await bounded("session.context", SDK_READ_TIMEOUT_MS, () => this.options.session.context({ sessionID }));
+        const truncated = afterMessageID !== undefined && !messages.some((message) => message.id === afterMessageID);
+        return { messages: toTranscript(messages), truncated };
+    }
+    async listSessions() {
+        return undefined;
+    }
+    async runFork(input) {
+        await this.fork(input);
+    }
+    // One deadline for the agent lookup and the model call together, so the selector never outlives
+    // the caller's timeout (recall.timeoutMs).
+    async generate(input) {
+        const result = await bounded("generate.text", input.timeoutMs, async () => {
+            const agent = await this.agent(input.agent);
+            return this.options.generateText({
+                prompt: buildGeneratePrompt(input),
+                ...(agent?.model ? { model: agent.model } : {}),
+            });
+        });
+        return typeof result?.text === "string" ? result.text : "";
+    }
+    async agent(name) {
+        try {
+            return await bounded(`agent.get ${name}`, SDK_READ_TIMEOUT_MS, () => this.options.getAgent(name));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async fork(input) {
+        // The resolved agent's ruleset (sandbox + the user's overrides) is also passed as the session
+        // ruleset; without one the child would inherit its parent's session permissions.
+        const agent = await this.agent(input.agent);
+        const permissions = agent?.permissions?.length
+            ? agent.permissions.map((rule) => ({ ...rule }))
+            : this.options.sandboxFor(input.agent);
+        return runV2Fork(this.options.session, {
+            ...input,
+            permissions,
+            ...(agent?.model ? { model: agent.model } : {}),
+            onCreated: (id) => {
+                if (input.system)
+                    this.forkSystems.set(id, input.system);
+                input.onCreated?.(id);
+            },
+            onFinished: (id) => {
+                this.forkSystems.delete(id);
+                input.onFinished?.(id);
+            },
+        });
+    }
+}

package/dist/host/v2/log.d.ts

@@ -0,0 +1,4 @@
+import type { Logger } from "../../util/log.js";
+export declare const LOG_FILE = "opencode-memory.log";
+export declare const LOG_MAX_BYTES = 1000000;
+export declare function createFileLogger(stateDir: string, maxBytes?: number): Logger;

package/dist/host/v2/log.js

@@ -0,0 +1,40 @@
+// V2 gives plugins no log API (ctx.app is name/version/channel only) and runs them inside the server
+// process, whose stdout/stderr the background service discards or the standalone TUI shares. Log
+// lines therefore go to a file in the plugin state directory, next to extraction-state.json.
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const LOG_FILE = "opencode-memory.log";
+// Rotated once to `<file>.1` past this size, so a long-running server never grows it unbounded.
+export const LOG_MAX_BYTES = 1_000_000;
+function formatLine(level, message, extra) {
+    let suffix = "";
+    if (extra && Object.keys(extra).length > 0) {
+        try {
+            suffix = ` ${JSON.stringify(extra)}`;
+        }
+        catch {
+            suffix = " [unserializable extra]";
+        }
+    }
+    return `${new Date().toISOString()} ${level.toUpperCase()} ${message}${suffix}\n`;
+}
+// Best-effort and synchronous: a failing write is dropped, never thrown into a hook.
+export function createFileLogger(stateDir, maxBytes = LOG_MAX_BYTES) {
+    const file = join(stateDir, LOG_FILE);
+    return (level, message, extra) => {
+        try {
+            mkdirSync(stateDir, { recursive: true });
+            try {
+                if (statSync(file).size > maxBytes)
+                    renameSync(file, `${file}.1`);
+            }
+            catch {
+                // no log file yet
+            }
+            appendFileSync(file, formatLine(level, message, extra), "utf-8");
+        }
+        catch {
+            // best-effort
+        }
+    };
+}

package/dist/host/v2/plugin.d.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from "@opencode/plugin";
+import { z } from "zod/v4";
+import { type MemoryToolSpec } from "../../tools.js";
+export type V2Context = Plugin.Context;
+export type V2Cleanup = Plugin.Cleanup;
+export declare const SETUP_CALL_TIMEOUT_MS = 30000;
+export declare const CLEANUP_CALL_TIMEOUT_MS = 5000;
+export declare function toV2Tool(spec: MemoryToolSpec): {
+    name: "memory_save" | "memory_delete" | "memory_list" | "memory_search" | "memory_read";
+    description: string;
+    input: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$strip>;
+    options: {
+        codemode: boolean;
+    };
+    execute(input: unknown, context: {
+        sessionID: string;
+    }): Promise<{
+        metadata?: {
+            title: string;
+        } | undefined;
+        content: string;
+    }>;
+};
+export declare const createV2Setup: (env?: NodeJS.ProcessEnv, homeDir?: string) => (ctx: V2Context) => Promise<V2Cleanup>;