@penpair/core 0.2.0 → 0.3.0

package/dist/client.d.ts

@@ -22,7 +22,10 @@ export interface PenpotToolClient {
 }
 /** Penpot's proxy refuses request bodies of about 110 KB; snippets stay under this. */
 export declare const maxSnippetBytes: number;
-export declare function connect(endpoint: Endpoint): Promise<PenpotToolClient>;
+export declare function connect(endpoint: Endpoint, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<PenpotToolClient>;
 /** Maps Penpot MCP failure text to a distinct code so each failure gets its own remedy. */
 export declare function classifyFailure(text: string): PenpairErrorCode;
 export interface ExecuteOptions {
@@ -50,7 +53,7 @@ export declare function executionEnvelope(outcome: ToolOutcome): Pick<ExecuteRes
 /**
  * Retries only declared reads. A lost response to any possible write leaves an uncertain outcome requiring independent inspection.
  */
-export declare function executeCode(client: PenpotToolClient, code: string, { timeoutMs, effect, retries: requestedRetries, sleep, onWait, redact }?: ExecuteOptions): Promise<ExecuteResult>;
+export declare function executeCode(client: PenpotToolClient, code: string, { timeoutMs, effect, retries: requestedRetries, sleep, onWait, redact, }?: ExecuteOptions): Promise<ExecuteResult>;
 export declare class UncertainExecutionError extends PenpairError {
     readonly runId: string;
     readonly outcome = "uncertain";

package/dist/client.js

@@ -1,32 +1,81 @@
 import { commandSignal, commandSleep } from "./command-result.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { randomUUID } from "node:crypto";
-import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { redactEndpoint } from "./endpoint.js";
 import { PenpairError } from "./errors.js";
 /** Penpot's proxy refuses request bodies of about 110 KB; snippets stay under this. */
 export const maxSnippetBytes = 90 * 1024;
-export async function connect(endpoint) {
+export async function connect(endpoint, options = {}) {
     commandSignal()?.throwIfAborted();
-    const client = new Client({ name: "penpair", version: "0" });
+    const signal = options.signal
+        ? AbortSignal.any([
+            options.signal,
+            ...(commandSignal()
+                ? [
+                    commandSignal(),
+                ]
+                : []),
+        ])
+        : commandSignal();
+    const client = new Client({
+        name: "penpair",
+        version: "0",
+    });
     const transport = new StreamableHTTPClientTransport(new URL(endpoint.url));
     try {
-        await client.connect(transport, { signal: commandSignal(), timeout: 120_000 });
+        await client.connect(transport, {
+            signal,
+            timeout: options.timeoutMs ?? 120_000,
+        });
     }
     catch (error) {
+        await client.close().catch(() => undefined);
         throw transportFailure(error, endpoint);
     }
     return {
         async callTool(name, args, options) {
             try {
-                const result = await client.callTool({ name, arguments: args }, undefined, { timeout: options?.timeoutMs ?? 120_000, signal: commandSignal() });
+                const result = await client.callTool({
+                    name,
+                    arguments: args,
+                }, undefined, {
+                    timeout: options?.timeoutMs ?? 120_000,
+                    signal: signal && commandSignal()
+                        ? AbortSignal.any([
+                            signal,
+                            commandSignal(),
+                        ])
+                        : (signal ?? commandSignal()),
+                });
                 const content = Array.isArray(result.content) ? result.content : [];
                 const text = content
-                    .flatMap((item) => typeof item === "object" && item !== null && "type" in item && item.type === "text" && "text" in item
-                    ? [String(item.text)]
+                    .flatMap((item) => typeof item === "object" &&
+                    item !== null &&
+                    "type" in item &&
+                    item.type === "text" &&
+                    "text" in item
+                    ? [
+                        String(item.text),
+                    ]
                     : [])
                     .join("\n");
-                return { text, metrics: { requestSnippetBytes: typeof args.code === "string" ? Buffer.byteLength(args.code, "utf8") : 0, responsePayloadBytes: Buffer.byteLength(text, "utf8") + (result.structuredContent === undefined ? 0 : Buffer.byteLength(JSON.stringify(result.structuredContent), "utf8")) }, ...(result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}), isError: result.isError === true };
+                return {
+                    text,
+                    metrics: {
+                        requestSnippetBytes: typeof args.code === "string" ? Buffer.byteLength(args.code, "utf8") : 0,
+                        responsePayloadBytes: Buffer.byteLength(text, "utf8") +
+                            (result.structuredContent === undefined
+                                ? 0
+                                : Buffer.byteLength(JSON.stringify(result.structuredContent), "utf8")),
+                    },
+                    ...(result.structuredContent !== undefined
+                        ? {
+                            structuredContent: result.structuredContent,
+                        }
+                        : {}),
+                    isError: result.isError === true,
+                };
             }
             catch (error) {
                 throw transportFailure(error, endpoint);
@@ -34,7 +83,10 @@ export async function connect(endpoint) {
         },
         async listTools() {
             try {
-                return (await client.listTools(undefined, { signal: commandSignal(), timeout: 120_000 })).tools.map((tool) => tool.name);
+                return (await client.listTools(undefined, {
+                    signal: commandSignal(),
+                    timeout: 120_000,
+                })).tools.map((tool) => tool.name);
             }
             catch (error) {
                 throw transportFailure(error, endpoint);
@@ -46,25 +98,31 @@ export async function connect(endpoint) {
     };
 }
 function transportFailure(error, endpoint) {
-    if (commandSignal()?.aborted)
+    if (commandSignal()?.aborted) {
         return commandSignal().reason;
+    }
     const raw = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
     const message = redactEndpoint(raw, endpoint);
-    if (error instanceof StreamableHTTPError && (error.code === 401 || error.code === 403))
+    if (error instanceof StreamableHTTPError && (error.code === 401 || error.code === 403)) {
         return new PenpairError("auth-rejected", message);
+    }
     const code = classifyFailure(message);
     return new PenpairError(code === "tool-failed" ? "mcp-unavailable" : code, message);
 }
 /** Maps Penpot MCP failure text to a distinct code so each failure gets its own remedy. */
 export function classifyFailure(text) {
-    if (/suspended|no heartbeat/i.test(text))
+    if (/suspended|no heartbeat/i.test(text)) {
         return "plugin-suspended";
-    if (/not connected|no (?:penpot )?plugin|no client|plugin (?:is )?(?:not|disconnected)|connect the plugin/i.test(text))
+    }
+    if (/not connected|no (?:penpot )?plugin|no client|plugin (?:is )?(?:not|disconnected)|connect the plugin/i.test(text)) {
         return "plugin-disconnected";
-    if (/401|403|unauthori[sz]ed|forbidden|invalid (?:user)?token/i.test(text))
+    }
+    if (/401|403|unauthori[sz]ed|forbidden|invalid (?:user)?token/i.test(text)) {
         return "auth-rejected";
-    if (/ECONNREFUSED|ENOTFOUND|fetch failed|EHOSTUNREACH|socket hang up|ECONNRESET|timed? ?out/i.test(text))
+    }
+    if (/ECONNREFUSED|ENOTFOUND|fetch failed|EHOSTUNREACH|socket hang up|ECONNRESET|timed? ?out/i.test(text)) {
         return "mcp-unavailable";
+    }
     return "tool-failed";
 }
 const defaultSleep = commandSleep;
@@ -78,28 +136,45 @@ export function executionEnvelope(outcome) {
             return undefined;
         }
     }
-    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope) || !("result" in envelope) || "log" in envelope && typeof envelope.log !== "string")
+    if (typeof envelope !== "object" ||
+        envelope === null ||
+        Array.isArray(envelope) ||
+        !("result" in envelope) ||
+        ("log" in envelope && typeof envelope.log !== "string")) {
         return undefined;
+    }
     const log = "log" in envelope && typeof envelope.log === "string" ? envelope.log : "";
     const raw = envelope.result;
-    if (typeof raw !== "string")
-        return { result: raw, log };
+    if (typeof raw !== "string") {
+        return {
+            result: raw,
+            log,
+        };
+    }
     try {
-        return { result: JSON.parse(raw), log };
+        return {
+            result: JSON.parse(raw),
+            log,
+        };
     }
     catch {
-        return { result: raw, log };
+        return {
+            result: raw,
+            log,
+        };
     }
 }
 /**
  * Retries only declared reads. A lost response to any possible write leaves an uncertain outcome requiring independent inspection.
  */
-export async function executeCode(client, code, { timeoutMs = 120_000, effect = "unknown", retries: requestedRetries = 6, sleep = defaultSleep, onWait, redact = (text) => text } = {}) {
+export async function executeCode(client, code, { timeoutMs = 120_000, effect = "unknown", retries: requestedRetries = 6, sleep = defaultSleep, onWait, redact = (text) => text, } = {}) {
     commandSignal()?.throwIfAborted();
-    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
+    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes) {
         throw new PenpairError("snippet-too-large", `The snippet is ${Buffer.byteLength(code, "utf8")} bytes`);
-    if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000) {
         throw new Error("Execution timeout must be from 1 to 120000 ms");
+    }
     const retries = effect === "read" ? requestedRetries : 0;
     const runId = randomUUID();
     const uncertain = (message) => new UncertainExecutionError(runId, redact(message));
@@ -107,7 +182,11 @@ export async function executeCode(client, code, { timeoutMs = 120_000, effect =
         let outcome;
         try {
             commandSignal()?.throwIfAborted();
-            outcome = await client.callTool("execute_code", { code }, { timeoutMs });
+            outcome = await client.callTool("execute_code", {
+                code,
+            }, {
+                timeoutMs,
+            });
             commandSignal()?.throwIfAborted();
         }
         catch (error) {
@@ -116,22 +195,42 @@ export async function executeCode(client, code, { timeoutMs = 120_000, effect =
                 await sleep(5_000 * (attempt + 1));
                 continue;
             }
-            if (effect !== "read" && (!(error instanceof PenpairError) || !["file-mismatch", "snippet-too-large", "auth-rejected"].includes(error.code)))
+            if (effect !== "read" &&
+                (!(error instanceof PenpairError) ||
+                    ![
+                        "file-mismatch",
+                        "snippet-too-large",
+                        "auth-rejected",
+                    ].includes(error.code))) {
                 throw uncertain(error instanceof Error ? error.message : String(error));
+            }
             throw error;
         }
         const unpacked = executionEnvelope(outcome);
         const failed = outcome.isError || (!unpacked && /^Tool execution failed:/i.test(outcome.text.trim()));
-        if (!failed && unpacked)
-            return { ...unpacked, runId, outcome: "ran", metrics: outcome.metrics ?? { requestSnippetBytes: Buffer.byteLength(code, "utf8"), responsePayloadBytes: Buffer.byteLength(outcome.text, "utf8") + (outcome.structuredContent === undefined ? 0 : Buffer.byteLength(JSON.stringify(outcome.structuredContent), "utf8")) } };
+        if (!failed && unpacked) {
+            return {
+                ...unpacked,
+                runId,
+                outcome: "ran",
+                metrics: outcome.metrics ?? {
+                    requestSnippetBytes: Buffer.byteLength(code, "utf8"),
+                    responsePayloadBytes: Buffer.byteLength(outcome.text, "utf8") +
+                        (outcome.structuredContent === undefined
+                            ? 0
+                            : Buffer.byteLength(JSON.stringify(outcome.structuredContent), "utf8")),
+                },
+            };
+        }
         const code_ = classifyFailure(outcome.text);
         if (code_ === "plugin-suspended" && attempt < retries) {
             onWait?.(`Penpot tab is suspended; bring it to the foreground (retry ${attempt + 1}/${retries})`);
             await sleep(5_000 * (attempt + 1));
             continue;
         }
-        if (effect !== "read" && code_ !== "auth-rejected")
+        if (effect !== "read" && code_ !== "auth-rejected") {
             throw uncertain(outcome.text.slice(0, 500));
+        }
         throw new PenpairError(code_, redact(outcome.text).slice(0, 500));
     }
 }