@sonde/agent 0.2.2 → 0.2.4

package/src/cli/mcp-bridge.ts

@@ -0,0 +1,217 @@
+/**
+ * stdio → StreamableHTTP MCP bridge.
+ *
+ * Claude Code spawns `sonde mcp-bridge` and speaks MCP over stdin/stdout.
+ * This bridge forwards every JSON-RPC message to the hub's /mcp endpoint
+ * using the StreamableHTTP transport and relays responses back on stdout.
+ *
+ * Protocol details:
+ *   stdin  – newline-delimited JSON-RPC (MCP stdio transport)
+ *   stdout – newline-delimited JSON-RPC (MCP stdio transport)
+ *   hub    – HTTP POST /mcp with JSON body, response is JSON or SSE
+ */
+import { loadConfig } from '../config.js';
+
+// ── stdio helpers ──────────────────────────────────────────────────────
+
+/** Write a JSON-RPC message to stdout (newline-delimited). */
+function writeMessage(msg: unknown): void {
+  const json = JSON.stringify(msg);
+  process.stdout.write(`${json}\n`);
+}
+
+/** Log to stderr so it doesn't interfere with the JSON-RPC channel. */
+function log(msg: string): void {
+  process.stderr.write(`[sonde-bridge] ${msg}\n`);
+}
+
+// ── SSE parsing ────────────────────────────────────────────────────────
+
+/** Parse SSE text into individual data payloads. */
+function parseSseEvents(text: string): string[] {
+  const payloads: string[] = [];
+  let currentData = '';
+  for (const line of text.split('\n')) {
+    if (line.startsWith('data: ')) {
+      currentData += line.slice(6);
+    } else if (line === '' && currentData) {
+      payloads.push(currentData);
+      currentData = '';
+    }
+  }
+  // Flush any remaining data (stream may not end with blank line)
+  if (currentData) {
+    payloads.push(currentData);
+  }
+  return payloads;
+}
+
+// ── HTTP transport ─────────────────────────────────────────────────────
+
+interface BridgeOptions {
+  mcpUrl: string;
+  apiKey: string;
+}
+
+class McpHttpTransport {
+  private sessionId: string | undefined;
+  private mcpUrl: string;
+  private apiKey: string;
+
+  constructor(opts: BridgeOptions) {
+    this.mcpUrl = opts.mcpUrl;
+    this.apiKey = opts.apiKey;
+  }
+
+  /** Send a JSON-RPC message to the hub and relay response(s) to stdout. */
+  async send(message: unknown): Promise<void> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      Authorization: `Bearer ${this.apiKey}`,
+    };
+
+    if (this.sessionId) {
+      headers['Mcp-Session-Id'] = this.sessionId;
+    }
+
+    const res = await fetch(this.mcpUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(message),
+    });
+
+    // Capture session ID from response
+    const newSessionId = res.headers.get('mcp-session-id');
+    if (newSessionId) {
+      this.sessionId = newSessionId;
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      log(`Hub returned ${res.status}: ${text}`);
+      // Send JSON-RPC error response if the message had an id
+      const msg = message as { id?: string | number };
+      if (msg.id !== undefined) {
+        writeMessage({
+          jsonrpc: '2.0',
+          id: msg.id,
+          error: { code: -32603, message: `Hub returned HTTP ${res.status}` },
+        });
+      }
+      return;
+    }
+
+    const contentType = res.headers.get('content-type') ?? '';
+
+    if (contentType.includes('text/event-stream')) {
+      // SSE response — parse events and forward each as a JSON-RPC message
+      const text = await res.text();
+      for (const payload of parseSseEvents(text)) {
+        try {
+          const parsed: unknown = JSON.parse(payload);
+          writeMessage(parsed);
+        } catch {
+          log(`Failed to parse SSE payload: ${payload.slice(0, 200)}`);
+        }
+      }
+    } else {
+      // JSON response — forward directly
+      const text = await res.text();
+      if (text) {
+        try {
+          const parsed: unknown = JSON.parse(text);
+          writeMessage(parsed);
+        } catch {
+          log(`Failed to parse JSON response: ${text.slice(0, 200)}`);
+        }
+      }
+    }
+  }
+
+  /** Terminate the session cleanly. */
+  async close(): Promise<void> {
+    if (!this.sessionId) return;
+    try {
+      await fetch(this.mcpUrl, {
+        method: 'DELETE',
+        headers: {
+          'Mcp-Session-Id': this.sessionId,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+      });
+    } catch {
+      // Best-effort cleanup
+    }
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────────
+
+export async function startMcpBridge(): Promise<void> {
+  const config = loadConfig();
+  if (!config) {
+    log('Agent not enrolled. Run "sonde enroll" first.');
+    process.exit(1);
+  }
+
+  if (!config.apiKey) {
+    log('No API key found in agent config. Re-enroll the agent with "sonde enroll".');
+    process.exit(1);
+  }
+
+  const mcpUrl = `${config.hubUrl}/mcp`;
+  log(`Bridging stdio ↔ ${mcpUrl}`);
+
+  const transport = new McpHttpTransport({
+    mcpUrl,
+    apiKey: config.apiKey,
+  });
+
+  // Read newline-delimited JSON-RPC from stdin
+  let buffer = '';
+
+  process.stdin.setEncoding('utf-8');
+  process.stdin.on('data', (chunk: string) => {
+    buffer += chunk;
+    // Process complete lines
+    let newlineIdx: number;
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
+      if (!line) continue;
+
+      let message: unknown;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        log(`Failed to parse stdin message: ${line.slice(0, 200)}`);
+        continue;
+      }
+
+      // Fire and forget — errors are handled inside send()
+      transport.send(message).catch((err: unknown) => {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        log(`Transport error: ${errorMsg}`);
+        // Try to send a JSON-RPC error if we can extract the message id
+        const msg = message as { id?: string | number };
+        if (msg.id !== undefined) {
+          writeMessage({
+            jsonrpc: '2.0',
+            id: msg.id,
+            error: { code: -32603, message: `Bridge transport error: ${errorMsg}` },
+          });
+        }
+      });
+    }
+  });
+
+  process.stdin.on('end', async () => {
+    log('stdin closed, shutting down');
+    await transport.close();
+    process.exit(0);
+  });
+
+  // Keep the process alive
+  process.stdin.resume();
+}

