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

package/.opencode/lib/opencode-v2-adapter.js

@@ -4,6 +4,7 @@ import {
   createRuntimeLocation,
 } from "./host-contract.js";
 import { createCodememRuntime } from "./runtime.js";
+import { registerV2NotificationBridge } from "./v2-notification-bridge.js";
 
 const DEFAULT_EVENT_TASK_TIMEOUT_MS = 250;
 const FAILED_TOOL_ERROR = Object.freeze({
@@ -419,6 +420,11 @@ const waitForRuntimeDisposal = (runtime, waitForTask, timeoutMs) =>
     timeoutMs,
   );
 
+const disposeNotificationRegistration = async (registration, waitForTask, timeoutMs) => {
+  if (!registration) return;
+  await waitForRegistrationDisposal([registration], waitForTask, timeoutMs);
+};
+
 const reportDiagnosticSafely = async (runtime, code) => {
   try {
     await runtime.reportDiagnostic?.(code);
@@ -619,19 +625,36 @@ export const createOpenCodeV2Adapter = ({
   waitForRuntimeDisposalTask = defaultWaitForEventTask,
 } = {}) => async (context) => {
   const location = context.location;
-  // OpenCode 2.0.2 exposes neither app logging nor toast APIs, so V2 uses local diagnostics only.
-  const runtime = await createRuntime({
-    location: createRuntimeLocation({
-      project: { ...location.project, root: location.project.canonical },
-      directory: location.directory,
-      worktree: location.project.directory,
-    }),
-    host: createRuntimeHost({ log: async () => {}, notify: null }),
-  });
-  if (!runtime) return undefined;
+  const notificationBridge = await registerV2NotificationBridge(context);
+  let runtime;
+  try {
+    runtime = await createRuntime({
+      location: createRuntimeLocation({
+        project: { ...location.project, root: location.project.canonical },
+        directory: location.directory,
+        worktree: location.project.directory,
+      }),
+      host: createRuntimeHost({ log: async () => {}, notify: notificationBridge.notify }),
+    });
+  } catch (error) {
+    await disposeNotificationRegistration(
+      notificationBridge.registration,
+      waitForRegistrationTask,
+      eventTaskTimeoutMs,
+    );
+    throw error;
+  }
+  if (!runtime) {
+    await disposeNotificationRegistration(
+      notificationBridge.registration,
+      waitForRegistrationTask,
+      eventTaskTimeoutMs,
+    );
+    return undefined;
+  }
 
   const abortController = new AbortController();
-  const registrations = [];
+  const registrations = notificationBridge.registration ? [notificationBridge.registration] : [];
   const translator = createV2EventTranslator();
   const scheduleCapture = createCaptureScheduler();
   const scheduleContext = createContextScheduler();

package/.opencode/lib/runtime.js

@@ -24,7 +24,7 @@ import { V2_ADAPTER_DIAGNOSTICS } from "./host-contract.js";
 
 const TRUTHY_VALUES = ["1", "true", "yes"];
 const DISABLED_VALUES = ["0", "false", "off"];
-const PINNED_BACKEND_VERSION = "0.45.0-rc.1";
+const PINNED_BACKEND_VERSION = "0.45.0-rc.2";
 const COMPAT_CHECK_DELAY_MS = 1500;
 const COMPAT_CHECK_CACHE_TTL_MS = 5 * 60 * 1000;
 const MAX_UPDATE_STATUS_BYTES = 16 * 1024;

package/.opencode/lib/v2-notification-bridge.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { CodememNotifications } from "../../rpc.js";
+
+const DEFAULT_MAX_NOTICES = 32;
+const DEFAULT_REGISTRATION_TIMEOUT_MS = 250;
+
+const resolvePositiveInteger = (value, fallback) =>
+  Number.isSafeInteger(value) && value > 0 ? value : fallback;
+
+const disposeLateRegistration = (registrationTask) => {
+  void registrationTask
+    .then((registration) => registration.dispose())
+    .catch(() => {
+      // Timed-out advisory registration cleanup is best-effort.
+    });
+};
+
+const registerWithinTimeout = async (context, handlers, timeoutMs) => {
+  const registrationTask = Promise.resolve().then(() =>
+    context.rpc.register(CodememNotifications, handlers)
+  );
+  let timeout;
+  const timeoutTask = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve({ status: "timeout" }), timeoutMs);
+    timeout.unref?.();
+  });
+  const result = await Promise.race([
+    registrationTask.then(
+      (registration) => ({ status: "registered", registration }),
+      () => ({ status: "failed" })
+    ),
+    timeoutTask,
+  ]);
+  clearTimeout(timeout);
+  if (result.status === "timeout") disposeLateRegistration(registrationTask);
+  return result.status === "registered" ? result.registration : null;
+};
+
+export const createNotificationBacklog = ({
+  maxNotices = DEFAULT_MAX_NOTICES,
+  createID = randomUUID,
+} = {}) => {
+  const notices = [];
+  const limit = Number.isSafeInteger(maxNotices) && maxNotices > 0 ? maxNotices : DEFAULT_MAX_NOTICES;
+  let buffering = true;
+
+  return {
+    push({ message, variant }) {
+      const notice = { id: createID(), message, variant };
+      if (!buffering) return notice;
+      notices.push(notice);
+      while (notices.length > limit) notices.shift();
+      return notice;
+    },
+    drain() {
+      buffering = false;
+      return notices.splice(0, notices.length);
+    },
+  };
+};
+
+export const registerV2NotificationBridge = async (context, options = {}) => {
+  if (typeof context?.rpc?.register !== "function") {
+    return { notify: null, registration: null };
+  }
+
+  const backlog = createNotificationBacklog(options);
+  const registrationTimeoutMs = resolvePositiveInteger(
+    options.registrationTimeoutMs,
+    DEFAULT_REGISTRATION_TIMEOUT_MS
+  );
+  const registration = await registerWithinTimeout(
+    context,
+    { drain: async () => ({ notices: backlog.drain() }) },
+    registrationTimeoutMs
+  );
+  if (!registration) {
+    return { notify: null, registration: null };
+  }
+
+  let active = true;
+  return {
+    notify: async (input) => {
+      if (!active) return;
+      const notice = backlog.push(input);
+      try {
+        void Promise.resolve(registration.events.emit("notice", notice)).catch(() => {
+          // Replay remains available when live publication fails.
+        });
+      } catch {
+        // Replay remains available when live publication throws synchronously.
+      }
+    },
+    registration: {
+      async dispose() {
+        active = false;
+        try {
+          await registration.dispose();
+        } catch {
+          // Notification cleanup must not fail the server plugin lifecycle.
+        }
+      },
+    },
+  };
+};

package/README.md

@@ -32,6 +32,10 @@ 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`.
 
+OpenCode 2 automatically loads the package's `./tui` companion. It displays
+best-effort injection, compatibility, persistence, and update notices from the
+server plugin without making notification delivery part of capture or recall.
+
 ## Troubleshooting and rollback
 
 - No automatic recall on OpenCode 2: recall requires a non-empty latest
@@ -39,6 +43,8 @@ registration wins and later copies skip their hooks with a warning in
   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.
+- No notifications on OpenCode 2: restart the TUI after installing or upgrading
+  the plugin so it loads the matching `./tui` companion.
 - 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.
@@ -57,6 +63,10 @@ the hyphenated IDs. OpenCode 2.0.2 automatic recall runs through
 retries and tool continuations replay retained context. Missing or blank identity
 skips recall safely, and auxiliary hooks remain isolated.
 
+The `./rpc` export defines the location-scoped notification contract. The
+`./tui` export subscribes before draining the bounded startup backlog, suppresses
+duplicate notice IDs, and renders matching-location notices as Codemem toasts.
+
 `CodememPlugin` remains the canonical named OpenCode 1 function export.
 `OpencodeMemPlugin` remains available as a deprecated, reference-identical alias
 for integrations created before the Codemem rename. No removal version is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemem/opencode-plugin",
-  "version": "0.45.0-rc.1",
+  "version": "0.45.0-rc.2",
   "description": "CodeMem plugin for OpenCode",
   "type": "module",
   "main": "./index.js",
@@ -9,11 +9,23 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./rpc": {
+      "types": "./rpc.d.ts",
+      "import": "./rpc.js"
+    },
+    "./tui": {
+      "types": "./tui.d.ts",
+      "import": "./tui.js"
     }
   },
   "files": [
     "index.js",
     "index.d.ts",
+    "rpc.js",
+    "rpc.d.ts",
+    "tui.js",
+    "tui.d.ts",
     "src/opencode-v2-contract-fixture.ts",
     "v2-contract-fixture/",
     "README.md",
@@ -23,11 +35,11 @@
     ".opencode/lib/"
   ],
   "dependencies": {
-    "@opencode-ai/plugin": "1.18.29"
+    "@opencode-ai/plugin": "1.18.29",
+    "@opencode/plugin": "2.0.2"
   },
   "devDependencies": {
     "@opencode/cli": "2.0.2",
-    "@opencode/plugin": "2.0.2",
     "@types/node": "^24.12.4",
     "vitest": "^4.1.11"
   },

package/rpc.d.ts

@@ -0,0 +1,12 @@
+import type { Rpc } from "@opencode/plugin/rpc";
+
+export type CodememNotificationVariant = "info" | "success" | "warning" | "error";
+
+export interface CodememNotification {
+	readonly id: string;
+	readonly message: string;
+	readonly variant: CodememNotificationVariant;
+}
+
+export declare const CODEMEM_NOTIFICATION_RPC_ID: "codemem.notifications";
+export declare const CodememNotifications: Rpc.PortableDefinition;

package/rpc.js

@@ -0,0 +1,32 @@
+export const CODEMEM_NOTIFICATION_RPC_ID = "codemem.notifications";
+
+const noticeSchema = {
+	type: "object",
+	properties: {
+		id: { type: "string" },
+		message: { type: "string" },
+		variant: { enum: ["info", "success", "warning", "error"] },
+	},
+	required: ["id", "message", "variant"],
+	additionalProperties: false,
+};
+
+export const CodememNotifications = {
+	id: CODEMEM_NOTIFICATION_RPC_ID,
+	methods: {
+		drain: {
+			input: { type: "object", additionalProperties: false },
+			output: {
+				type: "object",
+				properties: {
+					notices: { type: "array", items: noticeSchema },
+				},
+				required: ["notices"],
+				additionalProperties: false,
+			},
+		},
+	},
+	events: {
+		notice: { schema: noticeSchema },
+	},
+};

package/tui.d.ts

@@ -0,0 +1,16 @@
+export type CodememTuiSetup = (
+	context: unknown,
+) => Promise<(() => Promise<void> | void) | void> | (() => Promise<void> | void) | void;
+
+export interface CodememTuiPlugin {
+	readonly id: string;
+	readonly setup: CodememTuiSetup;
+}
+
+export declare function createCodememTuiPlugin(options?: {
+	readonly maxSeenNotices?: number;
+	readonly replayTimeoutMs?: number;
+}): CodememTuiPlugin;
+
+declare const plugin: CodememTuiPlugin;
+export default plugin;

package/tui.js

@@ -0,0 +1,105 @@
+import { CodememNotifications } from "./rpc.js";
+
+const DEFAULT_MAX_SEEN_NOTICES = 64;
+const DEFAULT_REPLAY_TIMEOUT_MS = 250;
+const TOAST_VARIANTS = new Set(["info", "success", "warning", "error"]);
+
+const sameLocation = (left, right) =>
+	left?.directory === right?.directory &&
+	(left?.workspaceID ?? null) === (right?.workspaceID ?? null);
+
+const normalizeNotice = (value) => {
+	if (!value || typeof value !== "object") return null;
+	const id = typeof value.id === "string" ? value.id : "";
+	const message = typeof value.message === "string" ? value.message : "";
+	const variant = TOAST_VARIANTS.has(value.variant) ? value.variant : "warning";
+	if (!id || !message) return null;
+	return { id, message, variant };
+};
+
+export const createCodememTuiPlugin = ({
+	maxSeenNotices = DEFAULT_MAX_SEEN_NOTICES,
+	replayTimeoutMs = DEFAULT_REPLAY_TIMEOUT_MS,
+} = {}) =>
+	({
+		id: "codemem.tui",
+		async setup(context) {
+			const seen = new Set();
+			let active = true;
+			const seenLimit =
+				Number.isSafeInteger(maxSeenNotices) && maxSeenNotices > 0
+					? maxSeenNotices
+					: DEFAULT_MAX_SEEN_NOTICES;
+			const location = context.location ?? context.data?.location?.default?.();
+			const show = (input) => {
+				if (!active) return;
+				const notice = normalizeNotice(input);
+				if (!notice || seen.has(notice.id)) return;
+				seen.add(notice.id);
+				while (seen.size > seenLimit) seen.delete(seen.values().next().value);
+				try {
+					context.ui.toast.show({
+						title: "Codemem",
+						message: notice.message,
+						variant: notice.variant,
+					});
+				} catch {
+					// Notifications must not affect the TUI plugin lifecycle.
+				}
+			};
+
+			let notifications;
+			try {
+				notifications = context.client.rpc(CodememNotifications);
+			} catch {
+				return undefined;
+			}
+
+			let unsubscribe = () => {};
+			try {
+				unsubscribe = notifications.events.on("notice", (event) => {
+					if (location && !sameLocation(event.location, location)) return;
+					show(event.data);
+				});
+			} catch {
+				// Replay can still deliver notices when live subscription is unavailable.
+			}
+
+			const replayAbort = new AbortController();
+			const replayLimit =
+				Number.isSafeInteger(replayTimeoutMs) && replayTimeoutMs > 0
+					? replayTimeoutMs
+					: DEFAULT_REPLAY_TIMEOUT_MS;
+			let replayTimer;
+			const replayTimeout = new Promise((resolve) => {
+				replayTimer = setTimeout(() => {
+					replayAbort.abort();
+					resolve(null);
+				}, replayLimit);
+				replayTimer.unref?.();
+			});
+			const replayTask = Promise.resolve()
+				.then(() =>
+					notifications.drain({}, {
+						...(location ? { location } : {}),
+						signal: replayAbort.signal,
+					}),
+				)
+				.catch(() => null);
+			const replay = await Promise.race([replayTask, replayTimeout]);
+			clearTimeout(replayTimer);
+			for (const notice of Array.isArray(replay?.notices) ? replay.notices : []) show(notice);
+
+			return () => {
+				active = false;
+				replayAbort.abort();
+				try {
+					unsubscribe();
+				} catch {
+					// Best-effort cleanup only.
+				}
+			};
+		},
+	});
+
+export default createCodememTuiPlugin();