memtrace 0.8.9 → 0.8.10

package/pi-package/extension/mcp-client.ts

@@ -0,0 +1,259 @@
+// mcp-client.ts — minimal MCP JSON-RPC 2.0 stdio client for `memtrace mcp`.
+//
+// No runtime npm dependencies. Speaks newline-delimited JSON-RPC over the
+// child process stdin/stdout, implements the initialize handshake, discovers
+// tools via tools/list, and invokes them via tools/call. Designed to be
+// driven by the extension in index.ts.
+
+import { ChildProcess, spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+export interface McpToolDef {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  /** Raw field preserved for forward compatibility (e.g. annotations, _meta). */
+  [k: string]: unknown;
+}
+
+export interface McpContentBlock {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  [k: string]: unknown;
+}
+
+export interface McpToolResult {
+  content: McpContentBlock[];
+  isError?: boolean;
+  [k: string]: unknown;
+}
+
+export interface McpServerInfo {
+  name?: string;
+  version?: string;
+  protocolVersion?: string;
+}
+
+interface PendingReq {
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface StartOptions {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  requestTimeoutMs?: number;
+  debug?: boolean;
+}
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+export class MemtraceClient {
+  private proc: ChildProcess | null = null;
+  private nextId = 1;
+  private pending = new Map<number, PendingReq>();
+  private readline: ReturnType<typeof createInterface> | null = null;
+  private stderrBuf: string[] = [];
+  private requestTimeoutMs: number;
+  private debug: boolean;
+  private disposed = false;
+  readonly server: McpServerInfo = {};
+
+  constructor(opts: StartOptions) {
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 60_000;
+    this.debug = opts.debug ?? false;
+    this.command = opts.command;
+    this.args = opts.args;
+    this.env = opts.env;
+    this.cwd = opts.cwd;
+  }
+
+  readonly command: string;
+  readonly args: string[];
+  readonly env?: Record<string, string>;
+  readonly cwd?: string;
+
+  get connected(): boolean {
+    return !!this.proc && !this.proc.killed && this.proc.exitCode === null;
+  }
+
+  get lastStderr(): string {
+    return this.stderrBuf.slice(-2000).join("");
+  }
+
+  /** Spawn the server and run the initialize handshake. Resolves with server info. */
+  async start(): Promise<McpServerInfo> {
+    if (this.disposed) throw new Error("client disposed");
+    if (this.connected) return this.server;
+
+    const childEnv = { ...process.env, ...(this.env ?? {}) };
+    this.proc = spawn(this.command, this.args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: childEnv,
+      cwd: this.cwd,
+    });
+
+    this.proc.on("exit", (code, signal) => this.handleExit(code, signal));
+    this.proc.on("error", (err) => this.handleExit(null, null, err));
+
+    if (this.proc.stderr) {
+      const rl = createInterface({ input: this.proc.stderr });
+      rl.on("line", (line) => {
+        this.stderrBuf.push(line);
+        if (this.stderrBuf.length > 400) this.stderrBuf.shift();
+        if (this.debug) console.error(`[memtrace stderr] ${line}`);
+      });
+    }
+
+    if (this.proc.stdout) {
+      this.readline = createInterface({ input: this.proc.stdout });
+      this.readline.on("line", (line) => this.handleLine(line));
+    }
+
+    if (!this.proc.stdin) throw new Error("memtrace server has no stdin");
+
+    const initResult = (await this.request("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "memtrace-pi", version: "0.1.0" },
+    })) as { protocolVersion?: string; serverInfo?: { name?: string; version?: string } };
+
+    this.server.protocolVersion = initResult?.protocolVersion;
+    this.server.name = initResult?.serverInfo?.name;
+    this.server.version = initResult?.serverInfo?.version;
+
+    // Tell the server we're ready. Notifications carry no id and expect no reply.
+    this.notify("notifications/initialized", {});
+    return this.server;
+  }
+
+  /** List tools the server exposes. */
+  async listTools(): Promise<McpToolDef[]> {
+    const res = (await this.request("tools/list", {})) as { tools?: McpToolDef[] };
+    return res.tools ?? [];
+  }
+
+  /** Invoke a tool by name with JSON arguments. */
+  async callTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const res = (await this.request("tools/call", { name, arguments: args ?? {} })) as McpToolResult;
+    return {
+      ...res,
+      content: Array.isArray(res?.content) ? res.content : [],
+      isError: !!res?.isError,
+    };
+  }
+
+  /** Stop the server and release resources. Safe to call multiple times. */
+  dispose(): void {
+    this.disposed = true;
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error("memtrace client disposed"));
+    }
+    this.pending.clear();
+    try {
+      this.readline?.close();
+    } catch { /* noop */ }
+    if (this.proc) {
+      try {
+        this.proc.stdin?.end();
+      } catch { /* noop */ }
+      try {
+        this.proc.kill("SIGTERM");
+      } catch { /* noop */ }
+      const force = setTimeout(() => {
+        try { this.proc?.kill("SIGKILL"); } catch { /* noop */ }
+      }, 2000);
+      this.proc.once("exit", () => clearTimeout(force));
+    }
+    this.proc = null;
+  }
+
+  // ---- internals -----------------------------------------------------------
+
+  private handleLine(line: string): void {
+    if (!line) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return; // ignore non-JSON noise on stdout
+    }
+    const obj = msg as { id?: number; method?: string; result?: unknown; error?: unknown };
+    if (typeof obj.id === "number") {
+      const p = this.pending.get(obj.id);
+      if (!p) return;
+      this.pending.delete(obj.id);
+      clearTimeout(p.timer);
+      if (obj.error) {
+        p.reject(toError(obj.error));
+      } else {
+        p.resolve(obj.result);
+      }
+    }
+    // Notifications from server (no id) are ignored for now.
+  }
+
+  private request(method: string, params: unknown): Promise<unknown> {
+    return new Promise((resolveP, rejectP) => {
+      if (!this.proc || !this.proc.stdin || !this.connected) {
+        rejectP(new Error("memtrace server is not connected"));
+        return;
+      }
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          rejectP(new Error(`memtrace request "${method}" timed out after ${this.requestTimeoutMs}ms`));
+        }
+      }, this.requestTimeoutMs);
+      this.pending.set(id, { resolve: resolveP, reject: rejectP, timer });
+      const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
+      this.proc.stdin.write(payload, (err) => {
+        if (err) {
+          if (this.pending.delete(id)) {
+            clearTimeout(timer);
+            rejectP(new Error(`failed to write memtrace request: ${err.message}`));
+          }
+        }
+      });
+    });
+  }
+
+  private notify(method: string, params: unknown): void {
+    if (!this.proc || !this.proc.stdin) return;
+    const payload = JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n";
+    try {
+      this.proc.stdin.write(payload);
+    } catch { /* noop */ }
+  }
+
+  private handleExit(code: number | null, signal: NodeJS.Signals | null, err?: Error): void {
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(
+        err
+          ? new Error(`memtrace server failed to start: ${err.message}`)
+          : new Error(`memtrace server exited (code=${code}, signal=${signal})`),
+      );
+    }
+    this.pending.clear();
+    this.proc = null;
+  }
+}
+
+function toError(rpcError: unknown): Error {
+  if (rpcError && typeof rpcError === "object") {
+    const e = rpcError as { message?: string; code?: number; data?: unknown };
+    const msg = e.message ?? `MCP error ${e.code ?? ""}`.trim();
+    const err = new Error(`memtrace: ${msg}`);
+    (err as Error & { code?: number; data?: unknown }).code = e.code;
+    (err as Error & { code?: number; data?: unknown }).data = e.data;
+    return err;
+  }
+  return new Error(`memtrace: ${String(rpcError)}`);
+}

