@omnixal/openclaw-nats-plugin 0.1.0

package/PLUGIN.md

@@ -0,0 +1,94 @@
+# NATS JetStream Plugin
+
+Event-driven plugin for OpenClaw that replaces polling-based heartbeat with NATS JetStream messaging.
+
+## Quick Start
+
+    # Install plugin
+    openclaw plugins install @omnixal/openclaw-nats-plugin
+
+    # Setup infrastructure (auto-detects Bun or Docker)
+    npx @omnixal/openclaw-nats-plugin setup
+
+    # Restart gateway
+    openclaw gateway restart
+
+## Setup Options
+
+    # Force Bun mode (downloads nats-server binary, creates systemd/launchd units)
+    npx @omnixal/openclaw-nats-plugin setup --runtime=bun
+
+    # Force Docker mode (creates docker-compose with nats + sidecar containers)
+    npx @omnixal/openclaw-nats-plugin setup --runtime=docker
+
+Auto-detect priority: Bun > Docker.
+
+## Management
+
+    npx @omnixal/openclaw-nats-plugin start      # Start services
+    npx @omnixal/openclaw-nats-plugin stop       # Stop services
+    npx @omnixal/openclaw-nats-plugin status     # Health check
+    npx @omnixal/openclaw-nats-plugin uninstall  # Remove (keeps data)
+    npx @omnixal/openclaw-nats-plugin uninstall --purge  # Remove everything
+
+## Architecture
+
+Plugin hooks make lightweight HTTP calls to a NATS sidecar service for event publishing.
+
+### Hooks
+- **gateway-startup** — Publishes gateway startup event, verifies sidecar connectivity
+- **lifecycle-publisher** — Publishes tool_result_persist events (tool completed/failed)
+- **command-publisher** — Publishes command events (/new, /reset, /stop)
+
+### Plugins
+- **nats-context-engine** — Publishes agent lifecycle events via plugin SDK:
+  - Subagent spawned/ended
+  - Session started/ended
+  - Agent run ended
+  - Message sent (delivery status)
+  - Context compacted (after history summarization)
+
+### Published Events
+
+| Subject | Trigger |
+|---|---|
+| `agent.events.gateway.startup` | Gateway starts |
+| `agent.events.session.new` | `/new` command |
+| `agent.events.session.reset` | `/reset` command |
+| `agent.events.session.stop` | `/stop` command |
+| `agent.events.session.started` | Session begins |
+| `agent.events.session.ended` | Session ends |
+| `agent.events.tool.{name}.completed` | Tool succeeds |
+| `agent.events.tool.{name}.failed` | Tool fails |
+| `agent.events.subagent.spawned` | Subagent created |
+| `agent.events.subagent.ended` | Subagent finished |
+| `agent.events.agent.run_ended` | Agent run completes |
+| `agent.events.message.sent` | Message delivered |
+| `agent.events.context.compacted` | Context history compressed |
+
+## Dashboard
+
+The plugin includes a web dashboard at `/nats-dashboard` on the Gateway.
+
+It shows:
+- **Health status** — NATS server, Gateway WebSocket, and sidecar connectivity
+- **Pending events** — queued inbound events with priority and age
+- **Configuration** — streams, consumer name, dedup TTL
+
+The dashboard auto-refreshes every 5 seconds. API calls are proxied through the Gateway (no direct sidecar access needed from the browser).
+
+Build the dashboard (required after install):
+
+    cd openclaw-nats-plugin/dashboard && bun run build
+
+## Configuration
+
+Environment variables (auto-configured by setup):
+- `NATS_SIDECAR_URL` — Sidecar URL (default: `http://127.0.0.1:3104`)
+- `NATS_PLUGIN_API_KEY` — API key for sidecar auth (auto-generated)
+- `NATS_SERVERS` — NATS server URL (default: `nats://127.0.0.1:4222`)
+
+## Requirements
+
+- OpenClaw Gateway v2026.3+
+- Bun (recommended) or Docker

