@codemem/opencode-plugin 0.44.2 → 0.45.0-rc.1

package/README.md

@@ -2,6 +2,10 @@
 
 Persistent memory plugin for [OpenCode](https://opencode.ai).
 
+Requires OpenCode 1.18.29 or newer. The same package also runs on OpenCode 2,
+validated against the exact stable `@opencode/cli@2.0.2` and
+`@opencode/plugin@2.0.2` releases. Codemem's OpenCode 2 integration is beta.
+
 ## Install
 
 Recommended:
@@ -21,12 +25,42 @@ Manual config also works. Add the package name to your OpenCode config:
 
 OpenCode installs npm plugins automatically with Bun at startup.
 
+Setup keeps the singular `plugin` key because OpenCode 1 requires it and
+OpenCode 2 translates it into its native `plugins` configuration. Keep one Codemem
+entry: if OpenCode loads Codemem twice for one project (for example a configured
+npm plugin plus a checkout-local `.opencode/plugins/` copy), the first
+registration wins and later copies skip their hooks with a warning in
+`~/.codemem/plugin.log`.
+
+## Troubleshooting and rollback
+
+- No automatic recall on OpenCode 2: recall requires a non-empty latest
+  user-message ID in `session.context`. When the ID is missing or blank, the
+  turn skips recall instead of guessing. Capture and the manual tools still work.
+- Duplicate registration warning: remove either the configured npm entry or the
+  project-local copy so only one Codemem plugin loads.
+- Stop the OpenCode 2 path: set `CODEMEM_PLUGIN_IGNORE=1` in the environment that
+  launches OpenCode 2, or remove the plugin entry from that host's config.
+  OpenCode 1 keeps working from the same package.
+- Return to OpenCode 1: both hosts share one raw-event stream and SQLite
+  database, so switching hosts needs no storage migration.
+
 ## Exports
 
-`CodememPlugin` is the canonical named export and the package default export.
+The package default export is one dual-host object. OpenCode 1 calls its
+`server()` function, while OpenCode 2 calls its `setup()` function. The OpenCode 2
+setup captures conversation, tool, usage, and lifecycle activity and disposes its
+host registrations on unload. It exposes the manual `mem-status`, `mem-recent`,
+and `mem-stats` tools through `tool.transform` with `codemode: false`, keeping
+the hyphenated IDs. OpenCode 2.0.2 automatic recall runs through
+`session.context` when the latest user message has a non-empty ID. Each identified turn performs one fresh retrieval, while
+retries and tool continuations replay retained context. Missing or blank identity
+skips recall safely, and auxiliary hooks remain isolated.
+
+`CodememPlugin` remains the canonical named OpenCode 1 function export.
 `OpencodeMemPlugin` remains available as a deprecated, reference-identical alias
-for compatibility with integrations created before the Codemem rename. No removal
-version is currently scheduled.
+for integrations created before the Codemem rename. No removal version is
+currently scheduled.
 
 ## Documentation
 

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin as OpenCodeV1Plugin } from "@opencode-ai/plugin";
+
+export type CodememV2Setup = (
+	context: unknown,
+) => Promise<(() => Promise<void> | void) | void> | (() => Promise<void> | void) | void;
+
+export type CodememDualPlugin = {
+	readonly id: string;
+	readonly server: OpenCodeV1Plugin;
+	readonly setup: CodememV2Setup;
+};
+
+export declare const CodememPlugin: OpenCodeV1Plugin;
+
+/** @deprecated Use CodememPlugin. */
+export declare const OpencodeMemPlugin: typeof CodememPlugin;
+
+declare const plugin: CodememDualPlugin;
+export default plugin;

package/index.js

