@penpair/core 0.1.3 → 0.3.0

package/dist/client.d.ts

@@ -1,22 +1,38 @@
 import { type Endpoint } from "./endpoint.js";
-import { type PenpairErrorCode } from "./errors.js";
+import { PenpairError, type PenpairErrorCode } from "./errors.js";
+export interface ExecutionMetrics {
+    requestSnippetBytes: number;
+    responsePayloadBytes: number;
+}
 export interface ToolOutcome {
+    metrics?: ExecutionMetrics;
     text: string;
+    structuredContent?: unknown;
     isError: boolean;
 }
 /** The only Penpot surface penpair needs: one tool call at a time on an already connected editor. */
+export interface ToolCallOptions {
+    timeoutMs?: number;
+}
 export interface PenpotToolClient {
-    callTool(name: string, args: Record<string, unknown>): Promise<ToolOutcome>;
+    callTool(name: string, args: Record<string, unknown>, options?: ToolCallOptions): Promise<ToolOutcome>;
     /** The names of the tools the server offers. A hosted Penpot may offer fewer than a local one. */
     listTools?(): Promise<string[]>;
     close(): Promise<void>;
 }
 /** 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 {
+    /** Per-request budget; adapters/guards must forward it. */
+    timeoutMs?: number;
+    /** Only known read-only executions may be retried. Unclassified source is treated as a possible write. */
+    effect?: "read" | "write" | "unknown";
     /** How many times to wait and retry a suspended tab. */
     retries?: number;
     sleep?: (milliseconds: number) => Promise<void>;
@@ -25,13 +41,21 @@ export interface ExecuteOptions {
     redact?: (text: string) => string;
 }
 export interface ExecuteResult {
+    metrics?: ExecutionMetrics;
+    runId: string;
+    outcome: "ran";
     /** What the snippet returned, parsed when it was JSON. */
     result: unknown;
     /** What the snippet printed. */
     log: string;
 }
+export declare function executionEnvelope(outcome: ToolOutcome): Pick<ExecuteResult, "result" | "log"> | undefined;
 /**
- * Runs a snippet inside the connected Penpot editor. A suspended tab is waited out and retried, because the snippet may
- * already have run; the caller reads the page before repeating a write.
+ * 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, { retries, 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";
+    constructor(runId: string, message: string);
+}

package/dist/client.js

@@ -1,29 +1,81 @@
+import { commandSignal, commandSleep } from "./command-result.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { randomUUID } from "node:crypto";
+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) {
-    const client = new Client({ name: "penpair", version: "0" });
+export async function connect(endpoint, options = {}) {
+    commandSignal()?.throwIfAborted();
+    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);
+        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) {
+        async callTool(name, args, options) {
             try {
-                const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 120_000 });
+                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, 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);
@@ -31,7 +83,10 @@ export async function connect(endpoint) {
         },
         async listTools() {
             try {
-                return (await client.listTools()).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);
@@ -43,58 +98,96 @@ export async function connect(endpoint) {
     };
 }
 function transportFailure(error, endpoint) {
+    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 = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-function unpack(text) {
-    let envelope;
-    try {
-        envelope = JSON.parse(text);
+const defaultSleep = commandSleep;
+export function executionEnvelope(outcome) {
+    let envelope = outcome.structuredContent;
+    if (envelope === undefined) {
+        try {
+            envelope = JSON.parse(outcome.text);
+        }
+        catch {
+            return undefined;
+        }
     }
-    catch {
+    if (typeof envelope !== "object" ||
+        envelope === null ||
+        Array.isArray(envelope) ||
+        !("result" in envelope) ||
+        ("log" in envelope && typeof envelope.log !== "string")) {
         return undefined;
     }
-    if (typeof envelope !== "object" || envelope === null || !("result" in envelope))
-        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,
+        };
     }
 }
 /**
- * Runs a snippet inside the connected Penpot editor. A suspended tab is waited out and retried, because the snippet may
- * already have run; the caller reads the page before repeating a write.
+ * Retries only declared reads. A lost response to any possible write leaves an uncertain outcome requiring independent inspection.
  */
