@milaboratories/pl-mcp-server 0.2.0

package/dist/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_server = require("./server.cjs");
+exports.PlMcpServer = require_server.PlMcpServer;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { McpSecret, PlMcpServer, PlMcpServerCallbacks, PlMcpServerOptions, ServerConnection } from "./server.js";
+export { type McpSecret, PlMcpServer, type PlMcpServerCallbacks, type PlMcpServerOptions, type ServerConnection };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { PlMcpServer } from "./server.js";
+export { PlMcpServer };

package/dist/server.cjs

@@ -0,0 +1,171 @@
+const require_ping = require("./tools/ping.cjs");
+const require_connection = require("./tools/connection.cjs");
+const require_projects = require("./tools/projects.cjs");
+const require_blocks = require("./tools/blocks.cjs");
+const require_block_state = require("./tools/block-state.cjs");
+const require_await = require("./tools/await.cjs");
+const require_logs = require("./tools/logs.cjs");
+const require_data_query = require("./tools/data-query.cjs");
+const require_screenshot = require("./tools/screenshot.cjs");
+const require_ui_interaction = require("./tools/ui-interaction.cjs");
+let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+let node_http = require("node:http");
+let node_crypto = require("node:crypto");
+let _milaboratories_pl_middle_layer = require("@milaboratories/pl-middle-layer");
+//#region src/server.ts
+var PlMcpServer = class {
+	ml;
+	port;
+	secret;
+	callbacks;
+	httpServer;
+	transports = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.ml = options.middleLayer ?? null;
+		this.port = options.port;
+		this.secret = options.secret;
+		this.callbacks = options.callbacks ?? {};
+	}
+	/** Set or update the MiddleLayer instance (e.g. after connecting to a server). */
+	setMiddleLayer(ml) {
+		this.ml = ml ?? null;
+	}
+	get url() {
+		return `http://127.0.0.1:${this.port}/${this.secret}/mcp`;
+	}
+	async start() {
+		if (this.httpServer) throw new Error("MCP server is already running");
+		const expectedPath = `/${this.secret}/mcp`;
+		this.httpServer = (0, node_http.createServer)(async (req, res) => {
+			try {
+				if (req.headers.origin !== void 0) try {
+					const origin = new URL(req.headers.origin);
+					if (origin.hostname !== "localhost" && origin.hostname !== "127.0.0.1") {
+						res.writeHead(403, { "Content-Type": "application/json" });
+						res.end(JSON.stringify({ error: "Forbidden" }));
+						return;
+					}
+				} catch {
+					res.writeHead(403, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Forbidden" }));
+					return;
+				}
+				if (req.url !== expectedPath) {
+					res.writeHead(404, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Not Found" }));
+					return;
+				}
+				const sessionId = req.headers["mcp-session-id"];
+				if (sessionId && this.transports.has(sessionId)) {
+					await this.transports.get(sessionId).handleRequest(req, res);
+					return;
+				}
+				const transport = new _modelcontextprotocol_sdk_server_streamableHttp_js.StreamableHTTPServerTransport({ sessionIdGenerator: () => (0, node_crypto.randomUUID)() });
+				transport.onclose = () => {
+					const sid = transport.sessionId;
+					if (sid) this.transports.delete(sid);
+				};
+				await this.createMcpServer().connect(transport);
+				await transport.handleRequest(req, res);
+				const sid = transport.sessionId;
+				if (sid) this.transports.set(sid, transport);
+			} catch {
+				if (!res.headersSent) {
+					res.writeHead(500, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Internal Server Error" }));
+				}
+			}
+		});
+		const maxRetries = 10;
+		const requestHandler = this.httpServer.listeners("request")[0];
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			const server = this.httpServer;
+			try {
+				await new Promise((resolve, reject) => {
+					server.listen(this.port, "127.0.0.1", () => resolve());
+					server.once("error", reject);
+				});
+				const addr = server.address();
+				if (addr && typeof addr === "object") this.port = addr.port;
+				return;
+			} catch (err) {
+				if (err instanceof Error && "code" in err && err.code === "EADDRINUSE" && attempt < maxRetries - 1) {
+					server.removeAllListeners();
+					this.httpServer = (0, node_http.createServer)(requestHandler);
+					this.port++;
+					continue;
+				}
+				throw err;
+			}
+		}
+	}
+	async stop() {
+		for (const transport of this.transports.values()) await transport.close();
+		this.transports.clear();
+		const server = this.httpServer;
+		if (server) {
+			await new Promise((resolve, reject) => {
+				server.close((err) => err ? reject(err) : resolve());
+			});
+			this.httpServer = void 0;
+		}
+	}
+	createMcpServer() {
+		const sessionId = (0, node_crypto.randomUUID)().slice(0, 8);
+		const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
+			name: "pl",
+			version: "0.1.0"
+		}, { capabilities: { tools: {} } });
+		this.registerTools(server, sessionId);
+		return server;
+	}
+	registerTools(server, sessionId) {
+		const authorId = `mcp-${sessionId}`;
+		let localVersion = 0;
+		const ctx = {
+			getMl: () => this.ml,
+			requireMl: () => this.requireMl(),
+			resolveProject: (id) => this.resolveProject(id),
+			getOpenedProject: (id) => this.getOpenedProject(id),
+			callbacks: this.callbacks,
+			getAuthorMarker: () => ({
+				authorId,
+				localVersion: ++localVersion
+			})
+		};
+		require_ping.registerPingTool(server, ctx);
+		require_connection.registerConnectionTools(server, ctx);
+		require_projects.registerProjectTools(server, ctx);
+		require_blocks.registerBlockTools(server, ctx);
+		require_block_state.registerBlockStateTools(server, ctx);
+		require_await.registerAwaitTools(server, ctx);
+		require_logs.registerLogTools(server, ctx);
+		require_data_query.registerDataQueryTools(server, ctx);
+		require_screenshot.registerScreenshotTool(server, ctx);
+		require_ui_interaction.registerUIInteractionTools(server, ctx);
+	}
+	/** Throws if MiddleLayer is not available (not connected to a server). */
+	requireMl() {
+		if (!this.ml) throw new Error("Not connected to a server. Use connect_to_server first.");
+		return this.ml;
+	}
+	/** Resolves a project from the list by its projectId (resourceIdToString format). */
+	async resolveProject(projectId) {
+		const ml = this.requireMl();
+		await ml.projectList.refreshState();
+		const entry = (await ml.projectList.awaitStableValue()).find((p) => (0, _milaboratories_pl_middle_layer.resourceIdToString)(p.rid) === projectId);
+		if (!entry) throw new Error(`Project ${projectId} not found`);
+		return entry;
+	}
+	/** Gets an opened project by projectId. Resolves via project list → rid → getOpenedProject. */
+	async getOpenedProject(projectId) {
+		const ml = this.requireMl();
+		const entry = await this.resolveProject(projectId);
+		return ml.getOpenedProject(entry.rid);
+	}
+};
+//#endregion
+exports.PlMcpServer = PlMcpServer;
+
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.cjs","names":["StreamableHTTPServerTransport","McpServer"],"sources":["../src/server.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { randomUUID } from \"node:crypto\";\nimport { type MiddleLayer, resourceIdToString } from \"@milaboratories/pl-middle-layer\";\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { ToolContext } from \"./tools/types\";\nimport { registerPingTool } from \"./tools/ping\";\nimport { registerConnectionTools } from \"./tools/connection\";\nimport { registerProjectTools } from \"./tools/projects\";\nimport { registerBlockTools } from \"./tools/blocks\";\nimport { registerBlockStateTools } from \"./tools/block-state\";\nimport { registerAwaitTools } from \"./tools/await\";\nimport { registerLogTools } from \"./tools/logs\";\nimport { registerDataQueryTools } from \"./tools/data-query\";\nimport { registerScreenshotTool } from \"./tools/screenshot\";\nimport { registerUIInteractionTools } from \"./tools/ui-interaction\";\n\nexport interface PlMcpServerCallbacks {\n  onProjectCreated?: (projectId: string) => void | Promise<void>;\n  onProjectOpened?: (projectId: string) => void | Promise<void>;\n  onProjectClosed?: (projectId: string) => void | Promise<void>;\n  onProjectDeleted?: (projectId: string) => void | Promise<void>;\n  /** Capture the current application window as a PNG screenshot. Returns base64-encoded PNG. */\n  captureScreenshot?: () => Promise<string>;\n  /** Send an input event to the application window. */\n  sendInputEvent?: (event: unknown) => Promise<void>;\n  /** Execute JavaScript in the renderer and return the result. */\n  executeJavaScript?: (code: string) => Promise<unknown>;\n  /** List available blocks from all configured registries. */\n  listAvailableBlocks?: (query?: string) => Promise<unknown[]>;\n  /** Navigate the desktop UI to show a specific block. */\n  selectBlock?: (projectId: string, blockId: string) => Promise<void>;\n  /** Read recent lines from the application log. */\n  readAppLog?: (lines: number, search?: string) => Promise<string>;\n  /** List saved server connections. */\n  listConnections?: () => Promise<ServerConnection[]>;\n  /** Connect to a server. */\n  connectToServer?: (\n    addr: string,\n    login: string,\n    password?: string,\n  ) => Promise<{ status: string; message: string }>;\n  /** Get current connection status. */\n  getConnectionStatus?: () => Promise<{\n    connected: boolean;\n    type?: string;\n    addr?: string;\n    login?: string;\n  }>;\n  /** Disconnect from current server. */\n  disconnect?: () => Promise<void>;\n  /** Get detailed info about a specific block package. */\n  getBlockInfo?: (\n    registryUrl: string,\n    organization: string,\n    name: string,\n    version: string,\n  ) => Promise<unknown>;\n}\n\nexport interface ServerConnection {\n  addr: string;\n  login: string;\n  coreVersion?: string;\n  lastConnected?: string;\n}\n\n/** Branded type for the MCP server URL secret path segment. */\nexport type McpSecret = Branded<string, \"McpSecret\">;\n\nexport interface PlMcpServerOptions {\n  /** MiddleLayer instance providing access to projects, blocks, etc. Optional — server can start without it. */\n  middleLayer?: MiddleLayer;\n  /** Port to listen on. */\n  port: number;\n  /** Secret path segment for URL security. */\n  secret: McpSecret;\n  /** Optional callbacks for project lifecycle events (e.g. to sync UI state). */\n  callbacks?: PlMcpServerCallbacks;\n}\n\nexport class PlMcpServer {\n  private ml: MiddleLayer | null;\n  private port: number;\n  private readonly secret: McpSecret;\n  private readonly callbacks: PlMcpServerCallbacks;\n  private httpServer: Server | undefined;\n  private readonly transports = new Map<string, StreamableHTTPServerTransport>();\n\n  constructor(options: PlMcpServerOptions) {\n    this.ml = options.middleLayer ?? null;\n    this.port = options.port;\n    this.secret = options.secret;\n    this.callbacks = options.callbacks ?? {};\n  }\n\n  /** Set or update the MiddleLayer instance (e.g. after connecting to a server). */\n  setMiddleLayer(ml: MiddleLayer | null | undefined) {\n    this.ml = ml ?? null;\n  }\n\n  get url(): string {\n    return `http://127.0.0.1:${this.port}/${this.secret}/mcp`;\n  }\n\n  async start(): Promise<void> {\n    if (this.httpServer) {\n      throw new Error(\"MCP server is already running\");\n    }\n\n    const expectedPath = `/${this.secret}/mcp`;\n\n    this.httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {\n      try {\n        // Origin validation — only allow localhost\n        if (req.headers.origin !== undefined) {\n          try {\n            const origin = new URL(req.headers.origin);\n            if (origin.hostname !== \"localhost\" && origin.hostname !== \"127.0.0.1\") {\n              res.writeHead(403, { \"Content-Type\": \"application/json\" });\n              res.end(JSON.stringify({ error: \"Forbidden\" }));\n              return;\n            }\n          } catch {\n            res.writeHead(403, { \"Content-Type\": \"application/json\" });\n            res.end(JSON.stringify({ error: \"Forbidden\" }));\n            return;\n          }\n        }\n\n        // Secret path check\n        if (req.url !== expectedPath) {\n          res.writeHead(404, { \"Content-Type\": \"application/json\" });\n          res.end(JSON.stringify({ error: \"Not Found\" }));\n          return;\n        }\n\n        // Route to existing session transport\n        const sessionId = req.headers[\"mcp-session-id\"] as string | undefined;\n        if (sessionId && this.transports.has(sessionId)) {\n          await this.transports.get(sessionId)!.handleRequest(req, res);\n          return;\n        }\n\n        // New session — create transport and connect MCP server\n        const transport = new StreamableHTTPServerTransport({\n          sessionIdGenerator: () => randomUUID(),\n        });\n        transport.onclose = () => {\n          const sid = transport.sessionId;\n          if (sid) this.transports.delete(sid);\n        };\n\n        const server = this.createMcpServer();\n        await server.connect(transport);\n        await transport.handleRequest(req, res);\n\n        const sid = transport.sessionId;\n        if (sid) this.transports.set(sid, transport);\n      } catch {\n        if (!res.headersSent) {\n          res.writeHead(500, { \"Content-Type\": \"application/json\" });\n          res.end(JSON.stringify({ error: \"Internal Server Error\" }));\n        }\n      }\n    });\n\n    const maxRetries = 10;\n    const requestHandler = this.httpServer.listeners(\"request\")[0] as (\n      req: IncomingMessage,\n      res: ServerResponse,\n    ) => void;\n    for (let attempt = 0; attempt < maxRetries; attempt++) {\n      const server = this.httpServer;\n      try {\n        await new Promise<void>((resolve, reject) => {\n          server.listen(this.port, \"127.0.0.1\", () => resolve());\n          server.once(\"error\", reject);\n        });\n        // Read back the actual port (important when port is 0)\n        const addr = server.address();\n        if (addr && typeof addr === \"object\") {\n          this.port = addr.port;\n        }\n        return;\n      } catch (err: unknown) {\n        if (\n          err instanceof Error &&\n          \"code\" in err &&\n          err.code === \"EADDRINUSE\" &&\n          attempt < maxRetries - 1\n        ) {\n          server.removeAllListeners();\n          this.httpServer = createServer(requestHandler);\n          this.port++;\n          continue;\n        }\n        throw err;\n      }\n    }\n  }\n\n  async stop(): Promise<void> {\n    for (const transport of this.transports.values()) {\n      await transport.close();\n    }\n    this.transports.clear();\n\n    const server = this.httpServer;\n    if (server) {\n      await new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      });\n      this.httpServer = undefined;\n    }\n  }\n\n  private createMcpServer(): McpServer {\n    const sessionId = randomUUID().slice(0, 8);\n    const server = new McpServer({ name: \"pl\", version: \"0.1.0\" }, { capabilities: { tools: {} } });\n    this.registerTools(server, sessionId);\n    return server;\n  }\n\n  private registerTools(server: McpServer, sessionId: string): void {\n    const authorId = `mcp-${sessionId}`;\n    let localVersion = 0;\n    const ctx: ToolContext = {\n      getMl: () => this.ml,\n      requireMl: () => this.requireMl(),\n      resolveProject: (id) => this.resolveProject(id),\n      getOpenedProject: (id) => this.getOpenedProject(id),\n      callbacks: this.callbacks,\n      getAuthorMarker: () => ({ authorId, localVersion: ++localVersion }),\n    };\n    registerPingTool(server, ctx);\n    registerConnectionTools(server, ctx);\n    registerProjectTools(server, ctx);\n    registerBlockTools(server, ctx);\n    registerBlockStateTools(server, ctx);\n    registerAwaitTools(server, ctx);\n    registerLogTools(server, ctx);\n    registerDataQueryTools(server, ctx);\n    registerScreenshotTool(server, ctx);\n    registerUIInteractionTools(server, ctx);\n  }\n\n  /** Throws if MiddleLayer is not available (not connected to a server). */\n  private requireMl(): MiddleLayer {\n    if (!this.ml) throw new Error(\"Not connected to a server. Use connect_to_server first.\");\n    return this.ml;\n  }\n\n  /** Resolves a project from the list by its projectId (resourceIdToString format). */\n  private async resolveProject(projectId: string) {\n    const ml = this.requireMl();\n    await ml.projectList.refreshState();\n    const projects = await ml.projectList.awaitStableValue();\n    const entry = projects.find((p) => resourceIdToString(p.rid) === projectId);\n    if (!entry) throw new Error(`Project ${projectId} not found`);\n    return entry;\n  }\n\n  /** Gets an opened project by projectId. Resolves via project list → rid → getOpenedProject. */\n  private async getOpenedProject(projectId: string) {\n    const ml = this.requireMl();\n    const entry = await this.resolveProject(projectId);\n    return ml.getOpenedProject(entry.rid);\n  }\n}\n"],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,83 @@
+import { MiddleLayer } from "@milaboratories/pl-middle-layer";
+import { Branded } from "@milaboratories/pl-model-common";
+
+//#region src/server.d.ts
+interface PlMcpServerCallbacks {
+  onProjectCreated?: (projectId: string) => void | Promise<void>;
+  onProjectOpened?: (projectId: string) => void | Promise<void>;
+  onProjectClosed?: (projectId: string) => void | Promise<void>;
+  onProjectDeleted?: (projectId: string) => void | Promise<void>;
+  /** Capture the current application window as a PNG screenshot. Returns base64-encoded PNG. */
+  captureScreenshot?: () => Promise<string>;
+  /** Send an input event to the application window. */
+  sendInputEvent?: (event: unknown) => Promise<void>;
+  /** Execute JavaScript in the renderer and return the result. */
+  executeJavaScript?: (code: string) => Promise<unknown>;
+  /** List available blocks from all configured registries. */
+  listAvailableBlocks?: (query?: string) => Promise<unknown[]>;
+  /** Navigate the desktop UI to show a specific block. */
+  selectBlock?: (projectId: string, blockId: string) => Promise<void>;
+  /** Read recent lines from the application log. */
+  readAppLog?: (lines: number, search?: string) => Promise<string>;
+  /** List saved server connections. */
+  listConnections?: () => Promise<ServerConnection[]>;
+  /** Connect to a server. */
+  connectToServer?: (addr: string, login: string, password?: string) => Promise<{
+    status: string;
+    message: string;
+  }>;
+  /** Get current connection status. */
+  getConnectionStatus?: () => Promise<{
+    connected: boolean;
+    type?: string;
+    addr?: string;
+    login?: string;
+  }>;
+  /** Disconnect from current server. */
+  disconnect?: () => Promise<void>;
+  /** Get detailed info about a specific block package. */
+  getBlockInfo?: (registryUrl: string, organization: string, name: string, version: string) => Promise<unknown>;
+}
+interface ServerConnection {
+  addr: string;
+  login: string;
+  coreVersion?: string;
+  lastConnected?: string;
+}
+/** Branded type for the MCP server URL secret path segment. */
+type McpSecret = Branded<string, "McpSecret">;
+interface PlMcpServerOptions {
+  /** MiddleLayer instance providing access to projects, blocks, etc. Optional — server can start without it. */
+  middleLayer?: MiddleLayer;
+  /** Port to listen on. */
+  port: number;
+  /** Secret path segment for URL security. */
+  secret: McpSecret;
+  /** Optional callbacks for project lifecycle events (e.g. to sync UI state). */
+  callbacks?: PlMcpServerCallbacks;
+}
+declare class PlMcpServer {
+  private ml;
+  private port;
+  private readonly secret;
+  private readonly callbacks;
+  private httpServer;
+  private readonly transports;
+  constructor(options: PlMcpServerOptions);
+  /** Set or update the MiddleLayer instance (e.g. after connecting to a server). */
+  setMiddleLayer(ml: MiddleLayer | null | undefined): void;
+  get url(): string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  private createMcpServer;
+  private registerTools;
+  /** Throws if MiddleLayer is not available (not connected to a server). */
+  private requireMl;
+  /** Resolves a project from the list by its projectId (resourceIdToString format). */
+  private resolveProject;
+  /** Gets an opened project by projectId. Resolves via project list → rid → getOpenedProject. */
+  private getOpenedProject;
+}
+//#endregion
+export { McpSecret, PlMcpServer, PlMcpServerCallbacks, PlMcpServerOptions, ServerConnection };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;UAkBiB,oBAAA;EACf,gBAAA,IAAoB,SAAA,oBAA6B,OAAA;EACjD,eAAA,IAAmB,SAAA,oBAA6B,OAAA;EAChD,eAAA,IAAmB,SAAA,oBAA6B,OAAA;EAChD,gBAAA,IAAoB,SAAA,oBAA6B,OAAA;EAHA;EAKjD,iBAAA,SAA0B,OAAA;EAHsB;EAKhD,cAAA,IAAkB,KAAA,cAAmB,OAAA;EAFX;EAI1B,iBAAA,IAAqB,IAAA,aAAiB,OAAA;EAAA;EAEtC,mBAAA,IAAuB,KAAA,cAAmB,OAAA;EAEY;EAAtD,WAAA,IAAe,SAAA,UAAmB,OAAA,aAAoB,OAAA;EAItB;EAFhC,UAAA,IAAc,KAAA,UAAe,MAAA,cAAoB,OAAA;EAQ5C;EANL,eAAA,SAAwB,OAAA,CAAQ,gBAAA;EAeb;EAbnB,eAAA,IACE,IAAA,UACA,KAAA,UACA,QAAA,cACG,OAAA;IAAU,MAAA;IAAgB,OAAA;EAAA;EAvBX;EAyBpB,mBAAA,SAA4B,OAAA;IAC1B,SAAA;IACA,IAAA;IACA,IAAA;IACA,KAAA;EAAA;EA3B8C;EA8BhD,UAAA,SAAmB,OAAA;EA7BC;EA+BpB,YAAA,IACE,WAAA,UACA,YAAA,UACA,IAAA,UACA,OAAA,aACG,OAAA;AAAA;AAAA,UAGU,gBAAA;EACf,IAAA;EACA,KAAA;EACA,WAAA;EACA,aAAA;AAAA;;KAIU,SAAA,GAAY,OAAA;AAAA,UAEP,kBAAA;EAzC2B;EA2C1C,WAAA,GAAc,WAAA;EAzCC;EA2Cf,IAAA;EA3CsD;EA6CtD,MAAA,EAAQ,SAAA;EA3CM;EA6Cd,SAAA,GAAY,oBAAA;AAAA;AAAA,cAGD,WAAA;EAAA,QACH,EAAA;EAAA,QACA,IAAA;EAAA,iBACS,MAAA;EAAA,iBACA,SAAA;EAAA,QACT,UAAA;EAAA,iBACS,UAAA;cAEL,OAAA,EAAS,kBAAA;EAhDN;EAwDf,cAAA,CAAe,EAAA,EAAI,WAAA;EAAA,IAIf,GAAA,CAAA;EAIE,KAAA,CAAA,GAAS,OAAA;EAiGT,IAAA,CAAA,GAAQ,OAAA;EAAA,QAeN,eAAA;EAAA,QAOA,aAAA;EAjLN;EAAA,QAyMM,SAAA;EAtMW;EAAA,QA4ML,cAAA;EAzMZ;EAAA,QAmNY,gBAAA;AAAA"}