@@ -1,5 +1,14 @@
-export {
-	CodememPlugin as default,
+import {
 	CodememPlugin,
 	OpencodeMemPlugin,
 } from "./.opencode/plugins/codemem.js";
+import { setupOpenCodeV2 } from "./.opencode/lib/opencode-v2-adapter.js";
+
+const CodememDualPlugin = {
+	id: "codemem",
+	server: CodememPlugin,
+	setup: setupOpenCodeV2,
+};
+
+export default CodememDualPlugin;
+export { CodememPlugin, OpencodeMemPlugin };

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@codemem/opencode-plugin",
-  "version": "0.44.2",
+  "version": "0.45.0-rc.1",
   "description": "CodeMem plugin for OpenCode",
   "type": "module",
   "main": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./index.js"
     }
   },
   "files": [
     "index.js",
+    "index.d.ts",
+    "src/opencode-v2-contract-fixture.ts",
+    "v2-contract-fixture/",
     "README.md",
     "LICENSE",
     ".opencode/package.json",
@@ -18,10 +23,13 @@
     ".opencode/lib/"
   ],
   "dependencies": {
-    "@opencode-ai/plugin": "1.18.25"
+    "@opencode-ai/plugin": "1.18.29"
   },
   "devDependencies": {
-    "@types/node": "^24.12.4"
+    "@opencode/cli": "2.0.2",
+    "@opencode/plugin": "2.0.2",
+    "@types/node": "^24.12.4",
+    "vitest": "^4.1.11"
   },
   "repository": {
     "type": "git",
@@ -33,7 +41,8 @@
     "url": "https://github.com/kunickiaj/codemem/issues"
   },
   "engines": {
-    "node": ">=24.15.0"
+    "node": ">=24.15.0",
+    "opencode": ">=1.18.29"
   },
   "license": "MIT",
   "publishConfig": {
@@ -49,6 +58,8 @@
     "plugin"
   ],
   "scripts": {
-    "test:packed-artifact": "node ./scripts/packed-artifact-smoke.mjs"
+    "test": "pnpm exec vitest run",
+    "test:opencode-v2-contract": "node ./scripts/packed-v2-host-smoke.mjs",
+    "test:packed-artifact": "pnpm --filter codemem build && node ./scripts/packed-artifact-smoke.mjs"
   }
 }

package/src/opencode-v2-contract-fixture.ts