package/pi-package/extension/schema.ts

@@ -0,0 +1,293 @@
+// schema.ts — convert MCP tool inputSchema (JSON Schema) into Typebox schemas
+// for pi.registerTool, and apply curated labels / prompt guidance for the
+// well-known Memtrace tools. The live server schema is always authoritative;
+// overrides only refine presentation and never change the wire contract.
+
+import { Type, TSchema } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+
+type JsonSchema = Record<string, unknown> | undefined;
+
+/** Convert a JSON Schema fragment into the equivalent Typebox schema. */
+export function jsonSchemaToTypebox(schema: JsonSchema): TSchema {
+  if (!schema || typeof schema !== "object") return Type.Any() as unknown as TSchema;
+  const s = schema as {
+    type?: string | string[];
+    enum?: unknown[];
+    description?: string;
+    default?: unknown;
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    additionalProperties?: unknown;
+  };
+
+  const opts: Record<string, unknown> = {};
+  if (typeof s.description === "string") opts.description = s.description;
+  if ("default" in s) opts.default = s.default;
+
+  if (Array.isArray(s.enum) && s.enum.length > 0) {
+    if (s.type === "string" || s.enum.every((v) => typeof v === "string")) {
+      const union = StringEnum(s.enum as string[]);
+      return withOpts(union, opts) as unknown as TSchema;
+    }
+    const lit = Type.Union(s.enum.map((v) => Type.Literal(v as string | number | boolean)));
+    return withOpts(lit, opts) as unknown as TSchema;
+  }
+
+  if (Array.isArray(s.anyOf)) return Type.Union(s.anyOf.map((x) => jsonSchemaToTypebox(x))) as unknown as TSchema;
+  if (Array.isArray(s.oneOf)) return Type.Union(s.oneOf.map((x) => jsonSchemaToTypebox(x))) as unknown as TSchema;
+
+  const t = Array.isArray(s.type) ? s.type[0] : s.type;
+
+  switch (t) {
+    case "string":
+      return withOpts(Type.String(), opts) as unknown as TSchema;
+    case "integer":
+      return withOpts(Type.Integer(), opts) as unknown as TSchema;
+    case "number":
+      return withOpts(Type.Number(), opts) as unknown as TSchema;
+    case "boolean":
+      return withOpts(Type.Boolean(), opts) as unknown as TSchema;
+    case "array":
+      return withOpts(Type.Array(jsonSchemaToTypebox(s.items)), opts) as unknown as TSchema;
+    case "object":
+    case undefined:
+      if (s.properties || t === "object") return objectSchema(s, opts) as unknown as TSchema;
+      return Type.Any() as unknown as TSchema;
+    case "null":
+      return Type.Null() as unknown as TSchema;
+    default:
+      return Type.Any() as unknown as TSchema;
+  }
+}
+
+function objectSchema(
+  s: { properties?: Record<string, JsonSchema>; required?: string[] },
+  _opts: Record<string, unknown>,
+) {
+  const props: Record<string, TSchema> = {};
+  const required = new Set(s.required ?? []);
+  for (const [key, value] of Object.entries(s.properties ?? {})) {
+    const child = jsonSchemaToTypebox(value);
+    props[key] = required.has(key) ? child : (Type.Optional(child) as TSchema);
+  }
+  return Type.Object(props);
+}
+
+function withOpts<T extends TSchema>(schema: T, opts: Record<string, unknown>): T {
+  // Typebox schema objects are plain JSON-Schema; attach description/default.
+  if (opts.description !== undefined) (schema as unknown as Record<string, unknown>).description = opts.description;
+  if ("default" in opts) (schema as unknown as Record<string, unknown>).default = opts.default;
+  return schema;
+}
+
+// ---- curated presentation overrides ----------------------------------------
+//
+// Keyed by the raw Memtrace tool name. Only label / promptSnippet /
+// promptGuidelines / a friendlier description are set. The parameter schema
+// always comes from the live server so new tools and new params work without
+// a package release.
+
+export interface ToolOverride {
+  label?: string;
+  description?: string;
+  promptSnippet?: string;
+  promptGuidelines?: string[];
+}
+
+export const TOOL_OVERRIDES: Record<string, ToolOverride> = {
+  list_indexed_repositories: {
+    label: "Memtrace: Repos",
+    description:
+      "List repositories indexed in the Memtrace code graph. Call once at session start to discover repo_id values. No parameters.",
+    promptSnippet: "List repos indexed in Memtrace and get their repo_id values",
+    promptGuidelines: [
+      "Call memtrace_list_indexed_repositories once at session start to learn which repos are indexed and capture their repo_id values for later calls.",
+    ],
+  },
+  index_directory: {
+    label: "Memtrace: Index",
+    description:
+      "Index a local source directory into the Memtrace knowledge graph. Pass an absolute path; use incremental:true to refresh, clear_existing:true only for a full rebuild.",
+    promptSnippet: "Index a repo into Memtrace (returns a job_id)",
+    promptGuidelines: [
+      "Use memtrace_index_directory when the current repo is not yet indexed or searches miss a source subdirectory. Poll the returned job_id with memtrace_check_job_status (cap ~100 polls / 5 min).",
+    ],
+  },
+  check_job_status: {
+    label: "Memtrace: Job Status",
+    description: "Poll an indexing job by job_id until status is completed or failed.",
+  },
+  list_jobs: { label: "Memtrace: Jobs", description: "List Memtrace indexing jobs." },
+
+  find_symbol: {
+    label: "Memtrace: Find Symbol",
+    description:
+      "Find a symbol by exact or fuzzy identifier name. Returns name, kind, file_path, start_line, end_line, and symbol_id. Prefer this over grep for 'where is X defined'.",
+    promptSnippet: "Locate a symbol by name (exact or fuzzy) with file:line",
+    promptGuidelines: [
+      "Use memtrace_find_symbol (fuzzy:true) instead of grep/glob to locate a function/class/struct by name. Then use memtrace_get_symbol_context for the WHY (callers/callees), not a whole-file read.",
+    ],
+  },
+  find_code: {
+    label: "Memtrace: Find Code",
+    description:
+      "Hybrid BM25 + semantic search over the indexed codebase. Finds symbols, and text inside their bodies (string literals, error messages, log strings). Prefer over grep for behavior and natural-language queries.",
+    promptSnippet: "Semantic + keyword search across indexed code (catches strings inside function bodies)",
+    promptGuidelines: [
+      "Use memtrace_find_code instead of grep for behavior questions and string literals/error messages inside indexed code — the embedding catches text grep would need wildcards for.",
+    ],
+  },
+  get_source_window: {
+    label: "Memtrace: Source Window",
+    description:
+      "Return a bounded source span around a file/line range returned by other Memtrace tools. Use instead of whole-file read when you only need the span Memtrace pointed at.",
+    promptSnippet: "Read a bounded source span Memtrace returned (not the whole file)",
+    promptGuidelines: [
+      "Use memtrace_get_source_window (or read with offset/limit) to view only the start_line..end_line span Memtrace returned. Never whole-file read a source span Memtrace already located.",
+    ],
+  },
+  get_symbol_context: {
+    label: "Memtrace: Symbol Context",
+    description:
+      "Graph neighborhood of a symbol: callers, callees, type_references, community, processes, cross-repo api_callers. The default next step after find_symbol/find_code to answer 'how does X work'.",
+    promptSnippet: "Callers, callees, community, and processes for a symbol",
+    promptGuidelines: [
+      "After a memtrace_find_symbol / memtrace_find_code hit, call memtrace_get_symbol_context to answer 'how does this work / who calls it'. This is the default next step, not a file read.",
+    ],
+  },
+  analyze_relationships: {
+    label: "Memtrace: Relationships",
+    description:
+      "Directed relationship query: find_callers, find_callees, class_hierarchy, overrides, imports, exporters, type_usages.",
+  },
+
+  get_impact: {
+    label: "Memtrace: Blast Radius",
+    description:
+      "Transitive blast radius of modifying a symbol (upstream callers / downstream deps). Use before any non-trivial edit to know what breaks. Pass parameters per the tool's live schema.",
+    promptSnippet: "What breaks if I change this symbol (transitive impact + risk)",
+    promptGuidelines: [
+      "Before modifying an existing symbol, call memtrace_get_impact to see the blast radius. Do not grep for references to estimate impact — Memtrace computes transitive graph impact.",
+    ],
+  },
+  detect_changes: {
+    label: "Memtrace: Diff Impact",
+    description: "Scope the symbols and processes affected by a git diff or list of changed files.",
+  },
+
+  get_evolution: {
+    label: "Memtrace: Change History",
+    description:
+      "Symbol-level change history over a time window (requires repo_id and from). Modes: recent (per-episode), compound (top files/symbols), summary/overview (totals). Do NOT pass days — use from.",
+    promptSnippet: "What changed in a repo over a time window (symbol-level, not git log)",
+    promptGuidelines: [
+      "Use memtrace_get_evolution (not git log) for 'what changed since <date>'. It requires repo_id and from (e.g. '30d ago'); there is no days parameter.",
+    ],
+  },
+  get_changes_since: {
+    label: "Memtrace: Catch-Up",
+    description: "Changes since a stored anchor timestamp or episode id. Use to resume work after time away.",
+  },
+  get_timeline: {
+    label: "Memtrace: Symbol Timeline",
+    description: "Full history of one symbol across commits and working-tree saves.",
+  },
+  get_episode_replay: {
+    label: "Memtrace: Episode Replay",
+    description: "Replay the graph diff of one commit or working-tree save episode.",
+  },
+  get_cochange_context: {
+    label: "Memtrace: Co-Change",
+    description: "Files that historically co-change with a target symbol, ranked by co-occurrence.",
+  },
+
+  find_central_symbols: {
+    label: "Memtrace: Central Symbols",
+    description: "PageRank / degree centrality over call+reference edges — the symbols the codebase depends on most.",
+  },
+  find_bridge_symbols: {
+    label: "Memtrace: Bridge Symbols",
+    description: "Chokepoint symbols connecting otherwise-separate communities (single points of failure).",
+  },
+  list_communities: {
+    label: "Memtrace: Communities",
+    description: "Louvain communities — how the codebase naturally clusters into logical modules.",
+  },
+  list_processes: {
+    label: "Memtrace: Processes",
+    description: "Detected execution flows / entry points (HTTP handlers, CLI commands, jobs, event handlers).",
+  },
+  get_process_flow: {
+    label: "Memtrace: Process Flow",
+    description: "Trace a single execution path through the call graph.",
+  },
+  find_dependency_path: {
+    label: "Memtrace: Dependency Path",
+    description: "Shortest BFS path between two symbols through the dependency graph.",
+  },
+
+  get_repository_stats: {
+    label: "Memtrace: Repo Stats",
+    description: "Scale of an indexed repo: symbol counts by kind, relationship counts, communities, processes.",
+  },
+  find_dead_code: {
+    label: "Memtrace: Dead Code",
+    description: "Symbols with zero graph reachability (no callers), with kind filters.",
+  },
+  find_most_complex_functions: {
+    label: "Memtrace: Complexity Hotspots",
+    description: "Most complex functions by cyclomatic complexity — refactoring candidates.",
+  },
+  calculate_cyclomatic_complexity: {
+    label: "Memtrace: Complexity",
+    description: "Cyclomatic complexity of a single symbol.",
+  },
+
+  find_api_endpoints: {
+    label: "Memtrace: API Endpoints",
+    description: "HTTP route handlers in a repo, with method and path filters.",
+  },
+  find_api_calls: {
+    label: "Memtrace: API Calls",
+    description: "Outbound HTTP calls a repo makes, with method and path filters.",
+  },
+  get_api_topology: {
+    label: "Memtrace: API Topology",
+    description: "Cross-repo service-to-service HTTP dependency graph.",
+  },
+  get_service_diagram: {
+    label: "Memtrace: Service Diagram",
+    description: "Logical service diagram across indexed repos.",
+  },
+  link_repositories: {
+    label: "Memtrace: Link Repos",
+    description: "Connect already-indexed repos so cross-repo API topology can stitch their HTTP graphs.",
+  },
+  delete_repository: {
+    label: "Memtrace: Delete Repo",
+    description: "Remove a repo and its graph from the index.",
+  },
+  get_style_fingerprint: {
+    label: "Memtrace: Style Fingerprint",
+    description:
+      "Empirical codebase style norm (ternary vs if-else, arrow vs fn-decl, etc.). Use when choosing between competing idioms.",
+    promptGuidelines: [
+      "When choosing between competing idioms (ternary vs if-else, arrow vs fn-decl, const vs let, await vs .then), call memtrace_get_style_fingerprint and match the codebase's empirical norm.",
+    ],
+  },
+};
+
+/** Pi tool name to expose for a raw Memtrace tool name. */
+export function piToolName(memtraceName: string): string {
+  return `memtrace_${memtraceName}`;
+}
+
+/** Raw Memtrace name from a Pi tool name (best-effort). */
+export function memtraceName(piName: string): string {
+  return piName.startsWith("memtrace_") ? piName.slice("memtrace_".length) : piName;
+}

package/pi-package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "memtrace-pi",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Bundled Memtrace Pi extension — installed via memtrace install, not published to npm.",
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}