-export async function executeCode(client, code, { retries = 6, sleep = defaultSleep, onWait, redact = (text) => text } = {}) {
-    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
+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) {
         throw new PenpairError("snippet-too-large", `The snippet is ${Buffer.byteLength(code, "utf8")} bytes`);
+    }
+    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));
     for (let attempt = 0;; attempt++) {
         let outcome;
         try {
-            outcome = await client.callTool("execute_code", { code });
+            commandSignal()?.throwIfAborted();
+            outcome = await client.callTool("execute_code", {
+                code,
+            }, {
+                timeoutMs,
+            });
+            commandSignal()?.throwIfAborted();
         }
         catch (error) {
             if (error instanceof PenpairError && error.code === "plugin-suspended" && attempt < retries) {
@@ -102,18 +195,50 @@ export async function executeCode(client, code, { retries = 6, sleep = defaultSl
                 await sleep(5_000 * (attempt + 1));
                 continue;
             }
+            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 = unpack(outcome.text);
+        const unpacked = executionEnvelope(outcome);
         const failed = outcome.isError || (!unpacked && /^Tool execution failed:/i.test(outcome.text.trim()));
-        if (!failed && unpacked)
-            return unpacked;
+        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") {
+            throw uncertain(outcome.text.slice(0, 500));
+        }
         throw new PenpairError(code_, redact(outcome.text).slice(0, 500));
     }
 }
+export class UncertainExecutionError extends PenpairError {
+    runId;
+    outcome = "uncertain";
+    constructor(runId, message) {
+        super("write-uncertain", `Run ${runId} has an uncertain outcome: ${message}`);
+        this.runId = runId;
+    }
+}

package/dist/command-result.d.ts

@@ -0,0 +1,159 @@
+export interface CommandFailure {
+    code: string;
+    message: string;
+    remedy: string;
+    runId?: string;
+}
+export interface CommandResult {
+    schemaVersion: 1;
+    redacted?: boolean;
+    command: string;
+    outcome: "success" | "drift" | "failed" | "incomplete" | "uncertain" | "cancelled" | "deadline";
+    phase: string;
+    exitCode: number;
+    target: {
+        fileId?: string;
+        pageId?: string;
+    } | null;
+    runId: string | null;
+    data: unknown;
+    messages: string[];
+    warnings: string[];
+    errors: CommandFailure[];
+    completeness: {
+        complete: boolean;
+        reason?: string;
+    };
+    timings: {
+        startedAt: string;
+        durationMs: number;
+    };
+}
+export interface CommandOutput {
+    log(...values: unknown[]): void;
+    error(...values: unknown[]): void;
+    result(value: unknown): void;
+}
+export declare const commandOutput: CommandOutput;
+export declare function commandRedactor(redact: (value: string) => string): void;
+export declare function commandFailure(error: unknown): void;
+export declare function withCommandSignal<T>(signal: AbortSignal, work: () => Promise<T>): Promise<T>;
+/** Bounded explicit restoration work may finish after the main command is cancelled. */
+export declare function withCleanupDeadline<T>(work: () => Promise<T>, milliseconds?: number): Promise<T>;
+export declare function commandSignal(): AbortSignal | undefined;
+export declare function commandSleep(milliseconds: number): Promise<void>;
+export declare class CommandInterruptedError extends Error {
+    readonly code: "cancelled" | "deadline";
+    constructor(code: "cancelled" | "deadline");
+}
+/** Shared service boundary for CLI and future tool surfaces; no stdout or global console interception. */
+export declare function collectCommand(command: string, work: () => Promise<number>, options?: {
+    signal?: AbortSignal;
+}): Promise<CommandResult>;
+/** Outer transport contract. Command-specific data remains owned by the command service. */
+export declare const commandResultSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schemaVersion", "command", "outcome", "phase", "exitCode", "target", "runId", "data", "messages", "warnings", "errors", "completeness", "timings"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 1;
+        };
+        readonly redacted: {
+            readonly type: "boolean";
+        };
+        readonly command: {
+            readonly type: "string";
+        };
+        readonly outcome: {
+            readonly enum: readonly ["success", "drift", "failed", "incomplete", "uncertain", "cancelled", "deadline"];
+        };
+        readonly phase: {
+            readonly type: "string";
+        };
+        readonly exitCode: {
+            readonly enum: readonly [0, 1, 2, 3, 4, 124, 130];
+        };
+        readonly target: {
+            readonly anyOf: readonly [{
+                readonly type: "null";
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly fileId: {
+                        readonly type: "string";
+                    };
+                    readonly pageId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+        readonly runId: {
+            readonly type: readonly ["string", "null"];
+        };
+        readonly data: {};
+        readonly messages: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["code", "message", "remedy"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly remedy: {
+                        readonly type: "string";
+                    };
+                    readonly runId: {
+                        readonly type: "string";
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+        readonly completeness: {
+            readonly type: "object";
+            readonly required: readonly ["complete"];
+            readonly properties: {
+                readonly complete: {
+                    readonly type: "boolean";
+                };
+                readonly reason: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly timings: {
+            readonly type: "object";
+            readonly required: readonly ["startedAt", "durationMs"];
+            readonly properties: {
+                readonly startedAt: {
+                    readonly type: "string";
+                };
+                readonly durationMs: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+};