@@ -0,0 +1,367 @@
+import { appendFile } from "node:fs/promises";
+import { Plugin } from "@opencode/plugin";
+
+const SYSTEM_PART_CONTRACT_TEXT = "codemem-v2-system-part-contract";
+const MESSAGE_PART_CONTRACT_TEXT = "codemem-v2-message-part-contract";
+
+export const OPEN_CODE_V2_CONTRACT_VERSION = "2.0.2";
+export const OPEN_CODE_V2_CONTEXT_MARKER = "codemem-v2-context-hook-applied";
+
+export type ContractRecord = Readonly<Record<string, unknown>>;
+export type ContractReporter = (record: ContractRecord) => Promise<void> | void;
+
+type Disposable = { readonly dispose: () => Promise<void> };
+
+function identity(input: {
+	readonly sessionID: unknown;
+	readonly agent: unknown;
+	readonly model: unknown;
+}) {
+	return JSON.stringify([input.sessionID, input.agent, input.model]);
+}
+
+export function userMessageIDs(messages: readonly unknown[]) {
+	return messages.flatMap((message) => {
+		if (message == null || typeof message !== "object") return [];
+		const candidate = message as Record<string, unknown>;
+		if (candidate.role !== "user" || typeof candidate.id !== "string") return [];
+		return candidate.id.trim().length > 0 ? [candidate.id] : [];
+	});
+}
+
+export function latestUserMessageID(messages: readonly unknown[]) {
+	const latestUser = messages.findLast((message) => {
+		if (message == null || typeof message !== "object") return false;
+		return (message as Record<string, unknown>).role === "user";
+	});
+	if (latestUser == null || typeof latestUser !== "object") return null;
+	const id = (latestUser as Record<string, unknown>).id;
+	return typeof id === "string" && id.trim().length > 0 ? id : null;
+}
+
+export function summarizeEvent(event: unknown): ContractRecord {
+	if (event == null || typeof event !== "object") return { family: "generic", type: "unknown" };
+	const candidate = event as Record<string, unknown>;
+	const type = typeof candidate.type === "string" ? candidate.type : "unknown";
+	const family = ["session", "message", "tool"].find((prefix) => type.startsWith(`${prefix}.`));
+	const summary: ContractRecord = {
+		family: family ?? "generic",
+		type,
+		hasProperties: candidate.properties != null,
+	};
+	const data = candidate.data as Record<string, unknown> | undefined;
+	if (type === "session.inbox.enqueued") {
+		const item = data?.item as Record<string, unknown> | undefined;
+		const payload = item?.payload as Record<string, unknown> | undefined;
+		return {
+			...summary,
+			hasInboxID: typeof data?.inboxID === "string",
+			hasSessionID: typeof data?.sessionID === "string",
+			hasTextPayload: typeof payload?.text === "string",
+			isUserItem: item?.type === "user",
+		};
+	}
+	if (type === "session.step.ended") {
+		return {
+			...summary,
+			finish: typeof data?.finish === "string" ? data.finish : null,
+			hasAssistantMessageID: typeof data?.assistantMessageID === "string",
+			hasFinish: typeof data?.finish === "string",
+			hasSessionID: typeof data?.sessionID === "string",
+			hasTokens: data?.tokens != null && typeof data.tokens === "object",
+		};
+	}
+	if (type.startsWith("session.execution.")) {
+		return { ...summary, hasSessionID: typeof data?.sessionID === "string" };
+	}
+	return summary;
+}
+
+function defaultReporter(record: ContractRecord) {
+	const reportPath = process.env.CODEMEM_OPENCODE_V2_CONTRACT_REPORT;
+	if (!reportPath) return;
+	return appendFile(reportPath, `${JSON.stringify(record)}\n`, "utf8");
+}
+
+async function probeStorage(context: Plugin.Context, report: ContractReporter) {
+	const key = "codemem-contract/probe";
+	const expected = { version: OPEN_CODE_V2_CONTRACT_VERSION };
+	await context.storage.set(key, expected);
+	const value = await context.storage.get(key);
+	await context.storage.remove(key);
+	const removed = await context.storage.get(key);
+	await report({
+		phase: "storage",
+		removed: removed == null,
+		valueMatches: JSON.stringify(value) === JSON.stringify(expected),
+	});
+}
+
+async function consumeEvents(
+	context: Plugin.Context,
+	signal: AbortSignal,
+	report: ContractReporter,
+) {
+	try {
+		for await (const event of context.event.subscribe({ signal })) {
+			await report({ phase: "event", ...summarizeEvent(event) });
+		}
+		await report({ phase: "event.end", aborted: signal.aborted });
+	} catch (error) {
+		if (signal.aborted && error instanceof Error && error.name === "AbortError") {
+			await report({ phase: "event.end", aborted: true });
+			return;
+		}
+		throw error;
+	}
+}
+
+async function registerContextHook(context: Plugin.Context, report: ContractReporter) {
+	const seenSystems = new WeakSet<object>();
+	const seenMessages = new WeakSet<object>();
+	const seenTools = new WeakSet<object>();
+	return context.session.hook("context", async (input) => {
+		const { system, messages, tools } = input;
+		const alreadyMarked = input.options.codememContract === true;
+		const systemAlreadyMarked = system.some(
+			(part) => part.type === "text" && part.text === OPEN_CODE_V2_CONTEXT_MARKER,
+		);
+		const systemReused = seenSystems.has(system);
+		const messagesReused = seenMessages.has(messages);
+		const toolsReused = seenTools.has(tools);
+		seenSystems.add(system);
+		seenMessages.add(messages);
+		seenTools.add(tools);
+		input.system = [
+			...system,
+			{ type: "text", text: OPEN_CODE_V2_CONTEXT_MARKER },
+			{ type: "text", text: SYSTEM_PART_CONTRACT_TEXT },
+		];
+		const latestUserIndex = messages.findLastIndex((message) => message.role === "user");
+		input.messages = messages.map((message, index) => {
+			if (index !== latestUserIndex || message.role !== "user") return { ...message };
+			return {
+				...message,
+				content: [
+					...message.content,
+					{
+						type: "text",
+						text: MESSAGE_PART_CONTRACT_TEXT,
+						metadata: { codememPart: { v: 1, synthetic: true } },
+					},
+				],
+			};
+		});
+		const latestUser = input.messages.findLast((message) => message.role === "user");
+		input.tools = { ...tools };
+		input.options = { ...input.options, codememContract: true };
+		seenSystems.add(input.system);
+		seenMessages.add(input.messages);
+		seenTools.add(input.tools);
+		await report({
+			phase: "context",
+			agent: input.agent,
+			alreadyMarked,
+			hasAgent: Boolean(input.agent),
+			hasModel: Boolean(input.model),
+			hasSessionID: Boolean(input.sessionID),
+			latestUserMessageID: latestUserMessageID(input.messages),
+			messagesMutable: Array.isArray(input.messages),
+			messagesReused,
+			messagePartAccepted:
+				latestUser?.role === "user" &&
+				latestUser.content.some(
+					(part) => part.type === "text" && part.text === MESSAGE_PART_CONTRACT_TEXT,
+				),
+			model: input.model,
+			optionsMutable: typeof input.options === "object",
+			sessionID: input.sessionID,
+			systemMutable: Array.isArray(input.system),
+			systemAlreadyMarked,
+			systemReused,
+			systemPartAccepted: input.system.some(
+				(part) => part.type === "text" && part.text === SYSTEM_PART_CONTRACT_TEXT,
+			),
+			toolsMutable: typeof input.tools === "object",
+			toolsReused,
+			userMessageIDs: userMessageIDs(input.messages),
+		});
+	});
+}
+
+async function registerAuxiliaryHook(
+	context: Plugin.Context,
+	report: ContractReporter,
+	phase: "compaction" | "generate" | "title",
+) {
+	return context.session.hook(phase, async (input) => {
+		const alreadyMarked = input.options.codememContract === true;
+		input.system = [...input.system];
+		input.messages = [...input.messages];
+		input.options = { ...input.options, codememContract: true };
+		await report({
+			phase,
+			alreadyMarked,
+			hasAgent: "agent" in input && Boolean(input.agent),
+			hasModel: Boolean(input.model),
+			hasSessionID: Boolean(input.sessionID),
+			latestUserMessageID: latestUserMessageID(input.messages),
+			messagesMutable: Array.isArray(input.messages),
+			optionsMutable: typeof input.options === "object",
+			sessionID: input.sessionID,
+			systemMutable: Array.isArray(input.system),
+		});
+	});
+}
+
+async function registerSessionHooks(
+	context: Plugin.Context,
+	report: ContractReporter,
+	registrations: Disposable[],
+) {
+	registrations.push(
+		await context.session.hook("prompt", async (input) => {
+			await report({
+				phase: "prompt",
+				hasMessageID: Boolean(input.messageID),
+				hasSessionID: Boolean(input.sessionID),
+				messageID: input.messageID,
+				sessionID: input.sessionID,
+			});
+		}),
+	);
+	registrations.push(await registerContextHook(context, report));
+	registrations.push(await registerAuxiliaryHook(context, report, "compaction"));
+	registrations.push(await registerAuxiliaryHook(context, report, "generate"));
+	registrations.push(await registerAuxiliaryHook(context, report, "title"));
+	registrations.push(
+		await context.session.hook("model.request", async (input) => {
+			input.headers["x-codemem-contract-kind"] = input.kind;
+			await report({ phase: "model.request", kind: input.kind, identity: identity(input) });
+		}),
+	);
+	registrations.push(
+		await context.session.hook("http.request", async (input) => {
+			await report({
+				phase: "http.request",
+				kind: input.kind,
+				kindHeader: input.request.headers.get("x-codemem-contract-kind"),
+			});
+		}),
+	);
+	registrations.push(
+		await context.session.hook("http.response", async (input) => {
+			await report({
+				phase: "http.response",
+				kind: input.kind,
+				kindHeader: input.request.headers.get("x-codemem-contract-kind"),
+			});
+		}),
+	);
+	registrations.push(
+		await context.session.hook("retry", async (input) => {
+			await report({
+				phase: "retry",
+				attempt: input.attempt,
+				retry: input.decision.retry,
+				hasKind: "kind" in input,
+				hasRequestID: "requestID" in input,
+			});
+		}),
+	);
+}
+
+async function registerToolContracts(
+	context: Plugin.Context,
+	report: ContractReporter,
+	registrations: Disposable[],
+) {
+	const after = await context.tool.hook("execute.after", async (input) => {
+		await report({
+			phase: "tool.execute.after",
+			hasAgent: Boolean(input.agent),
+			status: input.status,
+			hasCallID: Boolean(input.id),
+			hasInput: input.input != null,
+			hasMessageID: Boolean(input.messageID),
+			hasSessionID: Boolean(input.sessionID),
+			hasTool: Boolean(input.tool),
+		});
+	});
+	registrations.push(after);
+	let effectiveID: string | null = null;
+	const declaredName = "contract-probe";
+	const transform = await context.tool.transform((editor) => {
+		editor.add({
+			name: declaredName,
+			description: "OpenCode 2 contract-only tool",
+			input: { type: "object", properties: {}, additionalProperties: false },
+			execute: async () => ({ content: "contract-ok" }),
+		});
+		const added = editor.list().find((tool) => tool.name === declaredName);
+		effectiveID = added?.id ?? null;
+	});
+	registrations.push(transform);
+	await report({ phase: "tool.transform", declaredName, effectiveID });
+}
+
+async function disposeAll(registrations: readonly Disposable[]) {
+	let firstError: unknown;
+	for (const registration of [...registrations].reverse()) {
+		try {
+			await registration.dispose();
+		} catch (error) {
+			firstError ??= error;
+		}
+	}
+	if (firstError) throw firstError;
+}
+
+export function defineOpenCodeV2ContractFixture(report: ContractReporter = defaultReporter) {
+	return Plugin.define({
+		id: "codemem-v2-contract",
+		async setup(context) {
+			const abortController = new AbortController();
+			const registrations: Disposable[] = [];
+			try {
+				await report({
+					phase: "setup",
+					appVersion: context.app.version,
+					directory: context.location.directory,
+					projectDirectory: context.location.project.directory,
+					projectCanonical: context.location.project.canonical,
+					hasWorkspaceID: Boolean(context.location.workspaceID),
+					optionKeys: Object.keys(context.options).sort(),
+					hasLog: "log" in context.app,
+					hasToast: "toast" in context || "tui" in context,
+				});
+				await probeStorage(context, report);
+				await registerSessionHooks(context, report, registrations);
+				await registerToolContracts(context, report, registrations);
+				let eventError: unknown;
+				const eventTask = consumeEvents(context, abortController.signal, report).catch((error) => {
+					eventError = error;
+				});
+				return async () => {
+					abortController.abort();
+					let disposalError: unknown;
+					try {
+						await disposeAll(registrations);
+					} catch (error) {
+						disposalError = error;
+					}
+					await eventTask;
+					await report({ phase: "cleanup", disposed: registrations.length });
+					if (disposalError) throw disposalError;
+					if (eventError) throw eventError;
+				};
+			} catch (error) {
+				abortController.abort();
+				await disposeAll(registrations);
+				throw error;
+			}
+		},
+	});
+}
+
+export default defineOpenCodeV2ContractFixture();

package/v2-contract-fixture/index.ts

@@ -0,0 +1 @@
+export { default } from "../src/opencode-v2-contract-fixture.ts";

package/v2-contract-fixture/package.json

@@ -0,0 +1,8 @@
+{
+	"private": true,
+	"type": "module",
+	"main": "./index.ts",
+	"peerDependencies": {
+		"@opencode/plugin": "2.0.2"
+	}
+}

package/.opencode/plugins/runtime.js

@@ -1 +0,0 @@
-export { default } from "./codemem.js";