package/bin/cli.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+import { parseArgs } from 'node:util';
+
+const COMMANDS = ['setup', 'start', 'stop', 'status', 'uninstall'] as const;
+type Command = typeof COMMANDS[number];
+
+function printUsage(): void {
+  console.log(`
+Usage: npx @omnixal/openclaw-nats-plugin <command> [options]
+
+Commands:
+  setup       Install and start NATS + sidecar (auto-detects runtime)
+  start       Start NATS + sidecar services
+  stop        Stop NATS + sidecar services
+  status      Check service health
+  uninstall   Remove services and config
+
+Options:
+  --runtime=bun|docker   Force specific runtime (default: auto-detect)
+  --help                 Show this help
+`);
+}
+
+const args = process.argv.slice(2);
+const command = args[0] as Command;
+
+if (!command || command === '--help' || !COMMANDS.includes(command)) {
+  printUsage();
+  process.exit(command === '--help' ? 0 : 1);
+}
+
+const { values } = parseArgs({
+  args: args.slice(1),
+  options: {
+    runtime: { type: 'string' },
+    purge: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+  strict: false,
+});
+
+if (values.help) {
+  printUsage();
+  process.exit(0);
+}
+
+const runtime = values.runtime as 'bun' | 'docker' | undefined;
+
+switch (command) {
+  case 'setup': {
+    const { runSetup } = await import('../cli/setup.ts');
+    await runSetup(runtime);
+    break;
+  }
+  case 'start': {
+    const { runStart } = await import('../cli/lifecycle.ts');
+    await runStart();
+    break;
+  }
+  case 'stop': {
+    const { runStop } = await import('../cli/lifecycle.ts');
+    await runStop();
+    break;
+  }
+  case 'status': {
+    const { runStatus } = await import('../cli/lifecycle.ts');
+    await runStatus();
+    break;
+  }
+  case 'uninstall': {
+    const { runUninstall } = await import('../cli/lifecycle.ts');
+    await runUninstall(values.purge as boolean);
+    break;
+  }
+}

package/cli/bun-setup.ts

@@ -0,0 +1,133 @@
+import { mkdirSync, existsSync, cpSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import {
+  PLUGIN_DIR, SIDECAR_DIR, DATA_DIR, JETSTREAM_DIR, BIN_DIR,
+  NATS_SERVER_BIN, STATE_FILE, NATS_CONF, type PluginState,
+} from './paths';
+import { downloadNatsServer, NATS_VERSION } from './download-nats';
+import { writeNatsConfig } from './nats-config';
+import { generateApiKey, writeEnvVariables } from './env-writer';
+import {
+  getServiceManager, generateSystemdUnit, generateLaunchdPlist,
+  installSystemdUnit, installLaunchdPlist, startService,
+} from './service-units';
+
+const NATS_SERVICE = 'openclaw-nats';
+const SIDECAR_SERVICE = 'openclaw-nats-sidecar';
+
+export async function bunSetup(): Promise<void> {
+  console.log('Setting up NATS plugin (Bun mode)...\n');
+
+  // 1. Create directories
+  for (const dir of [PLUGIN_DIR, BIN_DIR, SIDECAR_DIR, DATA_DIR, JETSTREAM_DIR]) {
+    mkdirSync(dir, { recursive: true });
+  }
+  mkdirSync(join(PLUGIN_DIR, 'logs'), { recursive: true });
+
+  // 2. Download nats-server
+  await downloadNatsServer();
+
+  // 3. Copy sidecar source into plugin dir
+  // When installed via npm, the sidecar/ dir is inside the package
+  const pluginRoot = join(dirname(new URL(import.meta.url).pathname), '..');
+  const sidecarSrc = join(pluginRoot, 'sidecar');
+  if (existsSync(sidecarSrc)) {
+    console.log('Copying sidecar source...');
+    cpSync(sidecarSrc, SIDECAR_DIR, { recursive: true });
+  } else {
+    throw new Error(`Sidecar source not found at ${sidecarSrc}`);
+  }
+
+  // 4. Install sidecar dependencies
+  console.log('Installing sidecar dependencies...');
+  execFileSync('bun', ['install', '--frozen-lockfile'], { cwd: SIDECAR_DIR, stdio: 'inherit' });
+
+  // 5. Generate NATS config
+  writeNatsConfig();
+
+  // 6. Generate API key
+  const apiKey = generateApiKey();
+
+  // 7. Write env variables
+  writeEnvVariables({
+    NATS_SIDECAR_URL: 'http://127.0.0.1:3104',
+    NATS_PLUGIN_API_KEY: apiKey,
+    NATS_SERVERS: 'nats://127.0.0.1:4222',
+  });
+
+  // 8. Generate and install service units
+  const manager = getServiceManager();
+
+  if (manager === 'systemd') {
+    const natsUnit = generateSystemdUnit({
+      name: NATS_SERVICE,
+      description: 'NATS Server for OpenClaw',
+      execStart: NATS_SERVER_BIN,
+      args: ['-c', NATS_CONF],
+      workingDirectory: PLUGIN_DIR,
+    });
+    installSystemdUnit(NATS_SERVICE, natsUnit);
+
+    const sidecarUnit = generateSystemdUnit({
+      name: SIDECAR_SERVICE,
+      description: 'NATS Sidecar for OpenClaw',
+      execStart: 'bun',
+      args: ['run', join(SIDECAR_DIR, 'src/index.ts')],
+      workingDirectory: SIDECAR_DIR,
+      after: `${NATS_SERVICE}.service`,
+    });
+    installSystemdUnit(SIDECAR_SERVICE, sidecarUnit);
+  } else {
+    const natsPlist = generateLaunchdPlist({
+      label: 'com.openclaw.nats',
+      program: NATS_SERVER_BIN,
+      programArguments: ['-c', NATS_CONF],
+      workingDirectory: PLUGIN_DIR,
+    });
+    installLaunchdPlist('com.openclaw.nats', natsPlist);
+
+    const sidecarPlist = generateLaunchdPlist({
+      label: 'com.openclaw.nats-sidecar',
+      program: 'bun',
+      programArguments: ['run', join(SIDECAR_DIR, 'src/index.ts')],
+      workingDirectory: SIDECAR_DIR,
+    });
+    installLaunchdPlist('com.openclaw.nats-sidecar', sidecarPlist);
+  }
+
+  // 9. Start services
+  console.log('\nStarting services...');
+  startService(NATS_SERVICE);
+  await waitForPort(8222, 10_000);
+  startService(SIDECAR_SERVICE);
+
+  // 10. Save state
+  const state: PluginState = {
+    runtime: 'bun',
+    installedAt: new Date().toISOString(),
+    natsServerVersion: NATS_VERSION,
+  };
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+
+  console.log('\nNATS plugin setup complete (Bun mode)');
+  console.log('  NATS server:  127.0.0.1:4222');
+  console.log('  Sidecar:      127.0.0.1:3104');
+  console.log('\nRestart OpenClaw gateway to activate the plugin.');
+}
+
+async function waitForPort(port: number, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/`, {
+        signal: AbortSignal.timeout(1000),
+      });
+      if (res.ok || res.status === 404) return;
+    } catch {
+      // Not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  console.warn(`Warning: port ${port} not ready after ${timeoutMs}ms`);
+}

package/cli/detect-runtime.ts

@@ -0,0 +1,40 @@
+import { execFileSync } from 'node:child_process';
+
+export function checkBun(): boolean {
+  try {
+    execFileSync('bun', ['--version'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function checkDocker(): boolean {
+  try {
+    execFileSync('docker', ['info'], { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type Runtime = 'bun' | 'docker';
+
+export async function detectRuntime(preferred?: Runtime): Promise<Runtime> {
+  if (preferred) {
+    const check = preferred === 'bun' ? checkBun() : checkDocker();
+    if (!check) {
+      throw new Error(`Requested runtime "${preferred}" is not available`);
+    }
+    return preferred;
+  }
+
+  if (checkBun()) return 'bun';
+  if (checkDocker()) return 'docker';
+
+  throw new Error(
+    'Neither Bun nor Docker found. Install one of:\n' +
+    '  - Bun: https://bun.sh\n' +
+    '  - Docker: https://docs.docker.com/get-docker/'
+  );
+}

package/cli/docker-setup.ts

@@ -0,0 +1,54 @@
+import { mkdirSync, cpSync, writeFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { PLUGIN_DIR, DOCKER_DIR, STATE_FILE, type PluginState } from './paths';
+import { generateApiKey, writeEnvVariables } from './env-writer';
+
+export async function dockerSetup(): Promise<void> {
+  console.log('Setting up NATS plugin (Docker mode)...\n');
+
+  mkdirSync(DOCKER_DIR, { recursive: true });
+
+  // 1. Copy docker compose and sidecar source
+  const pluginRoot = join(dirname(new URL(import.meta.url).pathname), '..');
+  const templateDir = join(pluginRoot, 'docker');
+  const sidecarSrc = join(pluginRoot, 'sidecar');
+
+  if (!existsSync(join(templateDir, 'docker-compose.yml'))) {
+    throw new Error(`Docker compose template not found at ${templateDir}`);
+  }
+
+  if (!existsSync(sidecarSrc)) {
+    throw new Error(`Sidecar source not found at ${sidecarSrc}. The plugin package may be incomplete.`);
+  }
+
+  cpSync(templateDir, DOCKER_DIR, { recursive: true });
+  cpSync(sidecarSrc, join(DOCKER_DIR, 'sidecar'), { recursive: true });
+
+  // 2. Generate API key and write .env for compose
+  const apiKey = generateApiKey();
+  writeFileSync(join(DOCKER_DIR, '.env'), `NATS_PLUGIN_API_KEY=${apiKey}\n`);
+
+  // 3. Build and start
+  console.log('Building and starting containers...');
+  execFileSync('docker', ['compose', 'up', '-d', '--build'], { cwd: DOCKER_DIR, stdio: 'inherit' });
+
+  // 4. Write env variables for OpenClaw
+  writeEnvVariables({
+    NATS_SIDECAR_URL: 'http://127.0.0.1:3104',
+    NATS_PLUGIN_API_KEY: apiKey,
+    NATS_SERVERS: 'nats://127.0.0.1:4222',
+  });
+
+  // 5. Save state
+  const state: PluginState = {
+    runtime: 'docker',
+    installedAt: new Date().toISOString(),
+  };
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+
+  console.log('\nNATS plugin setup complete (Docker mode)');
+  console.log('  NATS server:  127.0.0.1:4222');
+  console.log('  Sidecar:      127.0.0.1:3104');
+  console.log('\nRestart OpenClaw gateway to activate the plugin.');
+}

package/cli/download-nats.ts

@@ -0,0 +1,110 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, existsSync, chmodSync, renameSync, rmSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { NATS_SERVER_BIN, BIN_DIR } from './paths';
+
+const NATS_VERSION = '2.10.24';
+
+export function detectPlatform(): { os: string; arch: string } {
+  const platform = process.platform;
+  const architecture = process.arch;
+
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error(`Unsupported platform: ${platform}. Only linux and darwin are supported.`);
+  }
+  if (architecture !== 'arm64' && architecture !== 'x64') {
+    throw new Error(`Unsupported architecture: ${architecture}. Only arm64 and x64 are supported.`);
+  }
+
+  const os = platform === 'darwin' ? 'darwin' : 'linux';
+  const arch = architecture === 'arm64' ? 'arm64' : 'amd64';
+
+  return { os, arch };
+}
+
+export function getNatsDownloadUrl(version: string, os: string, arch: string): string {
+  return `https://github.com/nats-io/nats-server/releases/download/v${version}/nats-server-v${version}-${os}-${arch}.zip`;
+}
+
+export async function downloadNatsServer(): Promise<string> {
+  if (existsSync(NATS_SERVER_BIN)) {
+    console.log('nats-server already installed, skipping download');
+    return NATS_SERVER_BIN;
+  }
+
+  const { os, arch } = detectPlatform();
+  const url = getNatsDownloadUrl(NATS_VERSION, os, arch);
+  const zipPath = join(BIN_DIR, 'nats-server.zip');
+  const extractDir = join(BIN_DIR, 'nats-extract');
+
+  mkdirSync(BIN_DIR, { recursive: true });
+
+  console.log(`Downloading nats-server v${NATS_VERSION} (${os}/${arch})...`);
+
+  let lastError: Error | null = null;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      execFileSync('curl', ['-fsSL', '-o', zipPath, url], { stdio: 'pipe', timeout: 120_000 });
+      lastError = null;
+      break;
+    } catch (e) {
+      lastError = e as Error;
+      console.warn(`Download attempt ${attempt}/3 failed, retrying...`);
+    }
+  }
+
+  if (lastError) {
+    throw new Error(
+      `Failed to download nats-server after 3 attempts.\n` +
+      `Download manually from: ${url}\n` +
+      `Place binary at: ${NATS_SERVER_BIN}`
+    );
+  }
+
+  // Verify SHA256 checksum
+  const checksumUrl = `https://github.com/nats-io/nats-server/releases/download/v${NATS_VERSION}/SHA256SUMS`;
+  try {
+    execFileSync('curl', ['-fsSL', '-o', join(BIN_DIR, 'SHA256SUMS'), checksumUrl], { stdio: 'pipe', timeout: 30_000 });
+
+    const zipData = readFileSync(zipPath);
+    const actualHash = createHash('sha256').update(zipData).digest('hex');
+    const checksumContent = readFileSync(join(BIN_DIR, 'SHA256SUMS'), 'utf-8');
+    const expectedLine = checksumContent.split('\n').find(line => line.includes(`nats-server-v${NATS_VERSION}-${os}-${arch}.zip`));
+    if (expectedLine) {
+      const expectedHash = expectedLine.split(/\s+/)[0];
+      if (actualHash !== expectedHash) {
+        rmSync(zipPath);
+        throw new Error(`Checksum mismatch for nats-server download.\nExpected: ${expectedHash}\nActual:   ${actualHash}`);
+      }
+      console.log('Checksum verified');
+    } else {
+      console.warn('Warning: Could not find checksum for this platform, skipping verification');
+    }
+  } catch (e) {
+    if (e instanceof Error && e.message.includes('Checksum mismatch')) throw e;
+    console.warn('Warning: Could not download checksums, skipping verification');
+  } finally {
+    const sumsPath = join(BIN_DIR, 'SHA256SUMS');
+    if (existsSync(sumsPath)) rmSync(sumsPath);
+  }
+
+  try {
+    mkdirSync(extractDir, { recursive: true });
+    execFileSync('unzip', ['-o', zipPath, '-d', extractDir], { stdio: 'pipe' });
+
+    const innerDir = `nats-server-v${NATS_VERSION}-${os}-${arch}`;
+    const extractedBin = join(extractDir, innerDir, 'nats-server');
+
+    renameSync(extractedBin, NATS_SERVER_BIN);
+    chmodSync(NATS_SERVER_BIN, 0o755);
+  } finally {
+    if (existsSync(zipPath)) rmSync(zipPath);
+    if (existsSync(extractDir)) rmSync(extractDir, { recursive: true });
+  }
+
+  console.log(`nats-server installed at ${NATS_SERVER_BIN}`);
+  return NATS_SERVER_BIN;
+}
+
+export { NATS_VERSION };