package/dist/server.js

@@ -0,0 +1,171 @@
+import { registerPingTool } from "./tools/ping.js";
+import { registerConnectionTools } from "./tools/connection.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerBlockTools } from "./tools/blocks.js";
+import { registerBlockStateTools } from "./tools/block-state.js";
+import { registerAwaitTools } from "./tools/await.js";
+import { registerLogTools } from "./tools/logs.js";
+import { registerDataQueryTools } from "./tools/data-query.js";
+import { registerScreenshotTool } from "./tools/screenshot.js";
+import { registerUIInteractionTools } from "./tools/ui-interaction.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { resourceIdToString } from "@milaboratories/pl-middle-layer";
+//#region src/server.ts
+var PlMcpServer = class {
+	ml;
+	port;
+	secret;
+	callbacks;
+	httpServer;
+	transports = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.ml = options.middleLayer ?? null;
+		this.port = options.port;
+		this.secret = options.secret;
+		this.callbacks = options.callbacks ?? {};
+	}
+	/** Set or update the MiddleLayer instance (e.g. after connecting to a server). */
+	setMiddleLayer(ml) {
+		this.ml = ml ?? null;
+	}
+	get url() {
+		return `http://127.0.0.1:${this.port}/${this.secret}/mcp`;
+	}
+	async start() {
+		if (this.httpServer) throw new Error("MCP server is already running");
+		const expectedPath = `/${this.secret}/mcp`;
+		this.httpServer = createServer(async (req, res) => {
+			try {
+				if (req.headers.origin !== void 0) try {
+					const origin = new URL(req.headers.origin);
+					if (origin.hostname !== "localhost" && origin.hostname !== "127.0.0.1") {
+						res.writeHead(403, { "Content-Type": "application/json" });
+						res.end(JSON.stringify({ error: "Forbidden" }));
+						return;
+					}
+				} catch {
+					res.writeHead(403, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Forbidden" }));
+					return;
+				}
+				if (req.url !== expectedPath) {
+					res.writeHead(404, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Not Found" }));
+					return;
+				}
+				const sessionId = req.headers["mcp-session-id"];
+				if (sessionId && this.transports.has(sessionId)) {
+					await this.transports.get(sessionId).handleRequest(req, res);
+					return;
+				}
+				const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+				transport.onclose = () => {
+					const sid = transport.sessionId;
+					if (sid) this.transports.delete(sid);
+				};
+				await this.createMcpServer().connect(transport);
+				await transport.handleRequest(req, res);
+				const sid = transport.sessionId;
+				if (sid) this.transports.set(sid, transport);
+			} catch {
+				if (!res.headersSent) {
+					res.writeHead(500, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ error: "Internal Server Error" }));
+				}
+			}
+		});
+		const maxRetries = 10;
+		const requestHandler = this.httpServer.listeners("request")[0];
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			const server = this.httpServer;
+			try {
+				await new Promise((resolve, reject) => {
+					server.listen(this.port, "127.0.0.1", () => resolve());
+					server.once("error", reject);
+				});
+				const addr = server.address();
+				if (addr && typeof addr === "object") this.port = addr.port;
+				return;
+			} catch (err) {
+				if (err instanceof Error && "code" in err && err.code === "EADDRINUSE" && attempt < maxRetries - 1) {
+					server.removeAllListeners();
+					this.httpServer = createServer(requestHandler);
+					this.port++;
+					continue;
+				}
+				throw err;
+			}
+		}
+	}
+	async stop() {
+		for (const transport of this.transports.values()) await transport.close();
+		this.transports.clear();
+		const server = this.httpServer;
+		if (server) {
+			await new Promise((resolve, reject) => {
+				server.close((err) => err ? reject(err) : resolve());
+			});
+			this.httpServer = void 0;
+		}
+	}
+	createMcpServer() {
+		const sessionId = randomUUID().slice(0, 8);
+		const server = new McpServer({
+			name: "pl",
+			version: "0.1.0"
+		}, { capabilities: { tools: {} } });
+		this.registerTools(server, sessionId);
+		return server;
+	}
+	registerTools(server, sessionId) {
+		const authorId = `mcp-${sessionId}`;
+		let localVersion = 0;
+		const ctx = {
+			getMl: () => this.ml,
+			requireMl: () => this.requireMl(),
+			resolveProject: (id) => this.resolveProject(id),
+			getOpenedProject: (id) => this.getOpenedProject(id),
+			callbacks: this.callbacks,
+			getAuthorMarker: () => ({
+				authorId,
+				localVersion: ++localVersion
+			})
+		};
+		registerPingTool(server, ctx);
+		registerConnectionTools(server, ctx);
+		registerProjectTools(server, ctx);
+		registerBlockTools(server, ctx);
+		registerBlockStateTools(server, ctx);
+		registerAwaitTools(server, ctx);
+		registerLogTools(server, ctx);
+		registerDataQueryTools(server, ctx);
+		registerScreenshotTool(server, ctx);
+		registerUIInteractionTools(server, ctx);
+	}
+	/** Throws if MiddleLayer is not available (not connected to a server). */
+	requireMl() {
+		if (!this.ml) throw new Error("Not connected to a server. Use connect_to_server first.");
+		return this.ml;
+	}
+	/** Resolves a project from the list by its projectId (resourceIdToString format). */
+	async resolveProject(projectId) {
+		const ml = this.requireMl();
+		await ml.projectList.refreshState();
+		const entry = (await ml.projectList.awaitStableValue()).find((p) => resourceIdToString(p.rid) === projectId);
+		if (!entry) throw new Error(`Project ${projectId} not found`);
+		return entry;
+	}
+	/** Gets an opened project by projectId. Resolves via project list → rid → getOpenedProject. */
+	async getOpenedProject(projectId) {
+		const ml = this.requireMl();
+		const entry = await this.resolveProject(projectId);
+		return ml.getOpenedProject(entry.rid);
+	}
+};
+//#endregion
+export { PlMcpServer };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from \"node:http\";\nimport { randomUUID } from \"node:crypto\";\nimport { type MiddleLayer, resourceIdToString } from \"@milaboratories/pl-middle-layer\";\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { ToolContext } from \"./tools/types\";\nimport { registerPingTool } from \"./tools/ping\";\nimport { registerConnectionTools } from \"./tools/connection\";\nimport { registerProjectTools } from \"./tools/projects\";\nimport { registerBlockTools } from \"./tools/blocks\";\nimport { registerBlockStateTools } from \"./tools/block-state\";\nimport { registerAwaitTools } from \"./tools/await\";\nimport { registerLogTools } from \"./tools/logs\";\nimport { registerDataQueryTools } from \"./tools/data-query\";\nimport { registerScreenshotTool } from \"./tools/screenshot\";\nimport { registerUIInteractionTools } from \"./tools/ui-interaction\";\n\nexport interface PlMcpServerCallbacks {\n  onProjectCreated?: (projectId: string) => void | Promise<void>;\n  onProjectOpened?: (projectId: string) => void | Promise<void>;\n  onProjectClosed?: (projectId: string) => void | Promise<void>;\n  onProjectDeleted?: (projectId: string) => void | Promise<void>;\n  /** Capture the current application window as a PNG screenshot. Returns base64-encoded PNG. */\n  captureScreenshot?: () => Promise<string>;\n  /** Send an input event to the application window. */\n  sendInputEvent?: (event: unknown) => Promise<void>;\n  /** Execute JavaScript in the renderer and return the result. */\n  executeJavaScript?: (code: string) => Promise<unknown>;\n  /** List available blocks from all configured registries. */\n  listAvailableBlocks?: (query?: string) => Promise<unknown[]>;\n  /** Navigate the desktop UI to show a specific block. */\n  selectBlock?: (projectId: string, blockId: string) => Promise<void>;\n  /** Read recent lines from the application log. */\n  readAppLog?: (lines: number, search?: string) => Promise<string>;\n  /** List saved server connections. */\n  listConnections?: () => Promise<ServerConnection[]>;\n  /** Connect to a server. */\n  connectToServer?: (\n    addr: string,\n    login: string,\n    password?: string,\n  ) => Promise<{ status: string; message: string }>;\n  /** Get current connection status. */\n  getConnectionStatus?: () => Promise<{\n    connected: boolean;\n    type?: string;\n    addr?: string;\n    login?: string;\n  }>;\n  /** Disconnect from current server. */\n  disconnect?: () => Promise<void>;\n  /** Get detailed info about a specific block package. */\n  getBlockInfo?: (\n    registryUrl: string,\n    organization: string,\n    name: string,\n    version: string,\n  ) => Promise<unknown>;\n}\n\nexport interface ServerConnection {\n  addr: string;\n  login: string;\n  coreVersion?: string;\n  lastConnected?: string;\n}\n\n/** Branded type for the MCP server URL secret path segment. */\nexport type McpSecret = Branded<string, \"McpSecret\">;\n\nexport interface PlMcpServerOptions {\n  /** MiddleLayer instance providing access to projects, blocks, etc. Optional — server can start without it. */\n  middleLayer?: MiddleLayer;\n  /** Port to listen on. */\n  port: number;\n  /** Secret path segment for URL security. */\n  secret: McpSecret;\n  /** Optional callbacks for project lifecycle events (e.g. to sync UI state). */\n  callbacks?: PlMcpServerCallbacks;\n}\n\nexport class PlMcpServer {\n  private ml: MiddleLayer | null;\n  private port: number;\n  private readonly secret: McpSecret;\n  private readonly callbacks: PlMcpServerCallbacks;\n  private httpServer: Server | undefined;\n  private readonly transports = new Map<string, StreamableHTTPServerTransport>();\n\n  constructor(options: PlMcpServerOptions) {\n    this.ml = options.middleLayer ?? null;\n    this.port = options.port;\n    this.secret = options.secret;\n    this.callbacks = options.callbacks ?? {};\n  }\n\n  /** Set or update the MiddleLayer instance (e.g. after connecting to a server). */\n  setMiddleLayer(ml: MiddleLayer | null | undefined) {\n    this.ml = ml ?? null;\n  }\n\n  get url(): string {\n    return `http://127.0.0.1:${this.port}/${this.secret}/mcp`;\n  }\n\n  async start(): Promise<void> {\n    if (this.httpServer) {\n      throw new Error(\"MCP server is already running\");\n    }\n\n    const expectedPath = `/${this.secret}/mcp`;\n\n    this.httpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {\n      try {\n        // Origin validation — only allow localhost\n        if (req.headers.origin !== undefined) {\n          try {\n            const origin = new URL(req.headers.origin);\n            if (origin.hostname !== \"localhost\" && origin.hostname !== \"127.0.0.1\") {\n              res.writeHead(403, { \"Content-Type\": \"application/json\" });\n              res.end(JSON.stringify({ error: \"Forbidden\" }));\n              return;\n            }\n          } catch {\n            res.writeHead(403, { \"Content-Type\": \"application/json\" });\n            res.end(JSON.stringify({ error: \"Forbidden\" }));\n            return;\n          }\n        }\n\n        // Secret path check\n        if (req.url !== expectedPath) {\n          res.writeHead(404, { \"Content-Type\": \"application/json\" });\n          res.end(JSON.stringify({ error: \"Not Found\" }));\n          return;\n        }\n\n        // Route to existing session transport\n        const sessionId = req.headers[\"mcp-session-id\"] as string | undefined;\n        if (sessionId && this.transports.has(sessionId)) {\n          await this.transports.get(sessionId)!.handleRequest(req, res);\n          return;\n        }\n\n        // New session — create transport and connect MCP server\n        const transport = new StreamableHTTPServerTransport({\n          sessionIdGenerator: () => randomUUID(),\n        });\n        transport.onclose = () => {\n          const sid = transport.sessionId;\n          if (sid) this.transports.delete(sid);\n        };\n\n        const server = this.createMcpServer();\n        await server.connect(transport);\n        await transport.handleRequest(req, res);\n\n        const sid = transport.sessionId;\n        if (sid) this.transports.set(sid, transport);\n      } catch {\n        if (!res.headersSent) {\n          res.writeHead(500, { \"Content-Type\": \"application/json\" });\n          res.end(JSON.stringify({ error: \"Internal Server Error\" }));\n        }\n      }\n    });\n\n    const maxRetries = 10;\n    const requestHandler = this.httpServer.listeners(\"request\")[0] as (\n      req: IncomingMessage,\n      res: ServerResponse,\n    ) => void;\n    for (let attempt = 0; attempt < maxRetries; attempt++) {\n      const server = this.httpServer;\n      try {\n        await new Promise<void>((resolve, reject) => {\n          server.listen(this.port, \"127.0.0.1\", () => resolve());\n          server.once(\"error\", reject);\n        });\n        // Read back the actual port (important when port is 0)\n        const addr = server.address();\n        if (addr && typeof addr === \"object\") {\n          this.port = addr.port;\n        }\n        return;\n      } catch (err: unknown) {\n        if (\n          err instanceof Error &&\n          \"code\" in err &&\n          err.code === \"EADDRINUSE\" &&\n          attempt < maxRetries - 1\n        ) {\n          server.removeAllListeners();\n          this.httpServer = createServer(requestHandler);\n          this.port++;\n          continue;\n        }\n        throw err;\n      }\n    }\n  }\n\n  async stop(): Promise<void> {\n    for (const transport of this.transports.values()) {\n      await transport.close();\n    }\n    this.transports.clear();\n\n    const server = this.httpServer;\n    if (server) {\n      await new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      });\n      this.httpServer = undefined;\n    }\n  }\n\n  private createMcpServer(): McpServer {\n    const sessionId = randomUUID().slice(0, 8);\n    const server = new McpServer({ name: \"pl\", version: \"0.1.0\" }, { capabilities: { tools: {} } });\n    this.registerTools(server, sessionId);\n    return server;\n  }\n\n  private registerTools(server: McpServer, sessionId: string): void {\n    const authorId = `mcp-${sessionId}`;\n    let localVersion = 0;\n    const ctx: ToolContext = {\n      getMl: () => this.ml,\n      requireMl: () => this.requireMl(),\n      resolveProject: (id) => this.resolveProject(id),\n      getOpenedProject: (id) => this.getOpenedProject(id),\n      callbacks: this.callbacks,\n      getAuthorMarker: () => ({ authorId, localVersion: ++localVersion }),\n    };\n    registerPingTool(server, ctx);\n    registerConnectionTools(server, ctx);\n    registerProjectTools(server, ctx);\n    registerBlockTools(server, ctx);\n    registerBlockStateTools(server, ctx);\n    registerAwaitTools(server, ctx);\n    registerLogTools(server, ctx);\n    registerDataQueryTools(server, ctx);\n    registerScreenshotTool(server, ctx);\n    registerUIInteractionTools(server, ctx);\n  }\n\n  /** Throws if MiddleLayer is not available (not connected to a server). */\n  private requireMl(): MiddleLayer {\n    if (!this.ml) throw new Error(\"Not connected to a server. Use connect_to_server first.\");\n    return this.ml;\n  }\n\n  /** Resolves a project from the list by its projectId (resourceIdToString format). */\n  private async resolveProject(projectId: string) {\n    const ml = this.requireMl();\n    await ml.projectList.refreshState();\n    const projects = await ml.projectList.awaitStableValue();\n    const entry = projects.find((p) => resourceIdToString(p.rid) === projectId);\n    if (!entry) throw new Error(`Project ${projectId} not found`);\n    return entry;\n  }\n\n  /** Gets an opened project by projectId. Resolves via project list → rid → getOpenedProject. */\n  private async getOpenedProject(projectId: string) {\n    const ml = this.requireMl();\n    const entry = await this.resolveProject(projectId);\n    return ml.getOpenedProject(entry.rid);\n  }\n}\n"],"mappings":"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"}

