om-memory-system 5.1.0 → 5.3.0

package/dist/core/recall-summary.js

@@ -0,0 +1,71 @@
+const QUERY_CUT = 60;
+const UNFOLDED_QUERY_CUT = 300;
+const HEADLINE_CUT = 140;
+/** Query on one line, cut to `max` characters. */
+export function queryLine(query, max = QUERY_CUT) {
+    const line = query.replace(/\s+/g, " ").trim();
+    return line.length > max ? `${line.slice(0, max - 3)}...` : line;
+}
+// Entry shape comes from `formatContextForPrompt`: `<memory id="..." relevance="N%">`, with the
+// id missing when the result had none. A body ends at its own `</memory>` when another entry, a
+// section close or the end of the text follows it. The Claude Code hook can cut a block short and
+// leave tags open, so a body also ends at a section close or at the end of the text. An opening
+// tag inside the text, even at the start of a line, does not end it: a memory can quote the tag.
+const SECTION_CLOSE = String.raw `<\/project_knowledge>|<\/memory_context>|<\/omms-retrieval>`;
+const MEMORY_ENTRY = new RegExp(String.raw `<memory(?:\s+id="([^"]*)")?\s+relevance="(\d+)%">([\s\S]*?)` +
+    String.raw `(?=<\/memory>\s*(?:<memory\s|${SECTION_CLOSE}|$)|${SECTION_CLOSE}|$)`, "g");
+/** One line that names a memory: the first line under `## Request`, else the first line. */
+export function headline(body) {
+    const lines = body
+        .replace(/<\/memory>\s*$/, "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const heading = lines.findIndex((line) => /^##\s*request\s*$/i.test(line));
+    const line = (heading >= 0 ? lines[heading + 1] : lines[0]) ?? "";
+    return line.length > HEADLINE_CUT ? `${line.slice(0, HEADLINE_CUT - 3)}...` : line;
+}
+/**
+ * Summarise a formatted retrieval section for a host to show. Returns null when the section holds
+ * no memory (a profile-only section included), so the host draws nothing. A `recent` recall has
+ * no query, whatever the caller passes.
+ */
+export function buildRecallSummary(section, mode, query) {
+    const items = [];
+    for (const match of section.matchAll(MEMORY_ENTRY)) {
+        const text = headline(match[3] ?? "");
+        if (!text)
+            continue;
+        const item = { relevance: Number(match[2]), headline: text };
+        if (match[1])
+            item.id = match[1];
+        items.push(item);
+    }
+    if (items.length === 0)
+        return null;
+    return { mode, query: mode === "recent" ? null : query, items };
+}
+/** Escape backslashes and double quotes so the quoted value in the title reads as one string. */
+function escapeQuoted(text) {
+    return text.replace(/[\\"]/g, "\\$&");
+}
+/** `memory [mode=search, query="...", limit=4]`: the call's name and arguments, as a tool row shows them. */
+export function callTitle(summary) {
+    const args = [`mode=${summary.mode}`];
+    if (summary.query)
+        args.push(`query="${escapeQuoted(queryLine(summary.query))}"`);
+    args.push(`limit=${summary.items.length}`);
+    return `memory [${args.join(", ")}]`;
+}
+/** Body of an unfolded row, one string per line, without indentation (the host indents). */
+export function unfoldLines(summary) {
+    const lines = [`mode: ${summary.mode}`];
+    if (summary.query)
+        lines.push(`query: ${queryLine(summary.query, UNFOLDED_QUERY_CUT)}`);
+    lines.push(`limit: ${summary.items.length}`);
+    summary.items.forEach((item, index) => {
+        const id = item.id ? ` id=${item.id}` : "";
+        lines.push(`${index + 1}. ${item.relevance}%${id} ${item.headline}`);
+    });
+    return lines;
+}

package/dist/index.js

@@ -161,7 +161,7 @@ export async function configureOpencodeHostTransport(ctx) {
     if (hostConfig.fetch) {
         setHostFetch(hostConfig.fetch);
     }
-    else {
+    else if (!hostConfig.inProcess) {
         log("OpenCode host fetch unavailable; falling back to global fetch", {
             clientKeys: hostConfig.clientKeys,
             sdkConfigCount: hostConfig.sdkConfigCount,

package/dist/services/single-flight.d.ts

@@ -0,0 +1,2 @@
+/** Like setInterval, but skips a tick while the previous run of the task is still pending. */
+export declare function setSingleFlightInterval(task: () => Promise<void>, ms: number): NodeJS.Timeout;

package/dist/services/single-flight.js

@@ -0,0 +1,12 @@
+/** Like setInterval, but skips a tick while the previous run of the task is still pending. */
+export function setSingleFlightInterval(task, ms) {
+    let running = false;
+    return setInterval(() => {
+        if (running)
+            return;
+        running = true;
+        void task().finally(() => {
+            running = false;
+        });
+    }, ms);
+}

package/dist/services/visible-recall-config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `visibleRecall` setting (change add-opencode-v2-visible-recall), kept out
+ * of `src/config.ts` to save its lines. Pure on purpose: callers pass the file
+ * config and a log function, and the loaded `CONFIG` is never imported here,
+ * because many tests stub `src/config.js`.
+ *
+ * Read the effective value from `CONFIG.visibleRecall`. It is on by default,
+ * and only an explicit `false` turns it off.
+ */
+/**
+ * The key as it appears in a config file. `OmmsConfig` in `src/config.ts` has
+ * no field for it, to save lines, so the functions take `FileConfigWithKey`,
+ * which any config object satisfies. A hand-edited file can hold any value,
+ * which is why they compare with `=== false`.
+ */
+export interface VisibleRecallFileKey {
+    /** Draw a row in the OpenCode TUI for each memory recall. Default true. A project can only turn it off. */
+    visibleRecall?: boolean;
+}
+type FileConfigWithKey = VisibleRecallFileKey & object;
+/** Read the setting from a merged file config. Unset means on. */
+export declare function visibleRecallFromFile(fileConfig: FileConfigWithKey): {
+    visibleRecall: boolean;
+};
+/**
+ * Apply the project rule to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn the rows off, so a value
+ * of `false` stays. Any other project value is dropped, so the global value
+ * decides. A project value of `true` is also reported through `log`.
+ */
+export declare function applyProjectVisibleRecall(project: FileConfigWithKey, overrides: FileConfigWithKey, directory: string, log: (message: string, data: {
+    directory: string;
+}) => void): void;
+export {};

package/dist/services/visible-recall-config.js

@@ -0,0 +1,27 @@
+/**
+ * The `visibleRecall` setting (change add-opencode-v2-visible-recall), kept out
+ * of `src/config.ts` to save its lines. Pure on purpose: callers pass the file
+ * config and a log function, and the loaded `CONFIG` is never imported here,
+ * because many tests stub `src/config.js`.
+ *
+ * Read the effective value from `CONFIG.visibleRecall`. It is on by default,
+ * and only an explicit `false` turns it off.
+ */
+/** Read the setting from a merged file config. Unset means on. */
+export function visibleRecallFromFile(fileConfig) {
+    return { visibleRecall: fileConfig.visibleRecall !== false };
+}
+/**
+ * Apply the project rule to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn the rows off, so a value
+ * of `false` stays. Any other project value is dropped, so the global value
+ * decides. A project value of `true` is also reported through `log`.
+ */
+export function applyProjectVisibleRecall(project, overrides, directory, log) {
+    if (project.visibleRecall === false)
+        return;
+    delete overrides.visibleRecall;
+    if (project.visibleRecall === true) {
+        log("Project config cannot turn on visibleRecall; the value was ignored", { directory });
+    }
+}

package/dist/services/web-ensure.d.ts

@@ -70,6 +70,17 @@ export declare const START_LOCK_STALE_MS = 20000;
 export declare function startLockPath(home?: string): string;
 /** Lock files are private to the user (0600 in a 0700 folder), like the token file. */
 export declare const nodeLockFs: LockFs;
+/**
+ * `nodeLockFs.replace`: write the temp file, rename it over the target, and
+ * when the rename reports ENOENT for a temp file that was just written,
+ * rewrite it and try again, up to `rewrites` times.
+ */
+export declare function replaceRetrying(path: string, text: string, deps?: {
+    mkdir?: (dir: string) => void;
+    write?: (path: string, text: string) => void;
+    rename?: (from: string, to: string) => void;
+    rewrites?: number;
+}, rewrites?: number): void;
 /** `renameSync` that retries while Windows reports the target busy. */
 export declare function renameRetrying(from: string, to: string, rename?: (from: string, to: string) => void, platform?: NodeJS.Platform, wait?: (ms: number) => void): void;
 /** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */

package/dist/services/web-ensure.js

@@ -70,16 +70,45 @@ export const nodeLockFs = {
         }
     },
     replace(path, text) {
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        const temp = `${path}.${process.pid}.tmp`;
-        writeFileSync(temp, text, { mode: 0o600 });
-        renameRetrying(temp, path);
+        replaceRetrying(path, text);
     },
 };
 // Windows can refuse a link or rename while another process has the file open.
 // Bound retries so a permanent permission error still reaches the caller.
 const WINDOWS_FILE_RETRY_WAITS_MS = [1, 2, 5, 10, 20, 50, 100, 200];
 const WINDOWS_FILE_BUSY_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+/**
+ * How many times `replaceRetrying` rewrites its temp file when `rename`
+ * reports ENOENT for a file that was just written. Bun's rename can
+ * intermittently do that (see docs/tdr/030-intermittent-bun-rename-failure.md),
+ * which made tests/web-ensure.test.ts fail at random under load. Rewriting
+ * and retrying heals that without weakening a genuine failure, which keeps
+ * failing past this budget and still reaches the caller.
+ */
+const REPLACE_ENOENT_REWRITES = 3;
+/**
+ * `nodeLockFs.replace`: write the temp file, rename it over the target, and
+ * when the rename reports ENOENT for a temp file that was just written,
+ * rewrite it and try again, up to `rewrites` times.
+ */
+export function replaceRetrying(path, text, deps = {}, rewrites = deps.rewrites ?? REPLACE_ENOENT_REWRITES) {
+    const mkdir = deps.mkdir ?? ((dir) => mkdirSync(dir, { recursive: true, mode: 0o700 }));
+    const write = deps.write ?? ((file, body) => writeFileSync(file, body, { mode: 0o600 }));
+    const rename = deps.rename ?? ((from, to) => renameRetrying(from, to));
+    mkdir(dirname(path));
+    const temp = `${path}.${process.pid}.tmp`;
+    for (let attempt = 0;; attempt++) {
+        write(temp, text);
+        try {
+            rename(temp, path);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || attempt >= rewrites)
+                throw error;
+        }
+    }
+}
 /** `renameSync` that retries while Windows reports the target busy. */
 export function renameRetrying(from, to, rename = renameSync, platform = process.platform, wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)) {
     for (let attempt = 0;; attempt++) {

package/dist/services/web-server.d.ts

@@ -48,6 +48,7 @@ export declare class WebServer {
     private holdOffTimer;
     private portsExhaustedNotified;
     private takeoverFailures;
+    private lastHealthFailure;
     private readonly maxFallbackPort;
     private settingsImportJobs?;
     private backfillControlsInstance?;
@@ -99,6 +100,8 @@ export declare class WebServer {
     isRunning(): boolean;
     isServerOwner(): boolean;
     getUrl(): string;
+    /** Why the last `checkServerAvailable` call said no, or null when it said yes. */
+    getLastHealthFailure(): string | null;
     checkServerAvailable(): Promise<boolean>;
     private handleRequest;
     private contentTypeFor;

package/dist/services/web-server.js

@@ -13,10 +13,13 @@ import { AUTH_HEADER, getOrCreateAuthToken, isAuthorizedApiRequest } from "./aut
 import { WebAuth } from "./web-auth.js";
 import { NODE_HTTP_IDLE_TIMEOUT_MS } from "./request-timeouts.js";
 import { testReranker } from "./reranker-test.js";
+import { setSingleFlightInterval } from "./single-flight.js";
 import { handleListTags, handleListKeywords, handleListMemories, handleAddMemory, handleDeleteMemory, handleBulkDelete, handleUpdateMemory, handleSearch, handleStats, handlePinMemory, handleUnpinMemory, handleRunCleanup, handleRunDeduplication, handleDetectMigration, handleRunMigration, handleDetectTagMigration, handleRunTagMigrationBatch, handleGetTagMigrationProgress, handleDeletePrompt, handleBulkDeletePrompts, handleGetUserProfile, handleGetProfileChangelog, handleGetProfileSnapshot, handleRefreshProfile, handleUpdateProfileItem, } from "./api-handlers.js";
 import { routeModules } from "./web-route-modules.js";
 const isBun = typeof globalThis.Bun !== "undefined";
 const MIN_FAILED_TAKEOVERS = 3;
+/** A busy owner can answer late. Two seconds was short enough to call a live owner dead. */
+const HEALTH_CHECK_TIMEOUT_MS = 8_000;
 export function attachNodeDisconnectHandlers(req, res, onDisconnect) {
     let disconnected = false;
     const disconnectOnce = () => {
@@ -175,6 +178,7 @@ export class WebServer {
     holdOffTimer = null;
     portsExhaustedNotified = false;
     takeoverFailures = 0;
+    lastHealthFailure = null;
     maxFallbackPort;
     settingsImportJobs;
     backfillControlsInstance;
@@ -584,7 +588,7 @@ export class WebServer {
         if (this.healthCheckInterval) {
             return;
         }
-        this.healthCheckInterval = setInterval(() => void this.waiterTick(), 5000);
+        this.healthCheckInterval = setSingleFlightInterval(() => this.waiterTick(), 5000);
     }
     /** One check of a web app that waits for the port. */
     async waiterTick() {
@@ -667,6 +671,8 @@ export class WebServer {
             log("Web server port held by a non-responsive process; falling back to next port", {
                 previousPort: this.config.port,
                 newPort: nextPort,
+                lastFailure: this.lastHealthFailure,
+                healthTimeoutMs: HEALTH_CHECK_TIMEOUT_MS,
             }, "warn");
             this.config.port = nextPort;
         }
@@ -743,6 +749,10 @@ export class WebServer {
     getUrl() {
         return webServerUrl(this.config.host, this.config.port);
     }
+    /** Why the last `checkServerAvailable` call said no, or null when it said yes. */
+    getLastHealthFailure() {
+        return this.lastHealthFailure;
+    }
     async checkServerAvailable() {
         try {
             // Only a web app on this machine answers here, so the local token file is enough.
@@ -751,20 +761,28 @@ export class WebServer {
             const response = await fetch(`${this.getUrl()}${endpoint}`, {
                 method: "GET",
                 headers,
-                signal: AbortSignal.timeout(2000),
+                signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
             });
-            if (!response.ok)
+            if (!response.ok) {
+                this.lastHealthFailure = `http ${response.status}`;
                 return false;
+            }
             // Fallback spans 10 neighbor ports; any 2xx from an unrelated local
             // service must not be mistaken for an omms owner. Require the
             // response to carry our API envelope.
             const body = (await response.json());
-            if (endpoint === "/api/health") {
-                return body.success === true && body.status === "ok";
-            }
-            return body.success === true;
+            const ok = body.success === true && (endpoint !== "/api/health" || body.status === "ok");
+            this.lastHealthFailure = ok ? null : "unexpected response";
+            return ok;
         }
-        catch {
+        catch (error) {
+            const name = error instanceof Error ? error.name : "";
+            this.lastHealthFailure =
+                name === "TimeoutError"
+                    ? "timeout"
+                    : error instanceof Error
+                        ? error.message
+                        : String(error);
             return false;
         }
     }

package/dist/v2/adapter.js

@@ -4,6 +4,7 @@ import { SKILLS_TOOL_INPUT_SCHEMA } from "../core/skills-tool.js";
 import { log } from "../services/logger.js";
 import { utf8ByteLength } from "../utils/context-limit.js";
 import { eventBelongsToLocation, legacyToolResult, toLegacyEvent } from "./legacy-client.js";
+import { createRecallReporter } from "./recall-reporter.js";
 const memoryInput = {
     type: "object",
     properties: {
@@ -75,7 +76,9 @@ export async function registerV2Adapter(ctx, legacy, memory) {
     // until their message appears in a model request's history (the context
     // hook), and are only then recorded for auto-capture and profile learning.
     const pendingPrompts = new Map();
+    const recall = await createRecallReporter(ctx, memory, setBounded);
     const forgetSession = (sessionID) => {
+        recall.forget(sessionID);
         retrievals.delete(sessionID);
         restored.delete(sessionID);
         messageIDs.delete(sessionID);
@@ -186,7 +189,7 @@ export async function registerV2Adapter(ctx, legacy, memory) {
             log("v2 prompt: memory retrieval failed", { sessionID, error: String(error) }, "error");
             return null;
         });
-        setBounded(retrievals, sessionID, { promise, budgetBytes });
+        setBounded(retrievals, sessionID, { promise, budgetBytes, query: text });
     });
     await ctx.session.hook("context", async (event) => {
         const sessionID = event.sessionID;
@@ -201,6 +204,7 @@ export async function registerV2Adapter(ctx, legacy, memory) {
             const section = await settledRetrieval(retrieval);
             if (section) {
                 event.system.push({ type: "text", text: section });
+                recall.record(sessionID, retrieval, retrieval.query, section);
                 remainingBytes = retrieval.budgetBytes - utf8ByteLength(section);
             }
             else {
@@ -266,6 +270,7 @@ export async function registerV2Adapter(ctx, legacy, memory) {
         restored.clear();
         messageIDs.clear();
         pendingPrompts.clear();
+        recall.clear();
         await legacy.dispose?.();
     };
 }

package/dist/v2/legacy-client.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { markInProcessClient } from "../adapters/opencode/in-process-client.js";
 function textFromParts(parts = []) {
     return parts
         .filter((part) => part.type === "text")
@@ -216,7 +217,7 @@ export function createLegacyClient(ctx) {
             },
         },
     };
-    return client;
+    return markInProcessClient(client);
 }
 export function legacyToolResult(value) {
     if (typeof value === "string")

package/dist/v2/memory-bridge.d.ts

@@ -8,6 +8,8 @@ export interface V2MemoryBridge {
     isConfigured(): boolean;
     isInjectionEnabled(): boolean;
     isCompactionEnabled(): boolean;
+    /** Effective `visibleRecall` setting for this project, from a fresh config read. */
+    isVisibleRecallEnabled(): boolean;
     isInternalPrompt(sessionID: string, text: string): boolean;
     recordPrompt(sessionID: string, messageID: string, text: string): Promise<void>;
     /**

package/dist/v2/memory-bridge.js

@@ -11,6 +11,10 @@ export function createV2MemoryBridge(directory) {
         isConfigured,
         isInjectionEnabled: () => isConfigured() && Boolean(CONFIG.chatMessage.enabled),
         isCompactionEnabled: () => isConfigured() && Boolean(CONFIG.compaction.enabled),
+        isVisibleRecallEnabled() {
+            refreshConfigIfChanged(directory);
+            return CONFIG.visibleRecall !== false;
+        },
         isInternalPrompt,
         async recordPrompt(sessionID, messageID, text) {
             await recordUserPrompt(sessionID, messageID, directory, text);

package/dist/v2/recall-reporter.d.ts

@@ -0,0 +1,24 @@
+import type { Context } from "@opencode/plugin/promise/plugin";
+import type { V2MemoryBridge } from "./memory-bridge.js";
+/** Latest summaries kept per session. The TUI shows recent rows, so older ones are dropped. */
+export declare const MAX_RECALL_SUMMARIES = 20;
+/** Longest query kept per summary. The TUI shows at most 300 characters of it. */
+export declare const MAX_RECALL_QUERY_CHARS = 300;
+type Bound = <V>(map: Map<string, V>, key: string, value: V) => void;
+export interface RecallReporter {
+    /**
+     * Record the summary of one prompt retrieval. `token` identifies the retrieval: model steps
+     * that reuse it record once. A section with no memory entries records nothing, and neither
+     * does a subagent session (one with a parent). The call does not wait for the session lookup.
+     */
+    record(sessionID: string, token: object, query: string, section: string | null): void;
+    forget(sessionID: string): void;
+    clear(): void;
+}
+/**
+ * Keeps a bounded per-session ring of recall summaries and serves it over plugin RPC to the TUI
+ * entrypoint. It never throws and never touches what is injected. Logs carry the mode, count and
+ * session id only, never memory text or the query.
+ */
+export declare function createRecallReporter(ctx: Context, memory: V2MemoryBridge, bound: Bound): Promise<RecallReporter>;
+export {};

package/dist/v2/recall-reporter.js

@@ -0,0 +1,128 @@
+import { buildRecallSummary } from "../core/recall-summary.js";
+import { log } from "../services/logger.js";
+import { recallRpc } from "./recall-rpc.js";
+/** Latest summaries kept per session. The TUI shows recent rows, so older ones are dropped. */
+export const MAX_RECALL_SUMMARIES = 20;
+/** Longest query kept per summary. The TUI shows at most 300 characters of it. */
+export const MAX_RECALL_QUERY_CHARS = 300;
+/**
+ * Keeps a bounded per-session ring of recall summaries and serves it over plugin RPC to the TUI
+ * entrypoint. It never throws and never touches what is injected. Logs carry the mode, count and
+ * session id only, never memory text or the query.
+ */
+export async function createRecallReporter(ctx, memory, bound) {
+    const rings = new Map();
+    // Last number given per session. It keeps rising when the ring drops old entries.
+    const sequences = new Map();
+    const recorded = new WeakSet();
+    // One lookup per session. The promise is cached so concurrent records keep their order.
+    const subagents = new Map();
+    // Records waiting on a session lookup. `forget` and `clear` cancel them, so a late lookup cannot
+    // store a summary for a session whose state is gone. Entries leave when their lookup settles.
+    const pending = new Map();
+    let emit;
+    try {
+        const registration = await ctx.rpc.register(recallRpc, {
+            // The contract is plain JSON schema, so the host types the input as unknown.
+            list: async (input) => ({
+                enabled: memory.isVisibleRecallEnabled(),
+                items: [...(rings.get(input.sessionID) ?? [])],
+            }),
+        });
+        emit = (sessionID) => registration.events.emit("recalled", { sessionID });
+    }
+    catch (error) {
+        log("v2 recall: rpc registration failed", { error: String(error) }, "error");
+    }
+    const notify = (sessionID) => {
+        try {
+            emit?.(sessionID).catch((error) => log("v2 recall: push failed", { sessionID, error: String(error) }, "error"));
+        }
+        catch (error) {
+            log("v2 recall: push failed", { sessionID, error: String(error) }, "error");
+        }
+    };
+    // A session with a parent is a subagent session. A failed lookup counts as a root session, so
+    // the summary still shows.
+    const isSubagent = (sessionID) => {
+        const known = subagents.get(sessionID);
+        if (known)
+            return known;
+        const lookup = (async () => {
+            try {
+                const info = await ctx.session.get({ sessionID });
+                return Boolean(info?.parentID);
+            }
+            catch (error) {
+                log("v2 recall: session lookup failed", { sessionID, error: String(error) }, "error");
+                return false;
+            }
+        })();
+        bound(subagents, sessionID, lookup);
+        return lookup;
+    };
+    const store = (sessionID, built) => {
+        const seq = (sequences.get(sessionID) ?? 0) + 1;
+        bound(sequences, sessionID, seq);
+        const summary = { ...built, seq };
+        const ring = [...(rings.get(sessionID) ?? []), summary].slice(-MAX_RECALL_SUMMARIES);
+        bound(rings, sessionID, ring);
+        log("v2 recall: summary recorded", {
+            sessionID,
+            mode: summary.mode,
+            count: summary.items.length,
+        });
+        notify(sessionID);
+    };
+    return {
+        record(sessionID, token, query, section) {
+            if (recorded.has(token))
+                return;
+            recorded.add(token);
+            try {
+                const summary = section
+                    ? buildRecallSummary(section, "search", query.slice(0, MAX_RECALL_QUERY_CHARS))
+                    : null;
+                if (!summary)
+                    return;
+                const ticket = { cancelled: false };
+                const tickets = pending.get(sessionID) ?? new Set();
+                tickets.add(ticket);
+                pending.set(sessionID, tickets);
+                void isSubagent(sessionID).then((subagent) => {
+                    tickets.delete(ticket);
+                    if (tickets.size === 0 && pending.get(sessionID) === tickets)
+                        pending.delete(sessionID);
+                    if (subagent || ticket.cancelled)
+                        return;
+                    try {
+                        store(sessionID, summary);
+                    }
+                    catch (error) {
+                        log("v2 recall: could not record summary", { sessionID, error: String(error) }, "error");
+                    }
+                });
+            }
+            catch (error) {
+                log("v2 recall: could not record summary", { sessionID, error: String(error) }, "error");
+            }
+        },
+        forget: (sessionID) => {
+            for (const ticket of pending.get(sessionID) ?? [])
+                ticket.cancelled = true;
+            pending.delete(sessionID);
+            rings.delete(sessionID);
+            sequences.delete(sessionID);
+            subagents.delete(sessionID);
+        },
+        clear: () => {
+            for (const tickets of pending.values())
+                for (const ticket of tickets)
+                    ticket.cancelled = true;
+            pending.clear();
+            rings.clear();
+            sequences.clear();
+            subagents.clear();
+        },
+    };
+}

package/dist/v2/recall-rpc.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Plugin RPC contract between the OpenCode v2 server entrypoint (records recall summaries) and the
+ * terminal TUI entrypoint (draws them). Plain data on purpose: no host SDK import, so both sides and
+ * the tests can load it. The TUI pulls `list` and treats `recalled` as a refresh hint only; a missing
+ * push never breaks the rows (TDR-060).
+ */
+export declare const RECALL_RPC_ID = "omms-recall";
+export declare const recallRpc: {
+    readonly id: "omms-recall";
+    readonly methods: {
+        readonly list: {
+            readonly input: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly sessionID: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["sessionID"];
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly enabled: {
+                        readonly type: "boolean";
+                    };
+                    readonly items: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                        };
+                    };
+                };
+                readonly required: readonly ["enabled", "items"];
+            };
+        };
+    };
+    readonly events: {
+        readonly recalled: {
+            readonly schema: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly sessionID: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["sessionID"];
+            };
+        };
+    };
+};

package/dist/v2/recall-rpc.js

@@ -0,0 +1,38 @@
+/**
+ * Plugin RPC contract between the OpenCode v2 server entrypoint (records recall summaries) and the
+ * terminal TUI entrypoint (draws them). Plain data on purpose: no host SDK import, so both sides and
+ * the tests can load it. The TUI pulls `list` and treats `recalled` as a refresh hint only; a missing
+ * push never breaks the rows (TDR-060).
+ */
+export const RECALL_RPC_ID = "omms-recall";
+export const recallRpc = {
+    id: RECALL_RPC_ID,
+    methods: {
+        // `enabled` is the effective `visibleRecall` setting for the server's project, so the TUI never
+        // reads config. Summaries are recorded and served even when it is false.
+        list: {
+            input: {
+                type: "object",
+                properties: { sessionID: { type: "string" } },
+                required: ["sessionID"],
+            },
+            output: {
+                type: "object",
+                properties: {
+                    enabled: { type: "boolean" },
+                    items: { type: "array", items: { type: "object" } },
+                },
+                required: ["enabled", "items"],
+            },
+        },
+    },
+    events: {
+        recalled: {
+            schema: {
+                type: "object",
+                properties: { sessionID: { type: "string" } },
+                required: ["sessionID"],
+            },
+        },
+    },
+};