@omercnet/paseo-context-mode 0.0.0

package/server/mcp-process.ts

@@ -0,0 +1,357 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import type { LaunchDescriptor } from "./binary";
+
+export const PROCESS_OUTPUT_LIMIT = 192 * 1_024;
+export const PROCESS_TIMEOUT_MS = 12_000;
+export const PROCESS_TERMINATION_GRACE_MS = 500;
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+
+export type ProcessFailureCode =
+  | "timeout"
+  | "output-limit"
+  | "launch-failed"
+  | "protocol-error"
+  | "unsupported"
+  | "command-failed";
+
+export class ProcessFailure extends Error {
+  constructor(
+    readonly code: ProcessFailureCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ProcessFailure";
+  }
+}
+
+export interface McpInspection {
+  version: string | null;
+  tools: string[];
+}
+
+export interface McpProcessDependencies {
+  spawnProcess?: typeof spawn;
+  timeoutMs?: number;
+  outputLimit?: number;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  terminationGraceMs?: number;
+}
+
+export type McpJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | McpJsonValue[]
+  | { [key: string]: McpJsonValue };
+
+export type McpToolArguments = Readonly<Record<string, McpJsonValue>>;
+
+export type ContextModeToolName =
+  | "ctx_doctor"
+  | "ctx_stats"
+  | "ctx_upgrade"
+  | "ctx_search"
+  | "ctx_index"
+  | "ctx_fetch_and_index"
+  | "ctx_purge";
+
+export const CONTEXT_MODE_TOOL_TIMEOUT_MS: Readonly<Record<ContextModeToolName, number>> = {
+  ctx_doctor: 15_000,
+  ctx_stats: 15_000,
+  ctx_search: 20_000,
+  ctx_index: 120_000,
+  ctx_fetch_and_index: 45_000,
+  ctx_purge: 120_000,
+  ctx_upgrade: 120_000,
+};
+
+type JsonRpcResponse = {
+  id?: number;
+  result?: unknown;
+  error?: { code?: number; message?: string };
+};
+
+function safeMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message;
+  return String(value);
+}
+
+function extractToolOutput(result: unknown): string {
+  if (!result || typeof result !== "object") {
+    throw new ProcessFailure("protocol-error", "Context Mode returned an invalid tool result.");
+  }
+  const value = result as {
+    content?: Array<{ type?: string; text?: unknown }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+  };
+  const text = value.content
+    ?.filter((item) => item?.type === "text" && typeof item.text === "string")
+    .map((item) => item.text as string)
+    .join("\n");
+  const output =
+    text && text.trim().length > 0
+      ? text
+      : value.structuredContent === undefined
+        ? ""
+        : JSON.stringify(value.structuredContent, null, 2);
+  if (value.isError) {
+    throw new ProcessFailure("command-failed", output || "Context Mode reported a tool error.");
+  }
+  return output;
+}
+
+async function exchange(
+  launch: LaunchDescriptor,
+  operation:
+    | { kind: "inspect" }
+    | { kind: "tool"; name: ContextModeToolName; arguments: McpToolArguments },
+  dependencies: McpProcessDependencies,
+): Promise<McpInspection | string> {
+  const spawnProcess = dependencies.spawnProcess ?? spawn;
+  const timeoutMs =
+    dependencies.timeoutMs ??
+    (operation.kind === "tool" ? CONTEXT_MODE_TOOL_TIMEOUT_MS[operation.name] : PROCESS_TIMEOUT_MS);
+  const terminationGraceMs = dependencies.terminationGraceMs ?? PROCESS_TERMINATION_GRACE_MS;
+  const outputLimit = dependencies.outputLimit ?? PROCESS_OUTPUT_LIMIT;
+
+  const { promise, resolve, reject } = Promise.withResolvers<McpInspection | string>();
+  let child: ChildProcessWithoutNullStreams;
+  try {
+    child = spawnProcess(launch.program, launch.args, {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+      cwd: dependencies.cwd,
+      env: dependencies.env ? { ...process.env, ...dependencies.env } : undefined,
+    });
+  } catch (error) {
+    throw new ProcessFailure(
+      "launch-failed",
+      `Could not launch Context Mode: ${safeMessage(error)}`,
+    );
+  }
+
+  let settled = false;
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let lineBuffer = "";
+  let stderr = "";
+  let version: string | null = null;
+
+  const finish = (callback: () => void) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    child.stdout.removeAllListeners();
+    child.stderr.removeAllListeners();
+    child.removeAllListeners();
+    child.stdin.removeAllListeners("error");
+    child.stdin.on("error", () => {});
+
+    let completed = false;
+    const complete = () => {
+      if (completed) return;
+      completed = true;
+      clearTimeout(graceTimer);
+      child.stdin.destroy();
+      callback();
+    };
+    const graceTimer = setTimeout(() => {
+      child.kill("SIGKILL");
+      complete();
+    }, terminationGraceMs);
+    child.once("exit", complete);
+
+    if (child.exitCode != null || child.signalCode != null) {
+      complete();
+      return;
+    }
+    try {
+      if (!child.stdin.destroyed) child.stdin.end();
+      child.kill("SIGTERM");
+    } catch {
+      child.kill("SIGKILL");
+      complete();
+    }
+  };
+  const fail = (failure: ProcessFailure) => finish(() => reject(failure));
+  const writeMessage = (message: unknown) => {
+    if (settled) return;
+    if (child.stdin.destroyed || !child.stdin.writable) {
+      fail(new ProcessFailure("protocol-error", "Context Mode closed its protocol input."));
+      return;
+    }
+    try {
+      child.stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+        if (error) {
+          fail(
+            new ProcessFailure(
+              "protocol-error",
+              `Context Mode protocol write failed: ${safeMessage(error)}`,
+            ),
+          );
+        }
+      });
+    } catch (error) {
+      fail(
+        new ProcessFailure(
+          "protocol-error",
+          `Context Mode protocol write failed: ${safeMessage(error)}`,
+        ),
+      );
+    }
+  };
+  const timer = setTimeout(
+    () =>
+      fail(new ProcessFailure("timeout", `Context Mode did not respond within ${timeoutMs} ms.`)),
+    timeoutMs,
+  );
+
+  child.stdin.on("error", (error) => {
+    fail(
+      new ProcessFailure(
+        "protocol-error",
+        `Context Mode protocol input failed: ${safeMessage(error)}`,
+      ),
+    );
+  });
+
+  child.once("error", (error) => {
+    fail(
+      new ProcessFailure("launch-failed", `Could not launch Context Mode: ${safeMessage(error)}`),
+    );
+  });
+  child.once("exit", (code, signal) => {
+    if (settled) return;
+    const detail = stderr.trim() || `exit ${code ?? "unknown"}${signal ? ` (${signal})` : ""}`;
+    fail(new ProcessFailure("command-failed", `Context Mode stopped before replying: ${detail}`));
+  });
+  child.stderr.on("data", (chunk: Buffer) => {
+    stderrBytes += chunk.byteLength;
+    if (stdoutBytes + stderrBytes > outputLimit) {
+      fail(
+        new ProcessFailure(
+          "output-limit",
+          `Context Mode exceeded the ${outputLimit}-byte output limit.`,
+        ),
+      );
+      return;
+    }
+    stderr += chunk.toString("utf8");
+  });
+  child.stdout.on("data", (chunk: Buffer) => {
+    stdoutBytes += chunk.byteLength;
+    if (stdoutBytes + stderrBytes > outputLimit) {
+      fail(
+        new ProcessFailure(
+          "output-limit",
+          `Context Mode exceeded the ${outputLimit}-byte output limit.`,
+        ),
+      );
+      return;
+    }
+    lineBuffer += chunk.toString("utf8");
+    const lines = lineBuffer.split(/\r?\n/);
+    lineBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let response: JsonRpcResponse;
+      try {
+        response = JSON.parse(line) as JsonRpcResponse;
+      } catch {
+        fail(
+          new ProcessFailure("protocol-error", "Context Mode emitted invalid MCP protocol output."),
+        );
+        return;
+      }
+      if (response.id === 1) {
+        if (response.error) {
+          fail(
+            new ProcessFailure(
+              "protocol-error",
+              response.error.message ?? "Context Mode initialization failed.",
+            ),
+          );
+          return;
+        }
+        const result = response.result as { serverInfo?: { version?: unknown } } | undefined;
+        version =
+          typeof result?.serverInfo?.version === "string" ? result.serverInfo.version : null;
+        writeMessage({ jsonrpc: "2.0", method: "notifications/initialized" });
+        writeMessage(
+          operation.kind === "inspect"
+            ? { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }
+            : {
+                jsonrpc: "2.0",
+                id: 2,
+                method: "tools/call",
+                params: { name: operation.name, arguments: operation.arguments },
+              },
+        );
+        continue;
+      }
+      if (response.id !== 2) continue;
+      if (response.error) {
+        const message = response.error.message ?? "Context Mode rejected the request.";
+        const unsupported =
+          response.error.code === -32601 || /unknown|not found|unsupported/i.test(message);
+        fail(new ProcessFailure(unsupported ? "unsupported" : "command-failed", message));
+        return;
+      }
+      if (operation.kind === "inspect") {
+        const result = response.result as { tools?: Array<{ name?: unknown }> } | undefined;
+        const tools = (result?.tools ?? [])
+          .map((tool) => tool.name)
+          .filter((name): name is string => typeof name === "string");
+        finish(() => resolve({ version, tools }));
+        return;
+      }
+      try {
+        const output = extractToolOutput(response.result);
+        finish(() => resolve(output));
+      } catch (error) {
+        fail(
+          error instanceof ProcessFailure
+            ? error
+            : new ProcessFailure("protocol-error", safeMessage(error)),
+        );
+      }
+      return;
+    }
+  });
+
+  writeMessage({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "paseo-context-mode", version: "0.0.0" },
+    },
+  });
+  return await promise;
+}
+
+export async function inspectContextMode(
+  launch: LaunchDescriptor,
+  dependencies: McpProcessDependencies = {},
+): Promise<McpInspection> {
+  return (await exchange(launch, { kind: "inspect" }, dependencies)) as McpInspection;
+}
+
+export async function callContextModeTool(
+  launch: LaunchDescriptor,
+  name: ContextModeToolName,
+  arguments_: McpToolArguments = {},
+  dependencies: McpProcessDependencies = {},
+): Promise<string> {
+  return (await exchange(
+    launch,
+    { kind: "tool", name, arguments: arguments_ },
+    dependencies,
+  )) as string;
+}