package/dist/tools/await.cjs

@@ -0,0 +1,89 @@
+const require_types = require("./types.cjs");
+const require_tokens = require("./tokens.cjs");
+const require_sandbox = require("./sandbox.cjs");
+let _milaboratories_pl_middle_layer = require("@milaboratories/pl-middle-layer");
+let zod = require("zod");
+let _platforma_sdk_model = require("@platforma-sdk/model");
+//#region src/tools/await.ts
+function registerAwaitTools(server, ctx) {
+	server.registerTool("await_block_done", {
+		description: "Wait for a block to finish computation and outputs to stabilize. Returns block status, data, and concise output summary with token estimates. Use `transform` to extract specific data server-side on completion.",
+		inputSchema: {
+			projectId: zod.z.string().describe("Project ID"),
+			blockId: zod.z.string().describe("Block ID to wait for"),
+			timeout: zod.z.number().optional().default(12e4).describe("Timeout in ms (default 120000)"),
+			transform: zod.z.string().optional().describe("JS expression evaluated server-side when block completes. Available variables: `data` (block args), `outputs` (raw outputs), `block` (status info). Omit for default concise summary."),
+			transformTimeout: zod.z.number().optional().default(5e3).describe("Timeout in ms for transform evaluation (default 5000).")
+		}
+	}, async ({ projectId, blockId, timeout, transform, transformTimeout }) => {
+		const project = await ctx.getOpenedProject(projectId);
+		const deadline = Date.now() + timeout;
+		while (Date.now() < deadline) {
+			const overview = await project.overview.getValue();
+			if (!overview) continue;
+			const block = overview.blocks.find((b) => b.id === blockId);
+			if (!block) return require_types.errorResult(`Block ${blockId} not found in project ${projectId}.`, "Use get_project_overview to list all block IDs in this project.");
+			if (block.calculationStatus === "Limbo") return require_types.errorResult("Block entered Limbo state (upstream failed or was stopped).", "Check upstream blocks with get_project_overview. Fix or re-run the failed upstream, then retry.");
+			if (block.calculationStatus === "NotCalculated") return require_types.errorResult("Block has not been started.", "Use run_block to start it first, then call await_block_done.");
+			if (block.calculationStatus === "Done") {
+				const remaining = Math.max(deadline - Date.now(), 1e3);
+				let state;
+				try {
+					state = await project.getBlockState(blockId).awaitStableValue(AbortSignal.timeout(remaining));
+				} catch (e) {
+					if ((0, _milaboratories_pl_middle_layer.isTimeoutError)(e)) return require_types.textResult({
+						timedOut: true,
+						status: "Done",
+						note: "Computation done but outputs did not stabilize in time. Retry with a longer timeout."
+					});
+					return require_types.errorResult(`Failed to get block state: ${e instanceof Error ? e.message : String(e)}`);
+				}
+				const data = (0, _platforma_sdk_model.deriveDataFromStorage)(state.blockStorage);
+				const blockInfo = {
+					id: block.id,
+					title: block.title ?? block.label,
+					calculationStatus: block.calculationStatus,
+					canRun: block.canRun,
+					stale: block.stale,
+					outputErrors: block.outputErrors
+				};
+				if (transform) try {
+					return require_types.textResult({
+						status: "Done",
+						block: blockInfo,
+						result: await require_sandbox.safeEval(transform, {
+							data,
+							outputs: state.outputs,
+							block: blockInfo
+						}, transformTimeout)
+					});
+				} catch (e) {
+					return require_types.errorResult(`Transform failed: ${e instanceof Error ? e.message : String(e)}`, "Check your JS expression syntax. Available variables: data, outputs, block.");
+				}
+				return require_types.textResult({
+					status: "Done",
+					block: blockInfo,
+					data,
+					outputs: require_tokens.summarizeOutputs(state.outputs)
+				});
+			}
+			const pollStart = Date.now();
+			try {
+				const result = await project.overview.getFullValue();
+				await project.overview.awaitChange(AbortSignal.timeout(5e3), result.uTag);
+			} catch {}
+			const elapsed = Date.now() - pollStart;
+			if (elapsed < 500) await new Promise((r) => setTimeout(r, 500 - elapsed));
+		}
+		const block = (await project.overview.getValue())?.blocks.find((b) => b.id === blockId);
+		return require_types.textResult({
+			timedOut: true,
+			status: block?.calculationStatus ?? "Unknown",
+			hint: "The block is still running. Call await_block_done again with a longer timeout."
+		});
+	});
+}
+//#endregion
+exports.registerAwaitTools = registerAwaitTools;
+
+//# sourceMappingURL=await.cjs.map

