ompchamber 0.3.0

package/src/server/lib/omp/config/config-cli.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * omp config CLI bridge — schema-aware get/set/list/reset over the real
+ * `omp config` command (498-key SETTINGS_SCHEMA with {value,type,description}
+ * metadata). Shell-out instead of RPC because omp exposes no config get/set
+ * RPC command; the CLI is fast (~0.3s) and authoritative.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+
+export interface ConfigEntry {
+  value?: unknown;
+  type: string;
+  description: string;
+}
+
+const BINARY = 'omp';
+const LIST_TIMEOUT_MS = 15_000;
+const WRITE_TIMEOUT_MS = 15_000;
+
+function runOmp(args: string[], timeoutMs: number): Promise<string> {
+  return (async () => {
+    const proc = Bun.spawn({
+      cmd: [BINARY, ...args],
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: timeoutMs,
+      maxBuffer: 16 * 1024 * 1024,
+      windowsHide: true,
+    });
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) throw new Error(`omp ${args[0]} failed: exited with code ${exitCode}`);
+    return stdout;
+  })();
+}
+
+/** Full schema snapshot: key → {value?, type, description}. Empty in mock mode. */
+export async function listOmpConfig(): Promise<Record<string, ConfigEntry>> {
+  if (isMockMode()) return {};
+  const stdout = await runOmp(['config', 'list', '--json'], LIST_TIMEOUT_MS);
+  const parsed: unknown = JSON.parse(stdout);
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('omp config list returned unexpected JSON');
+  }
+  const entries: Record<string, ConfigEntry> = {};
+  for (const [key, raw] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof raw !== 'object' || raw === null) continue;
+    const record = raw as Record<string, unknown>;
+    entries[key] = {
+      value: record.value,
+      type: typeof record.type === 'string' ? record.type : 'unknown',
+      description: typeof record.description === 'string' ? record.description : '',
+    };
+  }
+  return entries;
+}
+
+/** Read one config key's current value (undefined when unset). */
+export async function getOmpConfigValue(key: string): Promise<unknown> {
+  if (isMockMode()) return undefined;
+  const stdout = await runOmp(['config', 'get', key], WRITE_TIMEOUT_MS);
+  const text = stdout.trim();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** Write one config key; returns the value omp reports after the write.
+ * Arrays/records serialize to JSON strings, which `omp config set` parses
+ * against the key's schema type. */
+export async function setOmpConfigValue(
+  key: string,
+  value: string | number | boolean | unknown[] | Record<string, unknown>,
+): Promise<unknown> {
+  if (isMockMode()) throw new Error('config writes are unavailable in mock mode');
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+  await runOmp(['config', 'set', key, serialized], WRITE_TIMEOUT_MS);
+  return getOmpConfigValue(key);
+}
+
+/** Reset one config key to its schema default. */
+export async function resetOmpConfigKey(key: string): Promise<unknown> {
+  if (isMockMode()) throw new Error('config writes are unavailable in mock mode');
+  await runOmp(['config', 'reset', key], WRITE_TIMEOUT_MS);
+  return getOmpConfigValue(key);
+}

package/src/server/lib/omp/config/disabled-providers.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read/write of the native OMP `disabledProviders` list in
+ * ~/.omp/agent/config.yml — the flag behind connect/disconnect in the provider
+ * settings. Writes are atomic read-modify-writes that preserve every other key
+ * in the file.
+ */
+
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import { getOmpConfigPath } from '@/server/lib/omp/config/yaml';
+import { isRecord } from '@/shared/lib/util/guards';
+
+function readDisabledProviderSlugs(data: Record<string, unknown>): string[] {
+  const current = data.disabledProviders;
+  return Array.isArray(current)
+    ? current.filter((item): item is string => typeof item === 'string')
+    : [];
+}
+
+/**
+ * Re-enable a disabled provider by removing it from config.yml
+ * disabledProviders. Returns false when it was not disabled in the first place.
+ */
+export async function enableNativeProvider(slug: string): Promise<boolean> {
+  const path = getOmpConfigPath();
+  const file = Bun.file(path);
+  if (!(await file.exists())) return false;
+  const doc = Bun.YAML.parse(await file.text());
+  if (!isRecord(doc)) return false;
+  const current = readDisabledProviderSlugs(doc);
+  const next = current.filter((item) => item !== slug);
+  if (next.length === current.length) return false;
+  doc.disabledProviders = next;
+  await writeFileAtomic(path, Bun.YAML.stringify(doc, null, 2));
+  return true;
+}
+
+/**
+ * Disable a provider by appending it to config.yml disabledProviders — the
+ * mirror of enableNativeProvider. Written to the agent's own registry so a
+ * later provider merge cannot resurrect it as connected. Creates config.yml
+ * when absent; returns false when the provider was already disabled.
+ */
+export async function disableNativeProvider(slug: string): Promise<boolean> {
+  const path = getOmpConfigPath();
+  const file = Bun.file(path);
+  const source = (await file.exists()) ? await file.text() : '';
+  const doc = Bun.YAML.parse(source);
+  if (doc !== null && !isRecord(doc)) {
+    throw new Error(`${path} must contain a YAML mapping`);
+  }
+  const disabled = isRecord(doc) ? readDisabledProviderSlugs(doc) : [];
+  if (disabled.includes(slug)) return false;
+
+  let content: string;
+  if (isRecord(doc)) {
+    doc.disabledProviders = [...disabled, slug];
+    content = Bun.YAML.stringify(doc, null, 2);
+  } else {
+    content = Bun.YAML.stringify({ disabledProviders: [slug] }, null, 2);
+  }
+  await writeFileAtomic(path, content);
+  return true;
+}

package/src/server/lib/omp/config/extensions.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Extension discovery + toggle — scans .omp/extensions (user + project) and
+ * reads/writes config.yml disabledExtensions ids
+ * (`extension-module:<name>`, `skill:<name>`, `context-file:<level>:<basename>`).
+ */
+
+import { join } from 'path';
+import { getAgentDir, pathExists } from '@/server/lib/omp/core/paths';
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import { asMapping, getOmpConfigPath } from '@/server/lib/omp/config/yaml';
+import { isRecord } from '@/shared/lib/util/guards';
+
+export interface DiscoveredExtension {
+  id: string;
+  name: string;
+  /** Which root the extension file came from. */
+  sourceRoot: 'user' | 'project';
+  filePath: string;
+  disabled: boolean;
+}
+
+const EXTENSION_GLOB = new Bun.Glob('*.{ts,js,mjs,cjs}');
+const MAX_EXTENSION_BYTES = 2 * 1024 * 1024;
+
+async function scanExtensionsDir(dir: string, sourceRoot: 'user' | 'project', disabled: Set<string>): Promise<DiscoveredExtension[]> {
+  if (!(await pathExists(dir))) return [];
+  try {
+    const found: DiscoveredExtension[] = [];
+    for (const relativePath of await Array.fromAsync(EXTENSION_GLOB.scan({ cwd: dir, onlyFiles: true }))) {
+      const filePath = join(dir, relativePath);
+      try {
+        if ((await Bun.file(filePath).stat()).size > MAX_EXTENSION_BYTES) continue;
+      } catch {
+        continue;
+      }
+      const name = relativePath.replace(/\.(ts|js|mjs|cjs)$/, '');
+      const id = `extension-module:${name}`;
+      found.push({ id, name, sourceRoot, filePath, disabled: disabled.has(id) });
+    }
+    return found;
+  } catch {
+    return [];
+  }
+}
+
+/** Discover extensions from the user root (+ project root when given). */
+export async function discoverExtensions(projectDir?: string): Promise<DiscoveredExtension[]> {
+  const disabled = await readDisabledExtensions();
+  const userDir = join(getAgentDir(), 'extensions');
+  const byName = new Map<string, DiscoveredExtension>();
+  for (const ext of await scanExtensionsDir(userDir, 'user', disabled)) byName.set(ext.name, ext);
+  if (projectDir) {
+    for (const ext of await scanExtensionsDir(join(projectDir, '.omp', 'extensions'), 'project', disabled)) {
+      if (!byName.has(ext.name)) byName.set(ext.name, ext);
+    }
+  }
+  return [...byName.values()];
+}
+
+export async function readDisabledExtensions(): Promise<Set<string>> {
+  const path = getOmpConfigPath();
+  const file = Bun.file(path);
+  if (!(await file.exists()) || (await file.stat()).size >= 8 * 1024 * 1024) return new Set();
+  try {
+    const data = Bun.YAML.parse(await file.text());
+    if (!isRecord(data) || !Array.isArray(data.disabledExtensions)) return new Set();
+    return new Set(data.disabledExtensions.filter((item): item is string => typeof item === 'string'));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Toggle one extension id in config.yml disabledExtensions atomically. */
+export async function setExtensionDisabled(id: string, disabled: boolean): Promise<boolean> {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) throw new Error('Invalid extension id');
+  const path = getOmpConfigPath();
+  const doc = asMapping(Bun.YAML.parse((await Bun.file(path).exists()) ? await Bun.file(path).text() : ''), path);
+  const already = (await readDisabledExtensions()).has(id);
+  if (disabled === already) return false;
+  const list = [...(await readDisabledExtensions())];
+  const next = disabled ? [...list, id] : list.filter((item) => item !== id);
+  doc.disabledExtensions = next;
+  await writeFileAtomic(path, Bun.YAML.stringify(doc, null, 2));
+  return true;
+}

package/src/server/lib/omp/config/instructions.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read/write of the two native instruction files omp loads from the user agent
+ * dir (~/.omp/agent):
+ *
+ * - `AGENTS.md` — user context file, injected once into the opening project
+ *   prompt; it shadows every other user-level context file.
+ * - `RULES.md` — user sticky rule, re-sent in full on every request and
+ *   re-read when a session starts or after `/clear` and `/new`.
+ *
+ * Writes are atomic (temp + rename) so a crash never truncates the file, and
+ * the agent dir follows PI_CODING_AGENT_DIR through getAgentDir().
+ */
+
+import fs from 'fs';
+import { join } from 'path';
+import { getAgentDir } from '@/server/lib/omp/core/paths';
+import { writeFileAtomic } from '@/server/lib/fs/atomic-write';
+import type { InstructionFileKind } from '@/shared/types';
+
+/** Basenames omp recognises; the provider reads these exact names. */
+const FILE_NAMES: Record<InstructionFileKind, string> = {
+  agents: 'AGENTS.md',
+  rules: 'RULES.md',
+};
+
+/** Refuse to buffer an absurd instruction file rather than reading it whole. */
+const MAX_INSTRUCTION_BYTES = 1024 * 1024;
+
+export interface InstructionFile {
+  kind: InstructionFileKind;
+  path: string;
+  content: string;
+  exists: boolean;
+}
+
+/** Narrows an untrusted request value to a file this module can read or write. */
+export function isInstructionFileKind(value: unknown): value is InstructionFileKind {
+  return value === 'agents' || value === 'rules';
+}
+
+/** Absolute path of one native instruction file in the user agent dir. */
+export function getInstructionFilePath(kind: InstructionFileKind): string {
+  return join(getAgentDir(), FILE_NAMES[kind]);
+}
+
+/** Reads one instruction file. A missing file is a state, not an error. */
+export async function readInstructionFile(kind: InstructionFileKind): Promise<InstructionFile> {
+  const path = getInstructionFilePath(kind);
+  const file = Bun.file(path);
+  if (!(await file.exists())) return { kind, path, content: '', exists: false };
+  const stat = await file.stat();
+  if (stat.isDirectory()) throw new Error(`${path} is a directory, not a file`);
+  if (stat.size > MAX_INSTRUCTION_BYTES) throw new Error(`${path} is larger than ${MAX_INSTRUCTION_BYTES} bytes`);
+  return { kind, path, content: await file.text(), exists: true };
+}
+
+/**
+ * Writes one instruction file atomically, creating the agent dir when it does
+ * not exist yet. Whitespace-only content removes the file instead of leaving
+ * an empty one behind: omp reads nothing from an empty instruction file, so
+ * absence is the honest state — and an empty AGENTS.md would still claim the
+ * user context scope that another tool's file could otherwise fill.
+ */
+export async function saveInstructionFile(kind: InstructionFileKind, content: string): Promise<InstructionFile> {
+  const path = getInstructionFilePath(kind);
+  if (!content.trim()) return clearInstructionFile(kind);
+  await writeFileAtomic(path, content);
+  return { kind, path, content, exists: true };
+}
+
+/** Removes one instruction file and reports the resulting empty state. */
+export async function clearInstructionFile(kind: InstructionFileKind): Promise<InstructionFile> {
+  const path = getInstructionFilePath(kind);
+  await fs.promises.unlink(path).catch(() => {});
+  return { kind, path, content: '', exists: false };
+}

package/src/server/lib/omp/config/mcp-test.ts

@@ -0,0 +1,346 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Real MCP JSON-RPC 2.0 connectivity test. `command` transport spawns the
+ * configured command and runs the stdio initialize → notifications/initialized
+ * → tools/list exchange (one JSON object per line); `link` transport POSTs
+ * `initialize` to the HTTP/SSE endpoint. The child is always torn down (stdin
+ * EOF, SIGTERM, then SIGKILL) so no orphan survives; MOCK mode returns a
+ * deterministic result without ever spawning.
+ */
+
+import type { Subprocess } from 'bun';
+import { killProcessTree } from '@/server/lib/omp/rpc/kill-tree';
+import { readLines } from '@/server/lib/omp/rpc/lines';
+import { sanitizeProjectCommandEnvironment } from '@/server/lib/omp/rpc/process-helpers';
+import { isMockMode } from '@/server/mock.server';
+import type { McpServerItem } from '@/shared/types';
+import { isRecord } from '@/shared/lib/util/guards';
+
+export type McpTransport = 'command' | 'link';
+
+export interface McpTestResult {
+  ok: boolean;
+  transport: McpTransport;
+  protocolVersion?: string;
+  serverInfo?: { name?: string; version?: string };
+  toolCount?: number;
+  durationMs: number;
+  error?: string;
+}
+
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+const LINK_TIMEOUT_MS = 10_000;
+const PROTOCOL_VERSION = '2025-06-18';
+const REDACTED_SENTINEL = '••••••••';
+const STDERR_TAIL_LIMIT = 8 * 1024;
+const GRACE_PERIOD_MS = 2_000;
+
+const CLIENT_INFO = { name: 'ompchamber', version: '1.0.0' };
+
+interface HandshakeOutcome {
+  protocolVersion?: string;
+  serverInfo?: { name?: string; version?: string };
+  toolCount?: number;
+}
+
+function parseServerInfo(value: unknown): { name?: string; version?: string } | undefined {
+  if (!isRecord(value)) return undefined;
+  const info: { name?: string; version?: string } = {};
+  if (typeof value.name === 'string') info.name = value.name;
+  if (typeof value.version === 'string') info.version = value.version;
+  return info.name !== undefined || info.version !== undefined ? info : undefined;
+}
+
+function describeError(value: unknown): string {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (isRecord(value) && typeof value.message === 'string') return value.message;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return 'Unknown error';
+  }
+}
+
+function initializeRequest(): Record<string, unknown> {
+  return {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO },
+  };
+}
+
+/** Merge configured env vars over the sanitized env, skipping empty values and
+ * the redaction sentinel so masked credentials are never replayed. */
+function mergeEnvVars(server: McpServerItem): NodeJS.ProcessEnv {
+  const env = sanitizeProjectCommandEnvironment(Bun.env);
+  for (const item of server.envVars ?? []) {
+    const key = item?.key?.trim();
+    const value = item?.value;
+    if (!key || value === undefined || value === null || value === '' || value === REDACTED_SENTINEL) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+/** Mirror `RpcProcess.dispose`: stdin EOF, then SIGTERM, then SIGKILL on the
+ * whole process group; resolves once the child has exited so no orphan stays. */
+function disposeChild(child: Subprocess<"pipe", "pipe", "pipe">): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const termTimer = setTimeout(() => {
+      if (!settled) killProcessTree(child.pid, false, 'SIGTERM');
+    }, GRACE_PERIOD_MS);
+    const killTimer = setTimeout(() => {
+      if (!settled) killProcessTree(child.pid, true, 'SIGKILL');
+    }, GRACE_PERIOD_MS * 2);
+    termTimer.unref?.();
+    killTimer.unref?.();
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(termTimer);
+      clearTimeout(killTimer);
+      resolve();
+    };
+    try {
+      child.stdin?.end();
+    } catch {
+      // stdin may already be closed; the exit listener settles the promise.
+    }
+    void child.exited.then(settle);
+    if (child.exitCode !== null || child.signalCode !== null) settle();
+  });
+}
+
+function runHandshake(
+  child: Subprocess<"pipe", "pipe", "pipe">,
+  getStderrTail: () => string,
+): Promise<HandshakeOutcome> {
+  return new Promise<HandshakeOutcome>((resolve, reject) => {
+    let settled = false;
+
+    const overallTimer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`MCP handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`));
+    }, HANDSHAKE_TIMEOUT_MS);
+    overallTimer.unref?.();
+
+    const succeed = (value: HandshakeOutcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(overallTimer);
+      resolve(value);
+    };
+    const fail = (message: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(overallTimer);
+      reject(new Error(message));
+    };
+
+    let init: { protocolVersion?: string; serverInfo?: { name?: string; version?: string } } | null = null;
+
+    const send = (message: unknown) => {
+      const stdin = child.stdin;
+      if (!stdin) return;
+      try {
+        stdin.write(`${JSON.stringify(message)}\n`);
+      } catch {
+        // stdin may already be closed while the child is dying.
+      }
+    };
+
+    void readLines(child.stdout, (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        return; // ignore non-JSON banner/log output on stdout
+      }
+      if (!isRecord(parsed)) return;
+      const id = parsed.id;
+      if (id === 1 || id === '1') {
+        if (parsed.error !== undefined) {
+          fail(`MCP initialize failed: ${describeError(parsed.error)}`);
+          return;
+        }
+        const result = isRecord(parsed.result) ? parsed.result : undefined;
+        init = {
+          protocolVersion: typeof result?.protocolVersion === 'string' ? result.protocolVersion : undefined,
+          serverInfo: result ? parseServerInfo(result.serverInfo) : undefined,
+        };
+        send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+        send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+        return;
+      }
+      if (id === 2 || id === '2') {
+        if (parsed.error !== undefined) {
+          fail(`MCP tools/list failed: ${describeError(parsed.error)}`);
+          return;
+        }
+        const tools = isRecord(parsed.result) ? parsed.result.tools : undefined;
+        succeed({
+          protocolVersion: init?.protocolVersion,
+          serverInfo: init?.serverInfo,
+          toolCount: Array.isArray(tools) ? tools.length : undefined,
+        });
+      }
+    });
+
+    void child.exited.then((code) => {
+      const tail = getStderrTail();
+      const suffix = tail ? `: ${tail.slice(-500)}` : '';
+      fail(`Server exited before completing handshake (code ${code ?? 'null'}, signal ${child.signalCode ?? 'none'})${suffix}`);
+    });
+
+    send(initializeRequest());
+  });
+}
+
+async function runCommandTest(server: McpServerItem, cwd: string | undefined): Promise<McpTestResult> {
+  const commandArgs = (server.commandArgs ?? []).map((arg) => arg.trim()).filter((arg) => arg.length > 0);
+  const startedAt = Date.now();
+  if (commandArgs.length === 0) {
+    return { ok: false, transport: 'command', durationMs: 0, error: 'No command configured' };
+  }
+
+  const child: Subprocess<"pipe", "pipe", "pipe"> = Bun.spawn({
+    cmd: commandArgs,
+    cwd: cwd || process.cwd(),
+    env: mergeEnvVars(server),
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    windowsHide: true,
+    detached: process.platform !== 'win32',
+  });
+
+  let stderrTail = '';
+  void readLines(child.stderr, (line) => {
+    stderrTail = (stderrTail + line + '\n').slice(-STDERR_TAIL_LIMIT);
+  });
+
+  try {
+    const outcome = await runHandshake(child, () => stderrTail);
+    return {
+      ok: true, transport: 'command', protocolVersion: outcome.protocolVersion,
+      serverInfo: outcome.serverInfo, toolCount: outcome.toolCount, durationMs: Date.now() - startedAt,
+    };
+  } catch (error) {
+    return {
+      ok: false, transport: 'command', durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : 'MCP handshake failed',
+    };
+  } finally {
+    await disposeChild(child);
+  }
+}
+
+function extractSseData(text: string): unknown {
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line.startsWith('data:')) continue;
+    const data = line.slice(5).trim();
+    if (!data || data === '[DONE]') continue;
+    try {
+      return JSON.parse(data);
+    } catch {
+      // skip malformed frames; keep scanning for the first parseable data line
+    }
+  }
+  return undefined;
+}
+
+function extractInitializeOutcome(payload: unknown): HandshakeOutcome {
+  const result = isRecord(payload) && isRecord(payload.result) ? payload.result : payload;
+  if (!isRecord(result)) return {};
+  return {
+    protocolVersion: typeof result.protocolVersion === 'string' ? result.protocolVersion : undefined,
+    serverInfo: parseServerInfo(result.serverInfo),
+  };
+}
+
+async function runLinkTest(url: string): Promise<McpTestResult> {
+  const startedAt = Date.now();
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+      body: JSON.stringify(initializeRequest()),
+      signal: AbortSignal.timeout(LINK_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      return {
+        ok: false,
+        transport: 'link',
+        durationMs: Date.now() - startedAt,
+        error: `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}`,
+      };
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+    const payload = contentType.includes('text/event-stream')
+      ? extractSseData(await response.text())
+      : await response.json();
+    const outcome = extractInitializeOutcome(payload);
+    return {
+      ok: true,
+      transport: 'link',
+      protocolVersion: outcome.protocolVersion,
+      serverInfo: outcome.serverInfo,
+      durationMs: Date.now() - startedAt,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      transport: 'link',
+      durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : 'Connection failed',
+    };
+  }
+}
+
+function mockTestResult(server: McpServerItem): McpTestResult {
+  const valid = server.reachType === 'command'
+    ? (server.commandArgs ?? []).some((arg) => arg.trim().length > 0)
+    : typeof server.linkUrl === 'string' && /^https?:\/\//i.test(server.linkUrl);
+  if (!valid) {
+    return { ok: false, transport: server.reachType, durationMs: 12, error: 'Invalid server configuration' };
+  }
+  return {
+    ok: true,
+    transport: server.reachType,
+    protocolVersion: PROTOCOL_VERSION,
+    serverInfo: { name: server.name || undefined, version: '1.0.0' },
+    toolCount: 3,
+    durationMs: 37,
+  };
+}
+
+/** Run a real MCP handshake; resolves with a result record (never throws for a
+ * failed connection). Only truly unexpected errors reject, mapped to a 500 by
+ * the route without leaking env or secrets. */
+export async function testMcpServer(input: { server: McpServerItem; cwd?: string }): Promise<McpTestResult> {
+  const { server, cwd } = input;
+
+  if (isMockMode()) {
+    return mockTestResult(server);
+  }
+
+  if (server.reachType === 'link') {
+    const url = (server.linkUrl ?? '').trim();
+    if (!/^https?:\/\//i.test(url)) {
+      return { ok: false, transport: 'link', durationMs: 0, error: 'Link URL must be a valid http(s) endpoint' };
+    }
+    return runLinkTest(url);
+  }
+
+  return runCommandTest(server, cwd);
+}