package/server/storage-discovery.ts

@@ -0,0 +1,225 @@
+import type { Dirent } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import type { AnalyticsWarning } from "../shared/analytics";
+
+const MAX_DATABASES_PER_DIRECTORY = 512;
+const MAX_LOCAL_DISCOVERY_WARNINGS = 10;
+
+export interface ProviderStorageRoot {
+  provider: string;
+  root: string;
+  sessionsDir: string;
+  contentDir: string;
+}
+
+export interface StorageDiscoveryResult {
+  roots: ProviderStorageRoot[];
+  warnings: AnalyticsWarning[];
+}
+
+export interface StorageDiscoveryOptions {
+  home?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+}
+
+interface ProviderLocation {
+  provider: string;
+  root: string;
+}
+
+function configuredDirectory(
+  value: string | undefined,
+  home: string,
+  envVar: string,
+  warnings: AnalyticsWarning[],
+): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  if (trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return resolve(home, trimmed.slice(2));
+  }
+  if (isAbsolute(trimmed)) return resolve(trimmed);
+  warnings.push({
+    code: "invalid-storage-root",
+    message: `${envVar} was ignored because it is not an absolute path.`,
+  });
+  return null;
+}
+
+function providerLocations(
+  home: string,
+  env: NodeJS.ProcessEnv,
+  warnings: AnalyticsWarning[],
+  platform: NodeJS.Platform,
+): ProviderLocation[] {
+  const configuredRoot = configuredDirectory(
+    env.CONTEXT_MODE_DIR,
+    home,
+    "CONTEXT_MODE_DIR",
+    warnings,
+  );
+  const configuredDataRoot = configuredDirectory(
+    env.CONTEXT_MODE_DATA_DIR,
+    home,
+    "CONTEXT_MODE_DATA_DIR",
+    warnings,
+  );
+  const claudeRoot =
+    configuredDirectory(env.CLAUDE_CONFIG_DIR, home, "CLAUDE_CONFIG_DIR", warnings) ??
+    join(home, ".claude");
+  const codexRoot =
+    configuredDirectory(env.CODEX_HOME, home, "CODEX_HOME", warnings) ?? join(home, ".codex");
+  const kimiRoot =
+    configuredDirectory(env.KIMI_CODE_HOME, home, "KIMI_CODE_HOME", warnings) ??
+    join(home, ".kimi-code");
+  const xdgRoot =
+    platform === "win32"
+      ? (configuredDirectory(env.APPDATA, home, "APPDATA", warnings) ??
+        join(home, "AppData", "Roaming"))
+      : (configuredDirectory(env.XDG_CONFIG_HOME, home, "XDG_CONFIG_HOME", warnings) ??
+        join(home, ".config"));
+
+  return [
+    ...(configuredRoot ? [{ provider: "custom", root: configuredRoot }] : []),
+    ...(configuredDataRoot
+      ? [{ provider: "custom-data", root: join(configuredDataRoot, "context-mode") }]
+      : []),
+    { provider: "claude-code", root: join(claudeRoot, "context-mode") },
+    { provider: "gemini-cli", root: join(home, ".gemini", "context-mode") },
+    { provider: "openclaw", root: join(home, ".openclaw", "context-mode") },
+    { provider: "codex", root: join(codexRoot, "context-mode") },
+    { provider: "cursor", root: join(home, ".cursor", "context-mode") },
+    { provider: "vscode-copilot", root: join(home, ".vscode", "context-mode") },
+    { provider: "copilot-cli", root: join(home, ".copilot", "context-mode") },
+    { provider: "kiro", root: join(home, ".kiro", "context-mode") },
+    { provider: "pi", root: join(home, ".pi", "context-mode") },
+    { provider: "omp", root: join(home, ".omp", "context-mode") },
+    { provider: "qwen-code", root: join(home, ".qwen", "context-mode") },
+    { provider: "kimi", root: join(kimiRoot, "context-mode") },
+    { provider: "kilo", root: join(xdgRoot, "kilo", "context-mode") },
+    { provider: "opencode", root: join(xdgRoot, "opencode", "context-mode") },
+    { provider: "zed", root: join(home, ".config", "zed", "context-mode") },
+    {
+      provider: "jetbrains-copilot",
+      root: join(home, ".config", "JetBrains", "context-mode"),
+    },
+  ];
+}
+
+function storageWarning(provider: string, message: string, database?: string): AnalyticsWarning {
+  return {
+    code: "storage-unavailable",
+    provider,
+    ...(database ? { database } : {}),
+    message,
+  };
+}
+
+export async function discoverContextModeStorageRoots(
+  options: StorageDiscoveryOptions = {},
+): Promise<StorageDiscoveryResult> {
+  const home = resolve(options.home ?? homedir());
+  const env = options.env ?? process.env;
+  const warnings: AnalyticsWarning[] = [];
+  const roots: ProviderStorageRoot[] = [];
+  const seen = new Set<string>();
+
+  for (const location of providerLocations(
+    home,
+    env,
+    warnings,
+    options.platform ?? process.platform,
+  )) {
+    try {
+      const info = await lstat(location.root);
+      if (info.isSymbolicLink() || !info.isDirectory()) {
+        warnings.push(
+          storageWarning(
+            location.provider,
+            "The Context Mode storage root is not a regular directory.",
+          ),
+        );
+        continue;
+      }
+      const canonical = await realpath(location.root);
+      if (seen.has(canonical)) continue;
+      seen.add(canonical);
+      roots.push({
+        provider: location.provider,
+        root: canonical,
+        sessionsDir: join(canonical, "sessions"),
+        contentDir: join(canonical, "content"),
+      });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      warnings.push(
+        storageWarning(location.provider, "The Context Mode storage root could not be inspected."),
+      );
+    }
+  }
+
+  return { roots, warnings };
+}
+
+export async function listRegularContextModeDatabases(
+  provider: string,
+  directory: string,
+): Promise<{ files: string[]; warnings: AnalyticsWarning[] }> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { files: [], warnings: [] };
+    return {
+      files: [],
+      warnings: [
+        storageWarning(
+          provider,
+          `The ${basename(directory)} database directory could not be read.`,
+        ),
+      ],
+    };
+  }
+
+  const candidates = entries
+    .filter((entry) => entry.name.endsWith(".db"))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const files: string[] = [];
+  const warnings: AnalyticsWarning[] = [];
+
+  for (const entry of candidates.slice(0, MAX_DATABASES_PER_DIRECTORY)) {
+    const path = join(directory, entry.name);
+    try {
+      const info = await lstat(path);
+      if (entry.isFile() && info.isFile()) {
+        files.push(path);
+      } else if (warnings.length < MAX_LOCAL_DISCOVERY_WARNINGS) {
+        warnings.push({
+          code: "not-regular-database",
+          provider,
+          database: entry.name,
+          message: "Skipped a .db entry that is not a regular file.",
+        });
+      }
+    } catch {
+      if (warnings.length < MAX_LOCAL_DISCOVERY_WARNINGS) {
+        warnings.push(
+          storageWarning(provider, "A database disappeared during discovery.", entry.name),
+        );
+      }
+    }
+  }
+
+  if (candidates.length > MAX_DATABASES_PER_DIRECTORY) {
+    warnings.push({
+      code: "result-truncated",
+      provider,
+      message: `Only the first ${MAX_DATABASES_PER_DIRECTORY} database files in ${basename(directory)} were inspected.`,
+    });
+  }
+
+  return { files, warnings };
+}