package/src/cli/update.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { checkForUpdate, semverLt } from './update.js';
+
+describe('semverLt', () => {
+  it('returns true when a < b (major)', () => {
+    expect(semverLt('0.1.0', '1.0.0')).toBe(true);
+  });
+
+  it('returns true when a < b (minor)', () => {
+    expect(semverLt('1.0.0', '1.1.0')).toBe(true);
+  });
+
+  it('returns true when a < b (patch)', () => {
+    expect(semverLt('1.1.0', '1.1.1')).toBe(true);
+  });
+
+  it('returns false when equal', () => {
+    expect(semverLt('1.2.3', '1.2.3')).toBe(false);
+  });
+
+  it('returns false when a > b', () => {
+    expect(semverLt('2.0.0', '1.9.9')).toBe(false);
+  });
+});
+
+describe('checkForUpdate', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('returns update info when newer version is available', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '99.0.0' }),
+    });
+
+    const result = await checkForUpdate();
+    expect(result.latestVersion).toBe('99.0.0');
+    expect(result.updateAvailable).toBe(true);
+  });
+
+  it('returns no update when on latest version', async () => {
+    // Use 0.0.0 which is lower than any real version
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '0.0.0' }),
+    });
+
+    const result = await checkForUpdate();
+    expect(result.updateAvailable).toBe(false);
+  });
+
+  it('throws on network error', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'));
+
+    await expect(checkForUpdate()).rejects.toThrow('Network error');
+  });
+
+  it('throws on non-ok response', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+    });
+
+    await expect(checkForUpdate()).rejects.toThrow('Failed to check npm registry');
+  });
+});

package/src/cli/update.ts