package/cli/env-writer.ts

@@ -0,0 +1,58 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { OPENCLAW_ENV } from './paths';
+
+export function generateApiKey(): string {
+  return randomBytes(32).toString('hex');
+}
+
+export function mergeEnvContent(
+  existingContent: string,
+  variables: Record<string, string>,
+): string {
+  const lines = existingContent.split('\n');
+  const updatedKeys = new Set<string>();
+
+  const updatedLines = lines.map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) return line;
+
+    const key = trimmed.slice(0, eqIndex);
+    if (key in variables) {
+      updatedKeys.add(key);
+      return `${key}=${variables[key]}`;
+    }
+    return line;
+  });
+
+  const newVars = Object.entries(variables)
+    .filter(([key]) => !updatedKeys.has(key))
+    .map(([key, value]) => `${key}=${value}`);
+
+  if (newVars.length > 0) {
+    const lastLine = updatedLines[updatedLines.length - 1]?.trim();
+    if (lastLine !== '' && updatedLines.length > 0) {
+      updatedLines.push('');
+    }
+    updatedLines.push('# NATS Plugin');
+    updatedLines.push(...newVars);
+  }
+
+  return updatedLines.join('\n');
+}
+
+export function writeEnvVariables(variables: Record<string, string>): void {
+  mkdirSync(dirname(OPENCLAW_ENV), { recursive: true });
+
+  const existing = existsSync(OPENCLAW_ENV)
+    ? readFileSync(OPENCLAW_ENV, 'utf-8')
+    : '';
+
+  const merged = mergeEnvContent(existing, variables);
+  writeFileSync(OPENCLAW_ENV, merged, 'utf-8');
+  console.log(`Environment variables written to ${OPENCLAW_ENV}`);
+}