package/dist/tools/await.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"await.cjs","names":["z","errorResult","textResult","safeEval","summarizeOutputs"],"sources":["../../src/tools/await.ts"],"sourcesContent":["import type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { isTimeoutError } from \"@milaboratories/pl-middle-layer\";\nimport { deriveDataFromStorage } from \"@platforma-sdk/model\";\nimport { z } from \"zod\";\nimport type { ToolContext } from \"./types\";\nimport { summarizeOutputs } from \"./tokens\";\nimport { safeEval } from \"./sandbox\";\nimport { errorResult, textResult } from \"./types\";\n\nexport function registerAwaitTools(server: McpServer, ctx: ToolContext): void {\n  server.registerTool(\n    \"await_block_done\",\n    {\n      description:\n        \"Wait for a block to finish computation and outputs to stabilize. \" +\n        \"Returns block status, data, and concise output summary with token estimates. \" +\n        \"Use `transform` to extract specific data server-side on completion.\",\n      inputSchema: {\n        projectId: z.string().describe(\"Project ID\"),\n        blockId: z.string().describe(\"Block ID to wait for\"),\n        timeout: z.number().optional().default(120000).describe(\"Timeout in ms (default 120000)\"),\n        transform: z\n          .string()\n          .optional()\n          .describe(\n            \"JS expression evaluated server-side when block completes. \" +\n              \"Available variables: `data` (block args), `outputs` (raw outputs), `block` (status info). \" +\n              \"Omit for default concise summary.\",\n          ),\n        transformTimeout: z\n          .number()\n          .optional()\n          .default(5000)\n          .describe(\"Timeout in ms for transform evaluation (default 5000).\"),\n      },\n    },\n    async ({ projectId, blockId, timeout, transform, transformTimeout }) => {\n      const project = await ctx.getOpenedProject(projectId);\n      const deadline = Date.now() + timeout;\n\n      while (Date.now() < deadline) {\n        const overview = await project.overview.getValue();\n        if (!overview) continue;\n        const block = overview.blocks.find((b) => b.id === blockId);\n        if (!block)\n          return errorResult(\n            `Block ${blockId} not found in project ${projectId}.`,\n            \"Use get_project_overview to list all block IDs in this project.\",\n          );\n\n        // Terminal error states — return immediately\n        if (block.calculationStatus === \"Limbo\") {\n          return errorResult(\n            \"Block entered Limbo state (upstream failed or was stopped).\",\n            \"Check upstream blocks with get_project_overview. Fix or re-run the failed upstream, then retry.\",\n          );\n        }\n\n        if (block.calculationStatus === \"NotCalculated\") {\n          return errorResult(\n            \"Block has not been started.\",\n            \"Use run_block to start it first, then call await_block_done.\",\n          );\n        }\n\n        if (block.calculationStatus === \"Done\") {\n          // Await stable block state with remaining time budget\n          const remaining = Math.max(deadline - Date.now(), 1000);\n          let state;\n          try {\n            state = await project\n              .getBlockState(blockId)\n              .awaitStableValue(AbortSignal.timeout(remaining));\n          } catch (e: unknown) {\n            if (isTimeoutError(e)) {\n              return textResult({\n                timedOut: true,\n                status: \"Done\",\n                note: \"Computation done but outputs did not stabilize in time. Retry with a longer timeout.\",\n              });\n            }\n            return errorResult(\n              `Failed to get block state: ${e instanceof Error ? e.message : String(e)}`,\n            );\n          }\n\n          const data = deriveDataFromStorage(state.blockStorage);\n\n          const blockInfo = {\n            id: block.id,\n            title: block.title ?? block.label,\n            calculationStatus: block.calculationStatus,\n            canRun: block.canRun,\n            stale: block.stale,\n            outputErrors: block.outputErrors,\n          };\n\n          if (transform) {\n            try {\n              const result = await safeEval(\n                transform,\n                {\n                  data,\n                  outputs: state.outputs,\n                  block: blockInfo,\n                },\n                transformTimeout,\n              );\n              return textResult({ status: \"Done\", block: blockInfo, result });\n            } catch (e: unknown) {\n              return errorResult(\n                `Transform failed: ${e instanceof Error ? e.message : String(e)}`,\n                \"Check your JS expression syntax. Available variables: data, outputs, block.\",\n              );\n            }\n          }\n\n          return textResult({\n            status: \"Done\",\n            block: blockInfo,\n            data,\n            outputs: summarizeOutputs(state.outputs as Record<string, unknown> | undefined),\n          });\n        }\n\n        // Still running — wait up to 5s for overview to change, then re-poll.\n        // Minimum 500ms delay to avoid busy-looping if awaitChange resolves immediately.\n        const pollStart = Date.now();\n        try {\n          const result = await project.overview.getFullValue();\n          await project.overview.awaitChange(AbortSignal.timeout(5000), result.uTag);\n        } catch {\n          // timeout or abort — just re-poll\n        }\n        const elapsed = Date.now() - pollStart;\n        if (elapsed < 500) {\n          await new Promise((r) => setTimeout(r, 500 - elapsed));\n        }\n      }\n\n      // Timed out while running\n      const overview = await project.overview.getValue();\n      const block = overview?.blocks.find((b) => b.id === blockId);\n      return textResult({\n        timedOut: true,\n        status: block?.calculationStatus ?? \"Unknown\",\n        hint: \"The block is still running. Call await_block_done again with a longer timeout.\",\n      });\n    },\n  );\n}\n"],"mappings":"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"}