@@ -0,0 +1,78 @@
+import { execFileSync } from 'node:child_process';
+import { VERSION } from '../version.js';
+
+/**
+ * Lightweight semver comparison: returns true if a < b.
+ */
+export function semverLt(a: string, b: string): boolean {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av < bv) return true;
+    if (av > bv) return false;
+  }
+  return false;
+}
+
+/**
+ * Check for available updates by querying the npm registry.
+ */
+export async function checkForUpdate(): Promise<{
+  currentVersion: string;
+  latestVersion: string;
+  updateAvailable: boolean;
+}> {
+  const res = await fetch('https://registry.npmjs.org/@sonde/agent/latest', {
+    headers: { Accept: 'application/json' },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to check npm registry (HTTP ${res.status})`);
+  }
+  const data = (await res.json()) as { version?: string };
+  const latestVersion = data.version;
+  if (!latestVersion) {
+    throw new Error('No version found in npm registry response');
+  }
+
+  return {
+    currentVersion: VERSION,
+    latestVersion,
+    updateAvailable: semverLt(VERSION, latestVersion),
+  };
+}
+
+/**
+ * Perform the update by running npm install -g.
+ * After install, tries to restart the systemd service (best-effort).
+ */
+export function performUpdate(targetVersion: string): void {
+  console.log(`Installing @sonde/agent@${targetVersion}...`);
+  execFileSync('npm', ['install', '-g', `@sonde/agent@${targetVersion}`], {
+    stdio: 'inherit',
+    timeout: 120_000,
+  });
+
+  // Verify the installed version
+  const output = execFileSync('sonde', ['--version'], {
+    encoding: 'utf-8',
+    timeout: 5_000,
+  }).trim();
+  if (output !== targetVersion) {
+    throw new Error(`Version mismatch after install: expected ${targetVersion}, got ${output}`);
+  }
+
+  console.log(`Successfully updated to v${targetVersion}`);
+
+  // Best-effort systemd restart
+  try {
+    execFileSync('systemctl', ['restart', 'sonde-agent'], {
+      timeout: 10_000,
+    });
+    console.log('Restarted sonde-agent systemd service');
+  } catch {
+    // systemd not available or service not installed — that's fine
+  }
+}

package/src/config.ts

@@ -12,6 +12,7 @@ export interface AgentConfig {
   keyPath?: string;
   caCertPath?: string;
   scrubPatterns?: string[];
+  allowUnsignedPacks?: boolean;
 }
 
 const CONFIG_DIR = path.join(os.homedir(), '.sonde');
@@ -22,11 +23,24 @@ export function getConfigPath(): string {
 }
 
 export function loadConfig(): AgentConfig | undefined {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+  } catch (err: unknown) {
+    const code = (err as { code?: string }).code;
+    if (code === 'ENOENT') return undefined;
+    if (code === 'EACCES') {
+      console.error(`Cannot read config at ${CONFIG_FILE}. Check file permissions.`);
+      process.exit(1);
+    }
+    return undefined;
+  }
+
   try {
-    const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
     return JSON.parse(raw) as AgentConfig;
   } catch {
-    return undefined;
+    console.error(`Config file corrupted at ${CONFIG_FILE}. Re-enroll with "sonde enroll".`);
+    process.exit(1);
   }
 }
 

package/src/index.ts

@@ -2,11 +2,13 @@
 
 import os from 'node:os';
 import { handlePacksCommand } from './cli/packs.js';
+import { checkForUpdate, performUpdate } from './cli/update.js';
 import { type AgentConfig, getConfigPath, loadConfig, saveConfig } from './config.js';
 import { AgentConnection, type ConnectionEvents, enrollWithHub } from './runtime/connection.js';
 import { ProbeExecutor } from './runtime/executor.js';
 import { checkNotRoot } from './runtime/privilege.js';
 import { buildPatterns } from './runtime/scrubber.js';
+import { VERSION } from './version.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -25,6 +27,8 @@ function printUsage(): void {
   console.log('  start     Start the agent (TUI by default, --headless for daemon)');
   console.log('  status    Show agent status');
   console.log('  packs     Manage packs (list, scan, install, uninstall)');
+  console.log('  update    Check for and install agent updates');
+  console.log('  mcp-bridge  stdio MCP bridge (for Claude Code integration)');
   console.log('');
   console.log('Enroll options:');
   console.log('  --hub <url>      Hub URL (e.g. http://localhost:3000)');
@@ -63,6 +67,21 @@ function createRuntime(events: ConnectionEvents): Runtime {
   return { config, executor, connection };
 }
 
+async function cmdUpdate(): Promise<void> {
+  console.log(`Current version: v${VERSION}`);
+  console.log('Checking for updates...');
+
+  const { latestVersion, updateAvailable } = await checkForUpdate();
+
+  if (!updateAvailable) {
+    console.log(`Already on the latest version (v${latestVersion}).`);
+    return;
+  }
+
+  console.log(`New version available: v${latestVersion}`);
+  performUpdate(latestVersion);
+}
+
 async function cmdEnroll(): Promise<void> {
   const hubUrl = getArg('--hub');
   const apiKey = getArg('--key');
@@ -128,20 +147,28 @@ function cmdStart(): void {
       config.agentId = agentId;
       saveConfig(config);
     },
+    onUpdateAvailable: (latestVersion, currentVersion) => {
+      console.log(
+        `Update available: v${currentVersion} → v${latestVersion}. Run "sonde update" to upgrade.`,
+      );
+    },
   });
 
-  console.log('Sonde Agent v0.1.0');
+  console.log(`Sonde Agent v${VERSION}`);
   console.log(`  Name: ${config.agentName}`);
   console.log(`  Hub:  ${config.hubUrl}`);
   console.log('');
 
   connection.start();
+  process.stdin.unref();
 
-  process.on('SIGINT', () => {
+  const shutdown = () => {
     console.log('\nShutting down...');
     connection.stop();
     process.exit(0);
-  });
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }
 
 async function cmdManager(): Promise<void> {
@@ -176,6 +203,11 @@ async function cmdInstall(): Promise<void> {
   await waitUntilExit();
 }
 
+if (command === '--version' || command === '-v' || hasFlag('--version')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 switch (command) {
   case 'install':
     cmdInstall().catch((err: Error) => {
@@ -184,8 +216,17 @@ switch (command) {
     });
     break;
   case 'enroll':
-    cmdEnroll().catch((err: Error) => {
-      console.error(`Enrollment failed: ${err.message}`);
+    cmdEnroll().catch((err: Error & { code?: string }) => {
+      if (err.code === 'ECONNREFUSED') {
+        const hubUrl = getArg('--hub') ?? 'the hub';
+        console.error(`Could not connect to hub at ${hubUrl}. Verify the hub is running.`);
+      } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
+        console.error('Authentication failed. Check your API key or enrollment token.');
+      } else if (err.message?.includes('timed out')) {
+        console.error('Enrollment timed out. The hub may be unreachable.');
+      } else {
+        console.error(`Enrollment failed: ${err.message}`);
+      }
       process.exit(1);
     });
     break;
@@ -193,8 +234,14 @@ switch (command) {
     if (hasFlag('--headless')) {
       cmdStart();
     } else {
-      cmdManager().catch((err: Error) => {
-        console.error(err.message);
+      cmdManager().catch((err: Error & { code?: string }) => {
+        if (err.code === 'ECONNREFUSED') {
+          console.error(
+            'Could not connect to hub. Verify the hub is running and the URL is correct.',
+          );
+        } else {
+          console.error(err.message);
+        }
         process.exit(1);
       });
     }
@@ -205,10 +252,28 @@ switch (command) {
   case 'packs':
     handlePacksCommand(args.slice(1));
     break;
+  case 'update':
+    cmdUpdate().catch((err: Error) => {
+      console.error(`Update failed: ${err.message}`);
+      process.exit(1);
+    });
+    break;
+  case 'mcp-bridge':
+    import('./cli/mcp-bridge.js').then(({ startMcpBridge }) =>
+      startMcpBridge().catch((err: Error) => {
+        process.stderr.write(`[sonde-bridge] Fatal: ${err.message}\n`);
+        process.exit(1);
+      }),
+    );
+    break;
   default:
     if (command) {
       printUsage();
-      console.error(`\nUnknown command: ${command}`);
+      if (command.startsWith('--')) {
+        console.error(`\nUnknown flag: ${command}. Did you mean "sonde start ${command}"?`);
+      } else {
+        console.error(`\nUnknown command: ${command}`);
+      }
       process.exit(1);
     } else {
       // No command: launch TUI if enrolled, otherwise show usage

package/src/runtime/connection.ts

@@ -11,6 +11,7 @@ import {
 import WebSocket from 'ws';
 import type { AgentConfig } from '../config.js';
 import { saveCerts } from '../config.js';
+import { VERSION } from '../version.js';
 import { generateAttestation } from './attestation.js';
 import { AgentAuditLog } from './audit.js';
 import type { ProbeExecutor } from './executor.js';
@@ -21,6 +22,7 @@ export interface ConnectionEvents {
   onError?: (error: Error) => void;
   onRegistered?: (agentId: string) => void;
   onProbeCompleted?: (probe: string, status: string, durationMs: number) => void;
+  onUpdateAvailable?: (latestVersion: string, currentVersion: string) => void;
 }
 
 /** Minimum/maximum reconnect delays */
@@ -56,7 +58,7 @@ export function enrollWithHub(
       const payload: Record<string, unknown> = {
         name: config.agentName,
         os: `${process.platform} ${process.arch}`,
-        agentVersion: '0.1.0',
+        agentVersion: VERSION,
         packs: executor.getLoadedPacks(),
         attestation: generateAttestation(config, executor),
       };
@@ -118,13 +120,27 @@ export function enrollWithHub(
       }
     });
 
-    ws.on('error', (err) => {
+    ws.on('error', (err: Error & { code?: string }) => {
       clearTimeout(timeout);
-      reject(err);
+      reject(new Error(humanizeWsError(err, config.hubUrl)));
     });
   });
 }
 
+/** Map low-level WebSocket/network error codes to actionable messages. */
+function humanizeWsError(err: Error & { code?: string }, hubUrl: string): string {
+  switch (err.code) {
+    case 'ECONNREFUSED':
+      return `Could not connect to hub at ${hubUrl}. Verify the hub is running.`;
+    case 'ENOTFOUND':
+      return `Hub hostname not found: ${hubUrl}. Check the URL.`;
+    case 'ETIMEDOUT':
+      return `Connection to hub at ${hubUrl} timed out. The hub may be unreachable.`;
+    default:
+      return err.message;
+  }
+}
+
 /** Build WebSocket options, including TLS client cert if available. */
 function buildWsOptions(config: AgentConfig): WebSocket.ClientOptions {
   const options: WebSocket.ClientOptions = {
@@ -138,7 +154,7 @@ function buildWsOptions(config: AgentConfig): WebSocket.ClientOptions {
       options.cert = fs.readFileSync(config.certPath, 'utf-8');
       options.key = fs.readFileSync(config.keyPath, 'utf-8');
       options.ca = [fs.readFileSync(config.caCertPath, 'utf-8')];
-      options.rejectUnauthorized = false; // Hub uses self-signed CA cert
+      options.rejectUnauthorized = true; // Verify hub cert against our CA
     } catch {
       // Cert files missing or unreadable — fall back to API key only
     }
@@ -223,16 +239,21 @@ export class AgentConnection {
       this.handleMessage(data.toString());
     });
 
-    this.ws.on('close', () => {
+    this.ws.on('close', (code) => {
       this.clearTimers();
+      if (code === 4001) {
+        this.events.onError?.(
+          new Error("Authentication rejected by hub. Run 'sonde enroll' to re-authenticate."),
+        );
+      }
       this.events.onDisconnected?.();
       if (this.running) {
         this.scheduleReconnect();
       }
     });
 
-    this.ws.on('error', (err) => {
-      this.events.onError?.(err);
+    this.ws.on('error', (err: Error & { code?: string }) => {
+      this.events.onError?.(new Error(humanizeWsError(err, this.config.hubUrl)));
     });
   }
 
@@ -260,6 +281,14 @@ export class AgentConnection {
       case 'probe.request':
         this.handleProbeRequest(envelope);
         break;
+      case 'hub.update_available': {
+        const updatePayload = envelope.payload as {
+          latestVersion: string;
+          currentVersion: string;
+        };
+        this.events.onUpdateAvailable?.(updatePayload.latestVersion, updatePayload.currentVersion);
+        break;
+      }
       default:
         break;
     }
@@ -287,6 +316,11 @@ export class AgentConnection {
 
     const response = await this.executor.execute(request);
 
+    // Echo back requestId for concurrent probe correlation
+    if (request.requestId) {
+      response.requestId = request.requestId;
+    }
+
     this.auditLog.log(request.probe, response.status, response.durationMs);
     this.events.onProbeCompleted?.(request.probe, response.status, response.durationMs);
 
@@ -314,7 +348,7 @@ export class AgentConnection {
       payload: {
         name: this.config.agentName,
         os: `${process.platform} ${process.arch}`,
-        agentVersion: '0.1.0',
+        agentVersion: VERSION,
         packs: this.executor.getLoadedPacks(),
         attestation: generateAttestation(this.config, this.executor),
       },
@@ -349,7 +383,7 @@ export class AgentConnection {
         data: { error: message },
         durationMs: 0,
         metadata: {
-          agentVersion: '0.1.0',
+          agentVersion: VERSION,
           packName: 'unknown',
           packVersion: '0.0.0',
           capabilityLevel: 'observe',