package/shared/actions.ts

@@ -0,0 +1,57 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { ContextModePlatformSchema, ContextModeProviderSchema } from "./knowledge";
+
+export const CONTEXT_MODE_TARGET_VERSION = "1.0.169" as const;
+
+const providerInput = z.object({ provider: ContextModeProviderSchema }).strict();
+
+export const DoctorStatusRowSchema = z
+  .object({
+    status: z.enum(["ok", "warning", "error"]),
+    check: z.string().trim().min(1).max(256),
+    detail: z.string().max(4_096),
+  })
+  .strict();
+
+export const DoctorReportSchema = z
+  .object({
+    platform: ContextModePlatformSchema,
+    rows: z.array(DoctorStatusRowSchema).max(64),
+    rawOutput: z.string().max(192 * 1_024),
+  })
+  .strict();
+
+export const ContextModeActionSchema = z
+  .object({
+    program: z.string().trim().min(1).max(4_096),
+    args: z.array(z.string().max(4_096)).max(32),
+    currentVersion: z.string().trim().min(1).max(128).nullable(),
+    targetVersion: z.union([z.literal(CONTEXT_MODE_TARGET_VERSION), z.literal("latest")]),
+    platform: ContextModePlatformSchema,
+    requiresRestart: z.boolean(),
+  })
+  .strict();
+
+export const getContextModeDoctorReport = defineRpc({
+  name: "context-mode.actions.doctor",
+  input: providerInput,
+  output: DoctorReportSchema,
+});
+
+export const getContextModeInstallAction = defineRpc({
+  name: "context-mode.actions.install",
+  input: providerInput,
+  output: ContextModeActionSchema,
+});
+
+export const getContextModeUpgradeAction = defineRpc({
+  name: "context-mode.actions.upgrade",
+  input: providerInput,
+  output: ContextModeActionSchema,
+});
+
+export type DoctorStatusRow = z.infer<typeof DoctorStatusRowSchema>;
+export type DoctorReport = z.infer<typeof DoctorReportSchema>;
+export type ContextModeAction = z.infer<typeof ContextModeActionSchema>;
+export type ContextModeActionInput = z.infer<typeof providerInput>;