feat: Add OpenCode TUI health companion

Author: nguyenthdat

README.md

@@ -28,6 +28,17 @@ Add the plugin to `opencode.json` or `opencode.jsonc`:
 }
 ```
 
+The package also includes an OpenCode TUI companion. Enable it in `tui.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@nguyenthdat/opencode-memory@0.6.0-beta.0"]
+}
+```
+
+Use the project `.opencode/tui.json` or the user-level `~/.config/opencode/tui.json` depending on the desired scope. The companion displays `Memory: checking`, `Memory: healthy`, `Memory: degraded`, or `Memory: unavailable` in the TUI bottom bar. Run `/memory-health` to refresh it and show the detailed result as a toast. OpenCode's plugin installer can configure both the server and TUI entrypoints from the same package.
+
 On a supported platform, npm installs one matching optional native package. Reinstall without `--omit=optional`; the plugin intentionally has no postinstall script or runtime binary download.
 
 ### How the daemon is installed
@@ -36,7 +47,7 @@ The plugin does not install a global daemon, `systemd` unit, `launchd` service,
 
 When OpenCode loads the TypeScript plugin, no native process is started yet. On the first memory request, the plugin resolves the executable from the installed native package, validates the private per-user runtime directory and socket, and connects to an existing compatible daemon when one is already running. If no daemon is available, one contender acquires the startup lock and launches the packaged executable in detached `--daemon` mode; concurrent OpenCode processes wait for the same endpoint instead of starting additional daemons.
 
-The daemon is therefore installed and upgraded as part of the npm plugin dependency graph, but started lazily at runtime. It exits automatically after the configured idle interval and is started again on the next memory request. Set `OPENCODE_NATIVE_MEMORY_BIN` only for a development binary override, or `OPENCODE_MEMORY_TRANSPORT=sidecar` for the temporary beta rollback path.
+The daemon is therefore installed and upgraded as part of the npm plugin dependency graph, but started lazily at runtime. It exits automatically after the configured idle interval and is started again on the next memory request. Set `OPENCODE_NATIVE_MEMORY_BIN` only for a development binary override.
 
 Supported packages:
 
@@ -72,7 +83,7 @@ The plugin automatically registers its packaged `rules/native-memory.md` as an O
 | `memory_import`          | Validate and restore a portable JSON snapshot                             |
 | `memory_feedback`        | Record whether recalled memories were useful                              |
 | `memory_optimize`        | Prune expired records and optimize indexes                                |
-| `memory_status`          | Inspect backend, model, and schema status                                 |
+| `memory_status`          | Health-check the plugin and inspect backend, model, and schema status     |
 | `memory_doctor`          | Run shallow or deep integrity checks                                      |
 | `memory_purge`           | Confirm and delete the complete project store                             |
 
@@ -119,7 +130,6 @@ Changing model identity or vector-affecting preprocessing requires rebuilding th
 | `OPENCODE_MEMORY_MODEL_CACHE`                | Replace the complete local Hugging Face model-cache path                     |
 | `OPENCODE_MEMORY_REQUEST_TIMEOUT_MS`         | Native RPC timeout in milliseconds; default 5 minutes, maximum 2 hours       |
 | `OPENCODE_NATIVE_MEMORY_BIN`                 | Development/debug native daemon binary override                              |
-| `OPENCODE_MEMORY_TRANSPORT`                  | `daemon` by default; temporary `sidecar` beta rollback                       |
 | `OPENCODE_MEMORY_PROJECT_IDLE_SECONDS`       | Release an unleased project actor after 5 minutes                            |
 | `OPENCODE_MEMORY_DAEMON_IDLE_SECONDS`        | Stop the daemon after 10 minutes with no sessions or project activity        |
 | `OPENCODE_MEMORY_WARMUP`                     | Enable model/shared-memory warmup; default `true`                            |

bun.lock

@@ -165,6 +165,48 @@ export interface DocumentIndexResponse {
   warnings: string[];
 }
 
+export interface NativeMemoryStatus {
+  ready: boolean;
+  rpc_protocol_version: number;
+  backend: string;
+  zvec_version: string;
+  embedding_model: string;
+  embedding_dimension: number;
+  project_root: string;
+  project_id: string;
+  collection_path: string;
+  document_count: number;
+  indexed_document_count: number;
+  state_schema_version: number;
+  metadata_count: number;
+  tombstone_count: number;
+  retrieval_count: number;
+  pending_upsert_count: number;
+  pending_delete_count: number;
+  indexes: Array<{ name: string; completeness: number }>;
+  capabilities: string[];
+}
+
+export type MemoryPluginHealthStatus = "healthy" | "degraded" | "unavailable";
+
+export interface MemoryPluginHealthIssue {
+  component: "backend" | "shared_sync" | "document_index";
+  message: string;
+}
+
+export interface MemoryPluginHealth {
+  status: MemoryPluginHealthStatus;
+  ready: boolean;
+  checked_at_ms: number;
+  issues: MemoryPluginHealthIssue[];
+}
+
+export type MemoryStatusResponse = Record<string, unknown> &
+  (
+    | (NativeMemoryStatus & { plugin_health: MemoryPluginHealth })
+    | { plugin_health: MemoryPluginHealth }
+  );
+
 export interface SharedMemoryRecord extends CuratedCandidate {
   source: string;
 }
@@ -193,11 +235,3 @@ export interface RpcResponse {
   result?: unknown | undefined;
   error?: string | undefined;
 }
-
-export interface PendingRequest {
-  resolve(value: unknown): void;
-  reject(error: Error): void;
-  timer: ReturnType<typeof setTimeout>;
-  abort?: (() => void) | undefined;
-  signal?: AbortSignal | undefined;
-}

opencode-memory/src/contracts.ts

@@ -32,10 +32,8 @@ describe("shared daemon client", () => {
   });
 
   test("rejects invalid custom request timeouts before opening a transport", () => {
-    expect(() => new NativeMemoryClient(".", ".", undefined, 0)).toThrow("request timeout");
-    expect(() => new NativeMemoryClient(".", ".", undefined, Number.NaN)).toThrow(
-      "request timeout",
-    );
+    expect(() => new NativeMemoryClient(".", ".", 0)).toThrow("request timeout");
+    expect(() => new NativeMemoryClient(".", ".", Number.NaN)).toThrow("request timeout");
   });
 
   test("releases the shared project client only after the final local lease", async () => {

opencode-memory/src/daemon-client.test.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
 import {
   chmod,
   lstat,
@@ -10,6 +11,7 @@ import {
   unlink,
   type FileHandle,
 } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createConnection, type Socket } from "node:net";
@@ -36,11 +38,6 @@ import type {
   OpenSessionResponse,
 } from "./generated/opencode/memory/daemon/v1/daemon_pb.js";
 import type { Response as MemoryResponse } from "./generated/opencode/memory/v1/memory_pb.js";
-import {
-  NativeMemoryClient as LegacySidecarClient,
-  resolveNativeMemoryBinary,
-} from "./sidecar-client.js";
-import type { SpawnFn } from "./sidecar-client.js";
 import {
   createMemoryRequest,
   decodeMemoryResponse,
@@ -59,6 +56,12 @@ const START_LOCK_STALE_MS = 30_000;
 const START_LOCK_TIMEOUT_MS = START_LOCK_STALE_MS + STARTUP_TIMEOUT_MS;
 const DAEMON_PROTOCOL_GENERATION = 1;
 const DOMAIN_SCHEMA_GENERATION = 1;
+const require = createRequire(import.meta.url);
+const NATIVE_PACKAGES: Partial<Record<string, string>> = {
+  "darwin-arm64": "@nguyenthdat/opencode-memory-darwin-arm64",
+  "linux-arm64": "@nguyenthdat/opencode-memory-linux-arm64-gnu",
+  "linux-x64": "@nguyenthdat/opencode-memory-linux-x64-gnu",
+};
 
 export const MAX_REQUEST_BYTES = 32 * MiB;
 export const MAX_RESPONSE_BYTES = 32 * MiB;
@@ -71,10 +74,6 @@ export interface NativeMemoryRequester {
   request<T>(method: MemoryMethod, params?: unknown, signal?: AbortSignal): Promise<T>;
 }
 
-interface MemoryClientDelegate extends NativeMemoryRequester {
-  dispose(): Promise<void>;
-}
-
 interface PendingDaemonRequest {
   resolve(response: DaemonResponse): void;
   reject(error: Error): void;
@@ -145,7 +144,7 @@ class NativeMemoryOperationError extends Error {
   readonly name = "NativeMemoryOperationError";
 }
 
-class DaemonProjectClient implements MemoryClientDelegate {
+class DaemonProjectClient implements NativeMemoryRequester {
   private socket: Socket | undefined;
   private generation = 0;
   private ready: ReadyProject | undefined;
@@ -661,41 +660,23 @@ function createDaemonRequest(body: DaemonRequestMessage["body"], requestId = ran
   });
 }
 
-export class NativeMemoryClient implements MemoryClientDelegate {
-  private readonly daemon: DaemonProjectClient | undefined;
-  private readonly delegate: MemoryClientDelegate;
+export class NativeMemoryClient {
+  private readonly daemon: DaemonProjectClient;
 
-  constructor(
-    root: string,
-    worktree: string,
-    spawnOverride?: SpawnFn,
-    requestTimeoutMs = REQUEST_TIMEOUT_MS,
-  ) {
+  constructor(root: string, worktree: string, requestTimeoutMs = REQUEST_TIMEOUT_MS) {
     validateRequestTimeout(requestTimeoutMs);
-    const transport = process.env.OPENCODE_MEMORY_TRANSPORT ?? "daemon";
-    if (transport !== "daemon" && transport !== "sidecar") {
-      throw new Error(
-        `Invalid OPENCODE_MEMORY_TRANSPORT: expected daemon or sidecar, received ${transport}`,
-      );
-    }
-    if (spawnOverride || transport === "sidecar") {
-      this.delegate = new LegacySidecarClient(root, worktree, spawnOverride, requestTimeoutMs);
-      return;
-    }
     this.daemon = new DaemonProjectClient(root, worktree, requestTimeoutMs);
-    this.delegate = this.daemon;
   }
 
   request<T>(method: MemoryMethod, params: unknown = {}, signal?: AbortSignal): Promise<T> {
-    return this.delegate.request<T>(method, params, signal);
+    return this.daemon.request<T>(method, params, signal);
   }
 
   dispose(): Promise<void> {
-    return this.delegate.dispose();
+    return this.daemon.dispose();
   }
 
   async daemonInfo(): Promise<DaemonClientInfo> {
-    if (!this.daemon) throw new Error("Native memory client is using the legacy sidecar transport");
     return await this.daemon.info();
   }
 }
@@ -793,6 +774,51 @@ export function resolveDaemonEndpoint(): string {
     : join("/tmp", `opencode-memory-${uid}`, "daemon.sock");
 }
 
+export function resolveNativeMemoryBinary(root: string): string {
+  const platform = `${process.platform}-${process.arch}`;
+  const packageName = NATIVE_PACKAGES[platform];
+  if (!packageName) {
+    throw new Error(
+      `Native memory supports only macOS arm64 and glibc Linux arm64/x64, not ${platform}`,
+    );
+  }
+  const override = process.env.OPENCODE_NATIVE_MEMORY_BIN;
+  const binaryName = "opencode-memory";
+  const packaged = resolvePackagedBinary(packageName, binaryName);
+  const candidates = override
+    ? [resolve(override)]
+    : [
+        resolve(root, "target", "release", binaryName),
+        resolve(root, "target", "debug", binaryName),
+        ...(packaged ? [packaged] : []),
+      ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    const binary = realpathSync(candidate);
+    if (!override) {
+      const library = resolve(
+        binary,
+        "..",
+        "memory-libs",
+        process.platform === "darwin" ? "libzvec_c_api.dylib" : "libzvec_c_api.so",
+      );
+      if (!existsSync(library)) continue;
+    }
+    return binary;
+  }
+  throw new Error(
+    `Native memory binary was not found. Reinstall with optional dependencies or run \`bun run build:native:release\`. Checked: ${candidates.join(", ")}`,
+  );
+}
+
+function resolvePackagedBinary(packageName: string, binaryName: string): string | undefined {
+  try {
+    return require.resolve(`${packageName}/bin/${binaryName}`);
+  } catch {
+    return undefined;
+  }
+}
+
 async function bootstrapDaemon(root: string, endpoint: string): Promise<void> {
   const runtimeDirectory = dirname(endpoint);
   await ensurePrivateRuntimeDirectory(runtimeDirectory);
@@ -1127,6 +1153,3 @@ function asError(error: unknown): Error {
 function delay(milliseconds: number): Promise<void> {
   return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
 }
-
-export { resolveNativeMemoryBinary };
-export type { SpawnFn };

opencode-memory/src/daemon-client.ts

@@ -34,6 +34,11 @@ export type {
   CuratedCandidate,
   SharedMemoryRecord,
   SharedSyncResponse,
+  NativeMemoryStatus,
+  MemoryPluginHealthStatus,
+  MemoryPluginHealthIssue,
+  MemoryPluginHealth,
+  MemoryStatusResponse,
 } from "./contracts.js";
 
 // Shared daemon client
@@ -55,7 +60,6 @@ export type {
   DaemonControlInfo,
   NativeMemoryClientLease,
   NativeMemoryRequester,
-  SpawnFn,
 } from "./daemon-client.js";
 
 export {