pim-agent 0.0.1 → 0.10.0

package/packages/core/src/shared/Languages.ts

@@ -0,0 +1,95 @@
+// Values are highlight.js language ids; keep this module import-free, the web bundle needs it.
+
+const ALIASES: Readonly<Record<string, string>> = {
+  ts: "typescript",
+  mts: "typescript",
+  cts: "typescript",
+  tsx: "typescript",
+  js: "javascript",
+  jsx: "javascript",
+  mjs: "javascript",
+  cjs: "javascript",
+  py: "python",
+  rb: "ruby",
+  rs: "rust",
+  go: "go",
+  java: "java",
+  kt: "kotlin",
+  kts: "kotlin",
+  swift: "swift",
+  c: "c",
+  h: "c",
+  cpp: "cpp",
+  cc: "cpp",
+  cxx: "cpp",
+  hpp: "cpp",
+  cs: "csharp",
+  php: "php",
+  sh: "bash",
+  bash: "bash",
+  zsh: "bash",
+  shell: "bash",
+  fish: "fish",
+  ps1: "powershell",
+  sql: "sql",
+  html: "html",
+  htm: "html",
+  vue: "html",
+  svelte: "html",
+  css: "css",
+  scss: "scss",
+  sass: "scss",
+  less: "less",
+  json: "json",
+  jsonc: "json",
+  yaml: "yaml",
+  yml: "yaml",
+  toml: "toml",
+  ini: "ini",
+  xml: "xml",
+  svg: "xml",
+  md: "markdown",
+  markdown: "markdown",
+  dockerfile: "dockerfile",
+  containerfile: "dockerfile",
+  makefile: "makefile",
+  cmake: "cmake",
+  lua: "lua",
+  perl: "perl",
+  pl: "perl",
+  r: "r",
+  scala: "scala",
+  clj: "clojure",
+  ex: "elixir",
+  exs: "elixir",
+  erl: "erlang",
+  hs: "haskell",
+  ml: "ocaml",
+  vim: "vim",
+  graphql: "graphql",
+  gql: "graphql",
+  proto: "protobuf",
+  tf: "hcl",
+  hcl: "hcl",
+  diff: "diff",
+  patch: "diff",
+};
+
+const CANONICAL: ReadonlySet<string> = new Set(Object.values(ALIASES));
+
+// Never guess a language: auto-detection paints ordinary prose as keywords.
+function resolve(name: string | undefined): string | undefined {
+  if (name === undefined) {
+    return undefined;
+  }
+
+  const key = name.trim().toLowerCase();
+  return CANONICAL.has(key) ? key : ALIASES[key];
+}
+
+function fromPath(path: string): string | undefined {
+  const base = path.split(/[/\\]/).pop() ?? "";
+  return resolve(base.includes(".") ? base.split(".").pop() : base);
+}
+
+export const Languages = { resolve, fromPath };

package/packages/core/src/shared/Levenshtein.ts

@@ -0,0 +1,83 @@
+function distance(left: string, right: string): number {
+  if (left === right) {
+    return 0;
+  }
+  if (left.length === 0 || right.length === 0) {
+    return Math.max(left.length, right.length);
+  }
+
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  let current = Array.from({ length: right.length + 1 }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    current[0] = leftIndex;
+
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min(
+        previous[rightIndex]! + 1,
+        current[rightIndex - 1]! + 1,
+        previous[rightIndex - 1]! + cost
+      );
+    }
+
+    [previous, current] = [current, previous];
+  }
+
+  return previous[right.length] ?? 0;
+}
+
+/**
+ * Damerau–Levenshtein, where a transposition is one edit rather than two, and
+ * a pair that cannot reach `max` answers `max + 1` without finishing the
+ * matrix — the shape a vocabulary scan wants, since almost every term it asks
+ * about is nowhere near.
+ */
+function damerau(left: string, right: string, max: number): number {
+  const over = max + 1;
+  if (left === right) {
+    return 0;
+  }
+  if (Math.abs(left.length - right.length) > max) {
+    return over;
+  }
+
+  const width = right.length + 1;
+  let before = Array.from({ length: width }, () => 0);
+  let previous = Array.from({ length: width }, (_, index) => index);
+  let current = Array.from({ length: width }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    current[0] = leftIndex;
+    let best = leftIndex;
+
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      let value = Math.min(
+        previous[rightIndex]! + 1,
+        current[rightIndex - 1]! + 1,
+        previous[rightIndex - 1]! + cost
+      );
+      if (
+        leftIndex > 1 &&
+        rightIndex > 1 &&
+        left[leftIndex - 1] === right[rightIndex - 2] &&
+        left[leftIndex - 2] === right[rightIndex - 1]
+      ) {
+        value = Math.min(value, before[rightIndex - 2]! + 1);
+      }
+      current[rightIndex] = value;
+      best = Math.min(best, value);
+    }
+
+    if (best > max) {
+      return over;
+    }
+    [before, previous, current] = [previous, current, before];
+  }
+
+  const found = previous[right.length]!;
+  return found > max ? over : found;
+}
+
+export const Levenshtein = { distance, damerau };

