pim-agent 0.0.1 → 0.9.0

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;
+}

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

@@ -0,0 +1,84 @@
+const maxBytes = 32 * 1024;
+const maxLineLength = 2000;
+
+function truncateLine(line: string): string {
+  if (line.length <= maxLineLength) {
+    return line;
+  }
+
+  return `${line.slice(0, maxLineLength)}... (line truncated to ${maxLineLength} chars)`;
+}
+
+function truncateUtf8(
+  content: string,
+  limit: number = maxBytes
+): {
+  readonly body: string;
+  readonly returnedBytes: number;
+  readonly totalBytes: number;
+  readonly truncated: boolean;
+} {
+  const totalBytes = Buffer.byteLength(content, "utf8");
+
+  if (totalBytes <= limit) {
+    return {
+      body: content,
+      returnedBytes: totalBytes,
+      totalBytes,
+      truncated: false,
+    };
+  }
+
+  const encoded = new TextEncoder().encode(content);
+  let cut = limit;
+  while (cut > 0 && ((encoded[cut] ?? 0) & 0xc0) === 0x80) {
+    cut -= 1;
+  }
+
+  const body = new TextDecoder("utf-8").decode(encoded.subarray(0, cut));
+
+  return { body, returnedBytes: cut, totalBytes, truncated: true };
+}
+
+function applyByteCap(
+  items: readonly string[],
+  options: {
+    readonly maxBytes?: number;
+    readonly separator?: string;
+  } = {}
+): {
+  readonly visible: readonly string[];
+  readonly droppedItems: number;
+} {
+  const limit = options.maxBytes ?? maxBytes;
+  const separator = options.separator ?? "\n";
+  const separatorBytes = Buffer.byteLength(separator, "utf8");
+  const visible: string[] = [];
+  let bytes = 0;
+
+  for (const item of items) {
+    const itemBytes = Buffer.byteLength(item, "utf8");
+    const cost = visible.length === 0 ? itemBytes : separatorBytes + itemBytes;
+
+    if (visible.length > 0 && bytes + cost > limit) {
+      break;
+    }
+
+    visible.push(item);
+    bytes += cost;
+
+    if (bytes >= limit) {
+      break;
+    }
+  }
+
+  return { visible, droppedItems: items.length - visible.length };
+}
+
+export const OutputBudget = {
+  maxBytes,
+  maxLineLength,
+  truncateLine,
+  truncateUtf8,
+  applyByteCap,
+};

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

@@ -0,0 +1,40 @@
+export const ADD_FILE_MARKER = "*** Add File: ";
+export const DELETE_FILE_MARKER = "*** Delete File: ";
+export const UPDATE_FILE_MARKER = "*** Update File: ";
+export const MOVE_TO_MARKER = "*** Move to:";
+
+const FILE_MARKERS = [
+  ADD_FILE_MARKER,
+  DELETE_FILE_MARKER,
+  UPDATE_FILE_MARKER,
+] as const;
+
+function firstPath(input: string): string | undefined {
+  for (const raw of input.split("\n")) {
+    const line = raw.trim();
+    for (const marker of FILE_MARKERS) {
+      if (line.startsWith(marker)) {
+        return cleanPath(line.slice(marker.length));
+      }
+    }
+  }
+  return undefined;
+}
+
+export function cleanPath(raw: string): string {
+  let path = raw.trim();
+  if (path.startsWith("@")) {
+    path = path.slice(1).trim();
+  }
+  if (path.length >= 2) {
+    const first = path[0]!;
+    const last = path.at(-1)!;
+    if ((first === '"' || first === "'" || first === "`") && first === last) {
+      path = path.slice(1, -1);
+    }
+  }
+  return path;
+}
+
+/** Fault-tolerant scan of V4A patch text for renderers; unrecognized lines are ignored. */
+export const PatchSummary = { firstPath };

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

@@ -0,0 +1,80 @@
+import { chmod, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve as pathResolve, sep } from "node:path";
+
+function pimHomeDir(): string {
+  return expandHome(process.env.PIM_HOME_DIR ?? "~/.pim");
+}
+
+async function ensurePimHome(): Promise<string> {
+  const dir = pimHomeDir();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  return dir;
+}
+
+function resolve(value: string, baseDir: string): string {
+  const expanded = expandHome(value);
+  return isAbsolute(expanded) ? expanded : pathResolve(baseDir, expanded);
+}
+
+function toForwardSlashes(path: string): string {
+  return sep === "/" ? path : path.split(sep).join("/");
+}
+
+function expandHome(value: string): string {
+  if (value === "~") {
+    return homedir();
+  }
+
+  if (value.startsWith("~/")) {
+    return pathResolve(homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function abbreviateHome(path: string): string {
+  const home = homedir();
+  return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+function displayRelative(path: string, cwd: string): string {
+  const rel = relative(cwd, path);
+
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    return path;
+  }
+
+  return rel;
+}
+
+function compare(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function titleOr(
+  path: string | undefined,
+  cwd: string,
+  placeholder = "..."
+): string {
+  return path ? displayRelative(path, cwd) : placeholder;
+}
+
+export const Paths = {
+  pimHomeDir,
+  ensurePimHome,
+  resolve,
+  toForwardSlashes,
+  expandHome,
+  abbreviateHome,
+  displayRelative,
+  titleOr,
+  compare,
+};