@aaroncql/pim-agent 0.0.1

package/src/shared/McpClient.ts

@@ -0,0 +1,406 @@
+import ky, { HTTPError, type KyInstance } from "ky";
+
+export type McpFetch = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1]
+) => ReturnType<typeof fetch>;
+
+export type McpClientOptions = {
+  readonly endpoint: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: McpFetch;
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+};
+
+export type CallToolInput = {
+  readonly name: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  readonly signal?: AbortSignal;
+};
+
+type JsonRpcResponse = {
+  readonly id?: unknown;
+  readonly result?: unknown;
+  readonly error?: unknown;
+};
+
+export class McpClientError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "McpClientError";
+  }
+}
+
+export class McpClient {
+  private static readonly protocolVersion = "2025-06-18";
+
+  private readonly endpoint: string;
+  private readonly extraHeaders: Readonly<Record<string, string>>;
+  private readonly clientName: string;
+  private readonly clientVersion: string;
+  private readonly ky: KyInstance;
+  private nextRequestId = 1;
+
+  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.ky = ky.create(
+      options.fetch === undefined
+        ? {}
+        : { fetch: options.fetch as typeof fetch }
+    );
+  }
+
+  public async callTool(input: CallToolInput): Promise<unknown> {
+    let sessionId: string | undefined;
+    let activeRequestId: number | undefined;
+
+    try {
+      activeRequestId = this.nextRequestId++;
+      const initialize = await this.sendRpcRequest({
+        id: activeRequestId,
+        method: "initialize",
+        params: {
+          protocolVersion: McpClient.protocolVersion,
+          clientInfo: {
+            name: this.clientName,
+            version: this.clientVersion,
+          },
+          capabilities: {},
+        },
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      });
+      sessionId = initialize.sessionId;
+
+      await this.sendNotification({
+        sessionId,
+        method: "notifications/initialized",
+        params: {},
+      });
+
+      activeRequestId = this.nextRequestId++;
+      const toolCall = await this.sendRpcRequest({
+        id: activeRequestId,
+        ...(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, activeRequestId);
+        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 (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>>;
+  }): Promise<void> {
+    await this.postJson(
+      {
+        jsonrpc: "2.0",
+        method: input.method,
+        params: input.params,
+      },
+      input.sessionId
+    );
+  }
+
+  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.",
+        },
+      });
+    } catch {
+      // abort already surfaces; cancel is best-effort
+    }
+  }
+
+  private async postJson(
+    body: Readonly<Record<string, unknown>>,
+    sessionId?: string,
+    signal?: AbortSignal
+  ): Promise<Response> {
+    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))}`
+        );
+      }
+
+      throw new McpClientError(`MCP request failed: ${describeThrown(error)}`);
+    }
+  }
+
+  private createHeaders(sessionId: string | undefined): Headers {
+    const headers = new Headers({
+      accept: "application/json, text/event-stream",
+      "mcp-protocol-version": McpClient.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 asRecord(
+  value: unknown
+): Readonly<Record<string, unknown>> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as Readonly<Record<string, unknown>>;
+}
+
+function asRpcResponse(value: unknown): JsonRpcResponse | undefined {
+  const record = 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 = asRecord(error);
+  const message = record?.["message"];
+
+  if (typeof message === "string" && message.length > 0) {
+    return message;
+  }
+
+  return JSON.stringify(error);
+}
+
+function describeThrown(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(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/src/shared/OutputBudget.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { OutputBudget } from "./OutputBudget";
+
+describe("truncateLine", () => {
+  test("returns lines under the cap untouched", () => {
+    expect(OutputBudget.truncateLine("short")).toBe("short");
+  });
+
+  test("truncates with a signposted suffix once over the cap", () => {
+    const line = "x".repeat(OutputBudget.maxLineLength + 50);
+    expect(OutputBudget.truncateLine(line)).toBe(
+      `${"x".repeat(OutputBudget.maxLineLength)}... (line truncated to ${OutputBudget.maxLineLength} chars)`
+    );
+  });
+});
+
+describe("truncateUtf8", () => {
+  test("returns content unchanged when under cap", () => {
+    const result = OutputBudget.truncateUtf8("hello", 1024);
+    expect(result.body).toBe("hello");
+    expect(result.truncated).toBe(false);
+    expect(result.totalBytes).toBe(5);
+    expect(result.returnedBytes).toBe(5);
+  });
+
+  test("truncates ASCII at exact byte boundary", () => {
+    const result = OutputBudget.truncateUtf8("a".repeat(100), 10);
+    expect(result.body).toBe("a".repeat(10));
+    expect(result.truncated).toBe(true);
+    expect(result.returnedBytes).toBe(10);
+    expect(result.totalBytes).toBe(100);
+  });
+
+  test("backs off to a UTF-8 boundary mid-codepoint", () => {
+    const result = OutputBudget.truncateUtf8("é", 1);
+    expect(result.body).toBe("");
+    expect(result.returnedBytes).toBe(0);
+    expect(result.truncated).toBe(true);
+    expect(result.totalBytes).toBe(2);
+  });
+
+  test("preserves complete multi-byte chars", () => {
+    const result = OutputBudget.truncateUtf8("héllo", 3);
+    expect(result.body).toBe("hé");
+    expect(result.returnedBytes).toBe(3);
+    expect(result.truncated).toBe(true);
+    expect(result.totalBytes).toBe(6);
+  });
+
+  test("backs off across a 4-byte sequence", () => {
+    const result = OutputBudget.truncateUtf8("🦀x", 2);
+    expect(result.body).toBe("");
+    expect(result.returnedBytes).toBe(0);
+    expect(result.truncated).toBe(true);
+  });
+
+  test("defaults to OutputBudget.maxBytes when no cap supplied", () => {
+    const content = "a".repeat(OutputBudget.maxBytes + 100);
+    const result = OutputBudget.truncateUtf8(content);
+    expect(result.body.length).toBe(OutputBudget.maxBytes);
+    expect(result.truncated).toBe(true);
+  });
+});
+
+describe("applyByteCap", () => {
+  test("returns all items when their joined length fits", () => {
+    const items = ["alpha", "beta", "gamma"];
+    const result = OutputBudget.applyByteCap(items);
+    expect(result.visible).toEqual(items);
+    expect(result.droppedItems).toBe(0);
+  });
+
+  test("drops trailing items past the byte cap", () => {
+    const item = "x".repeat(100);
+    const items = Array.from({ length: 20 }, () => item);
+    const result = OutputBudget.applyByteCap(items, { maxBytes: 250 });
+    // 100 + 1 + 100 = 201 fits, adding another 1 + 100 = 302 does not.
+    expect(result.visible).toHaveLength(2);
+    expect(result.droppedItems).toBe(18);
+  });
+
+  test("always includes the first item even when it overflows alone", () => {
+    const head = "x".repeat(500);
+    const result = OutputBudget.applyByteCap([head, "tail"], {
+      maxBytes: 100,
+    });
+    expect(result.visible).toEqual([head]);
+    expect(result.droppedItems).toBe(1);
+  });
+
+  test("respects a custom separator", () => {
+    // Two 5-byte items with a 10-byte separator: 5 + 10 + 5 = 20.
+    const result = OutputBudget.applyByteCap(["alpha", "betas"], {
+      maxBytes: 20,
+      separator: "----------",
+    });
+    expect(result.visible).toEqual(["alpha", "betas"]);
+  });
+});

package/src/shared/OutputBudget.ts

@@ -0,0 +1,79 @@
+export class OutputBudget {
+  public static readonly maxBytes = 32 * 1024;
+  public static readonly maxLineLength = 2000;
+
+  public static truncateLine(line: string): string {
+    if (line.length <= OutputBudget.maxLineLength) {
+      return line;
+    }
+
+    return `${line.slice(0, OutputBudget.maxLineLength)}... (line truncated to ${OutputBudget.maxLineLength} chars)`;
+  }
+
+  public static truncateUtf8(
+    content: string,
+    maxBytes: number = OutputBudget.maxBytes
+  ): {
+    readonly body: string;
+    readonly returnedBytes: number;
+    readonly totalBytes: number;
+    readonly truncated: boolean;
+  } {
+    const totalBytes = Buffer.byteLength(content, "utf8");
+
+    if (totalBytes <= maxBytes) {
+      return {
+        body: content,
+        returnedBytes: totalBytes,
+        totalBytes,
+        truncated: false,
+      };
+    }
+
+    const encoded = new TextEncoder().encode(content);
+    let cut = maxBytes;
+    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 };
+  }
+
+  public static applyByteCap(
+    items: readonly string[],
+    options: {
+      readonly maxBytes?: number;
+      readonly separator?: string;
+    } = {}
+  ): {
+    readonly visible: readonly string[];
+    readonly droppedItems: number;
+  } {
+    const maxBytes = options.maxBytes ?? OutputBudget.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 > maxBytes) {
+        break;
+      }
+
+      visible.push(item);
+      bytes += cost;
+
+      if (bytes >= maxBytes) {
+        break;
+      }
+    }
+
+    return { visible, droppedItems: items.length - visible.length };
+  }
+}

package/src/shared/Paths.test.ts

@@ -0,0 +1,51 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+import { Paths } from "./Paths";
+
+describe("Paths.resolve", () => {
+  test("resolves relative paths against base", () => {
+    expect(Paths.resolve("foo.txt", "/work")).toBe("/work/foo.txt");
+    expect(Paths.resolve("src/foo.ts", "/work")).toBe("/work/src/foo.ts");
+  });
+
+  test("expands ~ to home directory", () => {
+    const home = homedir();
+    expect(Paths.resolve("~", "/tmp")).toBe(home);
+    expect(Paths.resolve("~/.config", "/tmp")).toBe(join(home, ".config"));
+  });
+
+  test("preserves absolute paths", () => {
+    expect(Paths.resolve("/etc/hosts", "/tmp")).toBe("/etc/hosts");
+  });
+});
+
+describe("Paths.displayRelative", () => {
+  test("returns relative path when inside cwd", () => {
+    expect(Paths.displayRelative("/work/src/foo.ts", "/work")).toBe(
+      "src/foo.ts"
+    );
+  });
+
+  test("returns absolute path when outside cwd", () => {
+    expect(Paths.displayRelative("/etc/hosts", "/work")).toBe("/etc/hosts");
+  });
+
+  test("returns absolute path when cwd equals path", () => {
+    expect(Paths.displayRelative("/work", "/work")).toBe("/work");
+  });
+});
+
+describe("Paths.titleOr", () => {
+  test("returns the placeholder when path is undefined", () => {
+    expect(Paths.titleOr(undefined, "/work")).toBe("...");
+  });
+
+  test("returns a path relative to cwd when within cwd", () => {
+    expect(Paths.titleOr("/work/src/file.ts", "/work")).toBe("src/file.ts");
+  });
+
+  test("returns the absolute path when outside cwd", () => {
+    expect(Paths.titleOr("/other/file.ts", "/work")).toBe("/other/file.ts");
+  });
+});

package/src/shared/Paths.ts

@@ -0,0 +1,52 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export class Paths {
+  public static pimHomeDir(): string {
+    return Paths.expandHome(process.env.PIM_HOME_DIR ?? "~/.pim");
+  }
+
+  public static resolve(value: string, baseDir: string): string {
+    const expanded = Paths.expandHome(value);
+    return isAbsolute(expanded) ? expanded : resolve(baseDir, expanded);
+  }
+
+  public static toForwardSlashes(path: string): string {
+    return sep === "/" ? path : path.split(sep).join("/");
+  }
+
+  public static expandHome(value: string): string {
+    if (value === "~") {
+      return homedir();
+    }
+
+    if (value.startsWith("~/")) {
+      return resolve(homedir(), value.slice(2));
+    }
+
+    return value;
+  }
+
+  public static abbreviateHome(path: string): string {
+    const home = homedir();
+    return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+  }
+
+  public static displayRelative(path: string, cwd: string): string {
+    const rel = relative(cwd, path);
+
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+      return path;
+    }
+
+    return rel;
+  }
+
+  public static titleOr(
+    path: string | undefined,
+    cwd: string,
+    placeholder = "..."
+  ): string {
+    return path ? Paths.displayRelative(path, cwd) : placeholder;
+  }
+}