package/packages/core/src/shared/Lines.ts

@@ -0,0 +1,79 @@
+const utf8Bom = "\uFEFF";
+const utf8BomBytes = new Uint8Array([0xef, 0xbb, 0xbf]);
+
+/** How far in a NUL is still evidence of a binary file rather than text. */
+const binarySniffBytes = 8192;
+
+function normalize(content: string): string {
+  return stripUtf8Bom(content).replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+}
+
+function splitNormalized(normalized: string): readonly string[] {
+  if (normalized.length === 0) {
+    return [];
+  }
+
+  const parts = normalized.split("\n");
+
+  if (parts.at(-1) === "") {
+    parts.pop();
+  }
+
+  return parts;
+}
+
+function split(content: string): readonly string[] {
+  return splitNormalized(normalize(content));
+}
+
+function continuationLine(head: string): number {
+  const { lines, hasTrailingNewline } = splitWithTrailingNewline(head);
+  return Math.max(1, lines.length + (hasTrailingNewline ? 1 : 0));
+}
+
+function splitWithTrailingNewline(content: string): {
+  readonly lines: readonly string[];
+  readonly hasTrailingNewline: boolean;
+} {
+  const normalized = normalize(content);
+  return {
+    lines: splitNormalized(normalized),
+    hasTrailingNewline: normalized.endsWith("\n"),
+  };
+}
+
+function stripUtf8Bom(content: string): string {
+  return content.startsWith(utf8Bom) ? content.slice(1) : content;
+}
+
+function hasUtf8Bom(bytes: Uint8Array): boolean {
+  return (
+    bytes[0] === utf8BomBytes[0] &&
+    bytes[1] === utf8BomBytes[1] &&
+    bytes[2] === utf8BomBytes[2]
+  );
+}
+
+function isBinaryBytes(bytes: Uint8Array): boolean {
+  return bytes.subarray(0, binarySniffBytes).includes(0);
+}
+
+async function isBinary(file: Bun.BunFile): Promise<boolean> {
+  return isBinaryBytes(
+    new Uint8Array(await file.slice(0, binarySniffBytes).arrayBuffer())
+  );
+}
+
+export const Lines = {
+  utf8Bom,
+  binarySniffBytes,
+  normalize,
+  split,
+  splitNormalized,
+  continuationLine,
+  splitWithTrailingNewline,
+  stripUtf8Bom,
+  hasUtf8Bom,
+  isBinaryBytes,
+  isBinary,
+};

package/packages/core/src/shared/McpClient.ts