package/cli/lifecycle.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { STATE_FILE, PLUGIN_DIR, DOCKER_DIR, type PluginState } from './paths';
+import {
+  startService, stopService, isServiceRunning, removeServiceUnit,
+} from './service-units';
+
+const NATS_SERVICE = 'openclaw-nats';
+const SIDECAR_SERVICE = 'openclaw-nats-sidecar';
+
+function loadState(): PluginState {
+  if (!existsSync(STATE_FILE)) {
+    throw new Error('NATS plugin not installed. Run: npx @omnixal/openclaw-nats-plugin setup');
+  }
+  return JSON.parse(readFileSync(STATE_FILE, 'utf-8'));
+}
+
+export async function runStart(): Promise<void> {
+  const state = loadState();
+
+  if (state.runtime === 'bun') {
+    startService(NATS_SERVICE);
+    startService(SIDECAR_SERVICE);
+    console.log('NATS services started');
+  } else {
+    execFileSync('docker', ['compose', 'up', '-d'], { cwd: DOCKER_DIR, stdio: 'inherit' });
+    console.log('NATS containers started');
+  }
+}
+
+export async function runStop(): Promise<void> {
+  const state = loadState();
+
+  if (state.runtime === 'bun') {
+    stopService(SIDECAR_SERVICE);
+    stopService(NATS_SERVICE);
+    console.log('NATS services stopped');
+  } else {
+    execFileSync('docker', ['compose', 'stop'], { cwd: DOCKER_DIR, stdio: 'inherit' });
+    console.log('NATS containers stopped');
+  }
+}
+
+export async function runStatus(): Promise<void> {
+  const state = loadState();
+
+  console.log(`Runtime: ${state.runtime}`);
+  console.log(`Installed: ${state.installedAt}\n`);
+
+  if (state.runtime === 'bun') {
+    const natsRunning = isServiceRunning(NATS_SERVICE);
+    const sidecarRunning = isServiceRunning(SIDECAR_SERVICE);
+    console.log(`NATS server:  ${natsRunning ? 'running' : 'stopped'}`);
+    console.log(`Sidecar:      ${sidecarRunning ? 'running' : 'stopped'}`);
+  } else {
+    try {
+      execFileSync('docker', ['compose', 'ps'], { cwd: DOCKER_DIR, stdio: 'inherit' });
+    } catch {
+      console.log('Docker containers not found');
+    }
+  }
+
+  // Check connectivity
+  try {
+    const res = await fetch('http://127.0.0.1:3104/metrics', {
+      signal: AbortSignal.timeout(3000),
+    });
+    console.log(`\nSidecar API:  ${res.ok ? 'healthy' : 'unhealthy'}`);
+  } catch {
+    console.log('\nSidecar API:  unreachable');
+  }
+
+  try {
+    const res = await fetch('http://127.0.0.1:8222/healthz', {
+      signal: AbortSignal.timeout(3000),
+    });
+    console.log(`NATS health:  ${res.ok ? 'healthy' : 'unhealthy'}`);
+  } catch {
+    console.log('NATS health:  unreachable');
+  }
+}
+
+export async function runUninstall(purge: boolean): Promise<void> {
+  const state = loadState();
+
+  console.log(`Uninstalling NATS plugin (${state.runtime} mode)...`);
+
+  if (state.runtime === 'bun') {
+    removeServiceUnit(SIDECAR_SERVICE);
+    removeServiceUnit(NATS_SERVICE);
+  } else {
+    try {
+      execFileSync('docker', ['compose', 'down'], { cwd: DOCKER_DIR, stdio: 'inherit' });
+    } catch {
+      // Containers might not exist
+    }
+  }
+
+  if (purge) {
+    console.log('Purging all data...');
+    rmSync(PLUGIN_DIR, { recursive: true, force: true });
+  } else {
+    rmSync(STATE_FILE, { force: true });
+    console.log('Services removed. Data preserved at ' + PLUGIN_DIR);
+    console.log('Use --purge to remove all data.');
+  }
+
+  console.log('Uninstall complete.');
+}