@@ -0,0 +1,444 @@
+import { Errors } from "./Errors";
+import { createKy, type HttpFetch } from "./Http";
+import { Json } from "./Json";
+import { HTTPError, type KyInstance } from "ky";
+import type { RateLimiter } from "./RateLimiter";
+
+export type McpFetch = HttpFetch;
+
+export type McpClientOptions = {
+  readonly endpoint: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: McpFetch;
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly rateLimiter?: RateLimiter;
+};
+
+export type CallToolInput = {
+  readonly name: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  readonly signal?: AbortSignal;
+};
+
+const protocolVersion = "2025-06-18";
+
+type JsonRpcResponse = {
+  readonly id?: unknown;
+  readonly result?: unknown;
+  readonly error?: unknown;
+};
+
+export class McpClientError extends Error {
+  public readonly status: number | undefined;
+
+  public constructor(message: string, status?: number) {
+    super(message);
+    this.name = "McpClientError";
+    this.status = status;
+  }
+}
+
+export class McpClient {
+  private readonly endpoint: string;
+  private readonly extraHeaders: Readonly<Record<string, string>>;
+  private readonly clientName: string;
+  private readonly clientVersion: string;
+  private readonly ky: KyInstance;
+  private readonly rateLimiter: RateLimiter | undefined;
+  private nextRequestId = 1;
+  private sessionPromise: Promise<string | undefined> | undefined;
+
+  public constructor(options: McpClientOptions) {
+    this.endpoint = options.endpoint;
+    this.extraHeaders = options.headers ?? {};
+    this.clientName = options.clientName ?? "pim-agent";
+    this.clientVersion = options.clientVersion ?? "0.0.0";
+    this.rateLimiter = options.rateLimiter;
+    this.ky = createKy(options.fetch);
+  }
+
+  public async callTool(input: CallToolInput): Promise<unknown> {
+    const pending = this.ensureSession();
+    const sessionId = await pending;
+
+    try {
+      return await this.invokeTool(input, sessionId);
+    } catch (error) {
+      if (
+        input.signal?.aborted ||
+        sessionId === undefined ||
+        !isStaleSessionError(error)
+      ) {
+        throw error;
+      }
+
+      this.invalidateSession(pending);
+
+      return this.invokeTool(input, await this.ensureSession());
+    }
+  }
+
+  private ensureSession(): Promise<string | undefined> {
+    const pending = (this.sessionPromise ??= this.handshake().catch(
+      (error: unknown) => {
+        this.invalidateSession(pending);
+        throw error;
+      }
+    ));
+
+    return pending;
+  }
+
+  private invalidateSession(pending: Promise<string | undefined>): void {
+    if (this.sessionPromise === pending) {
+      this.sessionPromise = undefined;
+    }
+  }
+
+  private async handshake(): Promise<string | undefined> {
+    const initialize = await this.sendRpcRequest({
+      id: this.nextRequestId++,
+      method: "initialize",
+      params: {
+        protocolVersion,
+        clientInfo: {
+          name: this.clientName,
+          version: this.clientVersion,
+        },
+        capabilities: {},
+      },
+    });
+
+    await this.sendNotification({
+      sessionId: initialize.sessionId,
+      method: "notifications/initialized",
+      params: {},
+    });
+
+    return initialize.sessionId;
+  }
+
+  private async invokeTool(
+    input: CallToolInput,
+    sessionId: string | undefined
+  ): Promise<unknown> {
+    const requestId = this.nextRequestId++;
+
+    try {
+      const toolCall = await this.sendRpcRequest({
+        id: requestId,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        method: "tools/call",
+        params: {
+          name: input.name,
+          arguments: input.arguments,
+        },
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      });
+
+      return toolCall.envelope.result;
+    } catch (error) {
+      if (input.signal?.aborted) {
+        await this.sendCancellation(sessionId, requestId);
+        throw new McpClientError("MCP request aborted.");
+      }
+
+      throw error;
+    }
+  }
+
+  private async sendRpcRequest(input: {
+    readonly id: number;
+    readonly sessionId?: string;
+    readonly method: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+  }): Promise<{
+    readonly envelope: JsonRpcResponse;
+    readonly sessionId: string | undefined;
+  }> {
+    const response = await this.postJson(
+      {
+        jsonrpc: "2.0",
+        id: input.id,
+        method: input.method,
+        params: input.params,
+      },
+      input.sessionId,
+      input.signal
+    );
+    const envelope = await this.readRpcResponse(response, input.id);
+    const sessionId =
+      input.sessionId ?? response.headers.get("mcp-session-id") ?? undefined;
+
+    if (Json.asRecord(envelope.error) !== undefined) {
+      throw new McpClientError(
+        `MCP JSON-RPC error: ${describeRpcError(envelope.error)}`
+      );
+    }
+
+    return { envelope, sessionId };
+  }
+
+  private async sendNotification(input: {
+    readonly sessionId: string | undefined;
+    readonly method: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly rateLimited?: boolean;
+  }): Promise<void> {
+    await this.postJson(
+      {
+        jsonrpc: "2.0",
+        method: input.method,
+        params: input.params,
+      },
+      input.sessionId,
+      undefined,
+      input.rateLimited ?? true
+    );
+  }
+
+  private async sendCancellation(
+    sessionId: string | undefined,
+    requestId: number | undefined
+  ): Promise<void> {
+    if (sessionId === undefined || requestId === undefined) {
+      return;
+    }
+
+    try {
+      await this.sendNotification({
+        sessionId,
+        method: "notifications/cancelled",
+        params: {
+          requestId,
+          reason: "Tool call aborted.",
+        },
+        rateLimited: false,
+      });
+    } catch {}
+  }
+
+  private async postJson(
+    body: Readonly<Record<string, unknown>>,
+    sessionId?: string,
+    signal?: AbortSignal,
+    rateLimited = true
+  ): Promise<Response> {
+    if (rateLimited) {
+      await this.rateLimiter?.acquire();
+    }
+
+    try {
+      return await this.ky(this.endpoint, {
+        method: "POST",
+        headers: this.createHeaders(sessionId),
+        json: body,
+        ...(signal === undefined ? {} : { signal }),
+      });
+    } catch (error) {
+      if (signal?.aborted) {
+        throw error;
+      }
+
+      if (error instanceof HTTPError) {
+        throw new McpClientError(
+          `MCP request failed with HTTP ${error.response.status}: ${excerpt(stringifyErrorData(error.data))}`,
+          error.response.status
+        );
+      }
+
+      throw new McpClientError(`MCP request failed: ${Errors.describe(error)}`);
+    }
+  }
+
+  private createHeaders(sessionId: string | undefined): Headers {
+    const headers = new Headers({
+      accept: "application/json, text/event-stream",
+      "mcp-protocol-version": protocolVersion,
+    });
+
+    if (sessionId !== undefined) {
+      headers.set("mcp-session-id", sessionId);
+    }
+
+    for (const [name, value] of Object.entries(this.extraHeaders)) {
+      headers.set(name, value);
+    }
+
+    return headers;
+  }
+
+  private async readRpcResponse(
+    response: Response,
+    id: number
+  ): Promise<JsonRpcResponse> {
+    const contentType = response.headers.get("content-type") ?? "";
+
+    if (contentType.includes("text/event-stream")) {
+      return this.readSseRpcResponse(response, id);
+    }
+
+    const parsed = parseJson(await response.text());
+    const envelope = asRpcResponse(parsed);
+
+    if (envelope === undefined || envelope.id !== id) {
+      throw new McpClientError("MCP returned a malformed JSON-RPC envelope.");
+    }
+
+    return envelope;
+  }
+
+  private async readSseRpcResponse(
+    response: Response,
+    id: number
+  ): Promise<JsonRpcResponse> {
+    if (response.body === null) {
+      throw new McpClientError("MCP returned an empty SSE response.");
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let eventName = "message";
+    const dataLines: string[] = [];
+
+    const dispatch = (): JsonRpcResponse | undefined => {
+      const data = dataLines.join("\n");
+      const currentEventName = eventName;
+
+      dataLines.length = 0;
+      eventName = "message";
+
+      if (data.length === 0 || currentEventName !== "message") {
+        return undefined;
+      }
+
+      const envelope = asRpcResponse(parseJson(data));
+
+      if (envelope === undefined) {
+        throw new McpClientError("MCP returned a malformed JSON-RPC envelope.");
+      }
+
+      return envelope.id === id ? envelope : undefined;
+    };
+
+    try {
+      while (true) {
+        const read = await reader.read();
+
+        buffer += decoder.decode(read.value, { stream: !read.done });
+
+        while (true) {
+          const newlineIndex = buffer.indexOf("\n");
+
+          if (newlineIndex === -1) {
+            break;
+          }
+
+          const rawLine = buffer.slice(0, newlineIndex);
+          const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+
+          buffer = buffer.slice(newlineIndex + 1);
+
+          if (line.length === 0) {
+            const envelope = dispatch();
+
+            if (envelope !== undefined) {
+              return envelope;
+            }
+
+            continue;
+          }
+
+          if (line.startsWith("event:")) {
+            eventName = line.slice("event:".length).trim();
+            continue;
+          }
+
+          if (line.startsWith("data:")) {
+            dataLines.push(line.slice("data:".length).trimStart());
+          }
+        }
+
+        if (read.done) {
+          const envelope = dispatch();
+
+          if (envelope !== undefined) {
+            return envelope;
+          }
+
+          break;
+        }
+      }
+    } finally {
+      await reader.cancel().catch(() => {});
+    }
+
+    throw new McpClientError(
+      "MCP SSE response did not include the expected message."
+    );
+  }
+}
+
+function isStaleSessionError(error: unknown): boolean {
+  return error instanceof McpClientError && error.status === 404;
+}
+
+function asRpcResponse(value: unknown): JsonRpcResponse | undefined {
+  const record = Json.asRecord(value);
+
+  if (record === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(record["id"] === undefined ? {} : { id: record["id"] }),
+    ...(record["result"] === undefined ? {} : { result: record["result"] }),
+    ...(record["error"] === undefined ? {} : { error: record["error"] }),
+  };
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new McpClientError("MCP returned invalid JSON.");
+  }
+}
+
+function describeRpcError(error: unknown): string {
+  const record = Json.asRecord(error);
+  const message = record?.["message"];
+
+  if (typeof message === "string" && message.length > 0) {
+    return message;
+  }
+
+  return JSON.stringify(error);
+}
+
+function stringifyErrorData(data: unknown): string {
+  if (typeof data === "string") {
+    return data;
+  }
+
+  if (data === undefined) {
+    return "";
+  }
+
+  return JSON.stringify(data);
+}
+
+function excerpt(text: string): string {
+  const normalized = text.replace(/\s+/gu, " ").trim();
+
+  if (normalized.length === 0) {
+    return "<empty>";
+  }
+
+  return normalized.length > 200
+    ? `${normalized.slice(0, 200)}...`
+    : normalized;
+}