@mcploom/codexec-remote 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mouaad Aallam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @mcploom/codexec-remote
+
+Transport-backed remote executor for `@mcploom/codexec`.
+
+[![npm version](https://img.shields.io/npm/v/%40mcploom%2Fcodexec--remote?style=flat-square)](https://www.npmjs.com/package/@mcploom/codexec-remote)
+[![License](https://img.shields.io/github/license/aallam/mcploom?style=flat-square)](https://github.com/aallam/mcploom/blob/main/LICENSE)
+
+## Choose `codexec-remote` When
+
+- you want codexec execution to live outside the application process
+- you already own the transport and runtime deployment shape
+- you want to keep the same `Executor` API while swapping in a stronger boundary
+
+## Install
+
+```bash
+npm install @mcploom/codexec @mcploom/codexec-remote
+```
+
+## Usage
+
+```ts
+import { resolveProvider } from "@mcploom/codexec";
+import { RemoteExecutor, attachQuickJsRemoteEndpoint } from "@mcploom/codexec-remote";
+
+const provider = resolveProvider({
+  name: "tools",
+  tools: {
+    echo: {
+      execute: async (input) => input,
+    },
+  },
+});
+
+const executor = new RemoteExecutor({
+  connectTransport: async () => myHostTransport,
+  timeoutMs: 1000,
+});
+
+const result = await executor.execute(
+  "await tools.echo({ ok: true })",
+  [provider],
+  { timeoutMs: 250 },
+);
+
+attachQuickJsRemoteEndpoint(myRunnerPort);
+```
+
+`RemoteExecutor` stays transport-agnostic. Your application owns the network stack and provides a fresh `HostTransport` per execution. `attachQuickJsRemoteEndpoint()` binds the shared QuickJS runner protocol to an app-provided remote port on the runner side.
+
+## Security Notes
+
+- This package improves the process boundary by moving execution behind a caller-supplied transport.
+- It is still not a hard security boundary by itself. Your actual trust boundary depends on the remote runtime you deploy.
+- Providers remain the capability boundary.
+- The package is intentionally small: it does not create servers, own authentication, or prescribe an HTTP/WebSocket framework.
+
+## Examples
+
+- [Remote codexec execution](https://github.com/aallam/mcploom/blob/main/examples/codexec-remote.ts)
+- [Codexec architecture overview](https://github.com/aallam/mcploom/blob/main/docs/codexec/architecture/README.md)
+- [Codexec MCP adapters and protocol](https://github.com/aallam/mcploom/blob/main/docs/codexec/architecture/codexec-mcp-and-protocol.md)

package/dist/index.cjs

@@ -0,0 +1,101 @@
+let node_crypto = require("node:crypto");
+let __mcploom_codexec_protocol = require("@mcploom/codexec-protocol");
+let __mcploom_codexec = require("@mcploom/codexec");
+let __mcploom_codexec_quickjs_runner_protocol_endpoint = require("@mcploom/codexec-quickjs/runner/protocol-endpoint");
+
+//#region src/remoteExecutor.ts
+const DEFAULT_CANCEL_GRACE_MS = 25;
+const DEFAULT_MAX_LOG_CHARS = 64e3;
+const DEFAULT_MAX_LOG_LINES = 100;
+const DEFAULT_MEMORY_LIMIT_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 5e3;
+function createRuntimeOptions(options, overrides = {}) {
+	return {
+		maxLogChars: overrides.maxLogChars ?? options.maxLogChars ?? DEFAULT_MAX_LOG_CHARS,
+		maxLogLines: overrides.maxLogLines ?? options.maxLogLines ?? DEFAULT_MAX_LOG_LINES,
+		memoryLimitBytes: overrides.memoryLimitBytes ?? options.memoryLimitBytes ?? DEFAULT_MEMORY_LIMIT_BYTES,
+		timeoutMs: overrides.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	};
+}
+/**
+* Transport-backed executor that runs guest code outside the host process.
+*/
+var RemoteExecutor = class {
+	cancelGraceMs;
+	options;
+	/**
+	* Creates a transport-backed executor with caller-supplied remote connectivity.
+	*/
+	constructor(options) {
+		this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+		this.options = options;
+	}
+	/**
+	* Executes JavaScript against the provided tool namespaces over a remote transport.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return (0, __mcploom_codexec.createTimeoutExecuteResult)();
+		let transport;
+		try {
+			transport = await this.options.connectTransport();
+		} catch (error) {
+			return {
+				durationMs: 0,
+				error: {
+					code: "internal_error",
+					message: error instanceof Error ? error.message : String(error)
+				},
+				logs: [],
+				ok: false
+			};
+		}
+		return await (0, __mcploom_codexec_protocol.runHostTransportSession)({
+			cancelGraceMs: this.cancelGraceMs,
+			code,
+			executionId: (0, node_crypto.randomUUID)(),
+			providers,
+			runtimeOptions: createRuntimeOptions(this.options, options),
+			signal: options.signal,
+			transport
+		});
+	}
+};
+
+//#endregion
+//#region src/runnerEndpoint.ts
+/**
+* Attaches the shared QuickJS protocol endpoint to a remote runner transport
+* and tears it down automatically when the transport closes or errors.
+*/
+function attachQuickJsRemoteEndpoint(port) {
+	const detachProtocol = (0, __mcploom_codexec_quickjs_runner_protocol_endpoint.attachQuickJsProtocolEndpoint)({
+		onMessage(handler) {
+			const maybeDetach = port.onMessage((message) => {
+				handler(message);
+			});
+			return () => {
+				if (typeof maybeDetach === "function") maybeDetach();
+			};
+		},
+		send(message) {
+			Promise.resolve(port.send(message)).catch(() => {});
+		}
+	});
+	const offClose = port.onClose?.(() => {
+		cleanup();
+	});
+	const offError = port.onError?.(() => {
+		cleanup();
+	});
+	function cleanup() {
+		if (typeof offClose === "function") offClose();
+		if (typeof offError === "function") offError();
+		detachProtocol();
+	}
+	return cleanup;
+}
+
+//#endregion
+exports.RemoteExecutor = RemoteExecutor;
+exports.attachQuickJsRemoteEndpoint = attachQuickJsRemoteEndpoint;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["transport: HostTransport"],"sources":["../src/remoteExecutor.ts","../src/runnerEndpoint.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport {\n  runHostTransportSession,\n  type HostTransport,\n  type ExecutorRuntimeOptions,\n} from \"@mcploom/codexec-protocol\";\nimport {\n  createTimeoutExecuteResult,\n  type ExecutionOptions,\n  type ExecuteResult,\n  type Executor,\n  type ResolvedToolProvider,\n} from \"@mcploom/codexec\";\n\nimport type { RemoteExecutorOptions } from \"./types\";\n\nconst DEFAULT_CANCEL_GRACE_MS = 25;\nconst DEFAULT_MAX_LOG_CHARS = 64_000;\nconst DEFAULT_MAX_LOG_LINES = 100;\nconst DEFAULT_MEMORY_LIMIT_BYTES = 64 * 1024 * 1024;\nconst DEFAULT_TIMEOUT_MS = 5000;\n\nfunction createRuntimeOptions(\n  options: RemoteExecutorOptions,\n  overrides: ExecutionOptions = {},\n): Required<ExecutorRuntimeOptions> {\n  return {\n    maxLogChars:\n      overrides.maxLogChars ?? options.maxLogChars ?? DEFAULT_MAX_LOG_CHARS,\n    maxLogLines:\n      overrides.maxLogLines ?? options.maxLogLines ?? DEFAULT_MAX_LOG_LINES,\n    memoryLimitBytes:\n      overrides.memoryLimitBytes ??\n      options.memoryLimitBytes ??\n      DEFAULT_MEMORY_LIMIT_BYTES,\n    timeoutMs: overrides.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n  };\n}\n\n/**\n * Transport-backed executor that runs guest code outside the host process.\n */\nexport class RemoteExecutor implements Executor {\n  private readonly cancelGraceMs: number;\n  private readonly options: RemoteExecutorOptions;\n\n  /**\n   * Creates a transport-backed executor with caller-supplied remote connectivity.\n   */\n  constructor(options: RemoteExecutorOptions) {\n    this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;\n    this.options = options;\n  }\n\n  /**\n   * Executes JavaScript against the provided tool namespaces over a remote transport.\n   */\n  async execute(\n    code: string,\n    providers: ResolvedToolProvider[],\n    options: ExecutionOptions = {},\n  ): Promise<ExecuteResult> {\n    if (options.signal?.aborted) {\n      return createTimeoutExecuteResult();\n    }\n\n    let transport: HostTransport;\n\n    try {\n      transport = await this.options.connectTransport();\n    } catch (error) {\n      return {\n        durationMs: 0,\n        error: {\n          code: \"internal_error\",\n          message: error instanceof Error ? error.message : String(error),\n        },\n        logs: [],\n        ok: false,\n      };\n    }\n\n    return await runHostTransportSession({\n      cancelGraceMs: this.cancelGraceMs,\n      code,\n      executionId: randomUUID(),\n      providers,\n      runtimeOptions: createRuntimeOptions(this.options, options),\n      signal: options.signal,\n      transport,\n    });\n  }\n}\n","import { attachQuickJsProtocolEndpoint } from \"@mcploom/codexec-quickjs/runner/protocol-endpoint\";\nimport type {\n  DispatcherMessage,\n  RunnerMessage,\n} from \"@mcploom/codexec-protocol\";\n\nimport type { RemoteRunnerPort } from \"./types\";\n\n/**\n * Attaches the shared QuickJS protocol endpoint to a remote runner transport\n * and tears it down automatically when the transport closes or errors.\n */\nexport function attachQuickJsRemoteEndpoint(port: RemoteRunnerPort): () => void {\n  const detachProtocol = attachQuickJsProtocolEndpoint({\n    onMessage(handler: (message: DispatcherMessage) => void): () => void {\n      const maybeDetach = port.onMessage((message: unknown) => {\n        handler(message as DispatcherMessage);\n      });\n\n      return () => {\n        if (typeof maybeDetach === \"function\") {\n          maybeDetach();\n        }\n      };\n    },\n    send(message: RunnerMessage): void {\n      void Promise.resolve(port.send(message)).catch(() => {});\n    },\n  });\n\n  const offClose = port.onClose?.(() => {\n    cleanup();\n  });\n  const offError = port.onError?.(() => {\n    cleanup();\n  });\n\n  function cleanup(): void {\n    if (typeof offClose === \"function\") {\n      offClose();\n    }\n    if (typeof offError === \"function\") {\n      offError();\n    }\n    detachProtocol();\n  }\n\n  return cleanup;\n}\n"],"mappings":";;;;;;AAiBA,MAAM,0BAA0B;AAChC,MAAM,wBAAwB;AAC9B,MAAM,wBAAwB;AAC9B,MAAM,6BAA6B,KAAK,OAAO;AAC/C,MAAM,qBAAqB;AAE3B,SAAS,qBACP,SACA,YAA8B,EAAE,EACE;AAClC,QAAO;EACL,aACE,UAAU,eAAe,QAAQ,eAAe;EAClD,aACE,UAAU,eAAe,QAAQ,eAAe;EAClD,kBACE,UAAU,oBACV,QAAQ,oBACR;EACF,WAAW,UAAU,aAAa,QAAQ,aAAa;EACxD;;;;;AAMH,IAAa,iBAAb,MAAgD;CAC9C,AAAiB;CACjB,AAAiB;;;;CAKjB,YAAY,SAAgC;AAC1C,OAAK,gBAAgB,QAAQ,iBAAiB;AAC9C,OAAK,UAAU;;;;;CAMjB,MAAM,QACJ,MACA,WACA,UAA4B,EAAE,EACN;AACxB,MAAI,QAAQ,QAAQ,QAClB,2DAAmC;EAGrC,IAAIA;AAEJ,MAAI;AACF,eAAY,MAAM,KAAK,QAAQ,kBAAkB;WAC1C,OAAO;AACd,UAAO;IACL,YAAY;IACZ,OAAO;KACL,MAAM;KACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;KAChE;IACD,MAAM,EAAE;IACR,IAAI;IACL;;AAGH,SAAO,8DAA8B;GACnC,eAAe,KAAK;GACpB;GACA,0CAAyB;GACzB;GACA,gBAAgB,qBAAqB,KAAK,SAAS,QAAQ;GAC3D,QAAQ,QAAQ;GAChB;GACD,CAAC;;;;;;;;;;AC/EN,SAAgB,4BAA4B,MAAoC;CAC9E,MAAM,uGAA+C;EACnD,UAAU,SAA2D;GACnE,MAAM,cAAc,KAAK,WAAW,YAAqB;AACvD,YAAQ,QAA6B;KACrC;AAEF,gBAAa;AACX,QAAI,OAAO,gBAAgB,WACzB,cAAa;;;EAInB,KAAK,SAA8B;AACjC,GAAK,QAAQ,QAAQ,KAAK,KAAK,QAAQ,CAAC,CAAC,YAAY,GAAG;;EAE3D,CAAC;CAEF,MAAM,WAAW,KAAK,gBAAgB;AACpC,WAAS;GACT;CACF,MAAM,WAAW,KAAK,gBAAgB;AACpC,WAAS;GACT;CAEF,SAAS,UAAgB;AACvB,MAAI,OAAO,aAAa,WACtB,WAAU;AAEZ,MAAI,OAAO,aAAa,WACtB,WAAU;AAEZ,kBAAgB;;AAGlB,QAAO"}

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+import { ExecuteResult, ExecutionOptions, Executor, ExecutorRuntimeOptions, ResolvedToolProvider } from "@mcploom/codexec";
+import { HostTransport, TransportCloseReason } from "@mcploom/codexec-protocol";
+
+//#region src/types.d.ts
+
+/**
+ * Factory that creates a fresh transport connection for one remote execution.
+ */
+type RemoteTransportFactory = () => HostTransport | Promise<HostTransport>;
+/**
+ * Minimal runner-side port for transport-backed QuickJS execution.
+ */
+interface RemoteRunnerPort {
+  onClose?(handler: (reason?: TransportCloseReason) => void): void | (() => void);
+  onError?(handler: (error: Error) => void): void | (() => void);
+  onMessage(handler: (message: unknown) => void): void | (() => void);
+  send(message: unknown): void | Promise<void>;
+}
+/**
+ * Options for constructing a {@link RemoteExecutor}.
+ */
+interface RemoteExecutorOptions extends ExecutorRuntimeOptions {
+  cancelGraceMs?: number;
+  connectTransport: RemoteTransportFactory;
+}
+//#endregion
+//#region src/remoteExecutor.d.ts
+/**
+ * Transport-backed executor that runs guest code outside the host process.
+ */
+declare class RemoteExecutor implements Executor {
+  private readonly cancelGraceMs;
+  private readonly options;
+  /**
+   * Creates a transport-backed executor with caller-supplied remote connectivity.
+   */
+  constructor(options: RemoteExecutorOptions);
+  /**
+   * Executes JavaScript against the provided tool namespaces over a remote transport.
+   */
+  execute(code: string, providers: ResolvedToolProvider[], options?: ExecutionOptions): Promise<ExecuteResult>;
+}
+//#endregion
+//#region src/runnerEndpoint.d.ts
+/**
+ * Attaches the shared QuickJS protocol endpoint to a remote runner transport
+ * and tears it down automatically when the transport closes or errors.
+ */
+declare function attachQuickJsRemoteEndpoint(port: RemoteRunnerPort): () => void;
+//#endregion
+export { RemoteExecutor, type RemoteExecutorOptions, type RemoteRunnerPort, type RemoteTransportFactory, attachQuickJsRemoteEndpoint };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/remoteExecutor.ts","../src/runnerEndpoint.ts"],"sourcesContent":[],"mappings":";;;;;;;AAMA;AACI,KADQ,sBAAA,GACR,GAAA,GAAA,aAAA,GACA,OADA,CACQ,aADR,CAAA;;;;AAMa,UAAA,gBAAA,CAAgB;EACH,OAAA,EAAA,OAAA,EAAA,CAAA,MAAA,CAAA,EAAA,oBAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EACF,OAAA,EAAA,OAAA,EAAA,CAAA,KAAA,EAAA,KAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EAEK,SAAA,CAAA,OAAA,EAAA,CAAA,OAAA,EAAA,OAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EAAO,IAAA,CAAA,OAAA,EAAA,OAAA,CAAA,EAAA,IAAA,GAAP,OAAO,CAAA,IAAA,CAAA;AAMxC;;;;ACoBa,UDpBI,qBAAA,SAA8B,sBCoBnB,CAAA;EAOL,aAAA,CAAA,EAAA,MAAA;EAUR,gBAAA,EDnCK,sBCmCL;;;;;;ADtDf;AACI,cCoCS,cAAA,YAA0B,QDpCnC,CAAA;EACQ,iBAAA,aAAA;EAAR,iBAAA,OAAA;EAAO;AAKX;;EAE4B,WAAA,CAAA,OAAA,ECmCL,qBDnCK;EAEK;;AAMjC;mCCqCe,kCACF,mBACR,QAAQ;;;;;;;ADxDb;AACI,iBEKY,2BAAA,CFLZ,IAAA,EEK8C,gBFL9C,CAAA,EAAA,GAAA,GAAA,IAAA"}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { HostTransport, TransportCloseReason } from "@mcploom/codexec-protocol";
+import { ExecuteResult, ExecutionOptions, Executor, ExecutorRuntimeOptions, ResolvedToolProvider } from "@mcploom/codexec";
+
+//#region src/types.d.ts
+
+/**
+ * Factory that creates a fresh transport connection for one remote execution.
+ */
+type RemoteTransportFactory = () => HostTransport | Promise<HostTransport>;
+/**
+ * Minimal runner-side port for transport-backed QuickJS execution.
+ */
+interface RemoteRunnerPort {
+  onClose?(handler: (reason?: TransportCloseReason) => void): void | (() => void);
+  onError?(handler: (error: Error) => void): void | (() => void);
+  onMessage(handler: (message: unknown) => void): void | (() => void);
+  send(message: unknown): void | Promise<void>;
+}
+/**
+ * Options for constructing a {@link RemoteExecutor}.
+ */
+interface RemoteExecutorOptions extends ExecutorRuntimeOptions {
+  cancelGraceMs?: number;
+  connectTransport: RemoteTransportFactory;
+}
+//#endregion
+//#region src/remoteExecutor.d.ts
+/**
+ * Transport-backed executor that runs guest code outside the host process.
+ */
+declare class RemoteExecutor implements Executor {
+  private readonly cancelGraceMs;
+  private readonly options;
+  /**
+   * Creates a transport-backed executor with caller-supplied remote connectivity.
+   */
+  constructor(options: RemoteExecutorOptions);
+  /**
+   * Executes JavaScript against the provided tool namespaces over a remote transport.
+   */
+  execute(code: string, providers: ResolvedToolProvider[], options?: ExecutionOptions): Promise<ExecuteResult>;
+}
+//#endregion
+//#region src/runnerEndpoint.d.ts
+/**
+ * Attaches the shared QuickJS protocol endpoint to a remote runner transport
+ * and tears it down automatically when the transport closes or errors.
+ */
+declare function attachQuickJsRemoteEndpoint(port: RemoteRunnerPort): () => void;
+//#endregion
+export { RemoteExecutor, type RemoteExecutorOptions, type RemoteRunnerPort, type RemoteTransportFactory, attachQuickJsRemoteEndpoint };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/remoteExecutor.ts","../src/runnerEndpoint.ts"],"sourcesContent":[],"mappings":";;;;;;;AAMA;AACI,KADQ,sBAAA,GACR,GAAA,GAAA,aAAA,GACA,OADA,CACQ,aADR,CAAA;;;;AAMa,UAAA,gBAAA,CAAgB;EACH,OAAA,EAAA,OAAA,EAAA,CAAA,MAAA,CAAA,EAAA,oBAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EACF,OAAA,EAAA,OAAA,EAAA,CAAA,KAAA,EAAA,KAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EAEK,SAAA,CAAA,OAAA,EAAA,CAAA,OAAA,EAAA,OAAA,EAAA,GAAA,IAAA,CAAA,EAAA,IAAA,GAAA,CAAA,GAAA,GAAA,IAAA,CAAA;EAAO,IAAA,CAAA,OAAA,EAAA,OAAA,CAAA,EAAA,IAAA,GAAP,OAAO,CAAA,IAAA,CAAA;AAMxC;;;;ACoBa,UDpBI,qBAAA,SAA8B,sBCoBnB,CAAA;EAOL,aAAA,CAAA,EAAA,MAAA;EAUR,gBAAA,EDnCK,sBCmCL;;;;;;ADtDf;AACI,cCoCS,cAAA,YAA0B,QDpCnC,CAAA;EACQ,iBAAA,aAAA;EAAR,iBAAA,OAAA;EAAO;AAKX;;EAE4B,WAAA,CAAA,OAAA,ECmCL,qBDnCK;EAEK;;AAMjC;mCCqCe,kCACF,mBACR,QAAQ;;;;;;;ADxDb;AACI,iBEKY,2BAAA,CFLZ,IAAA,EEK8C,gBFL9C,CAAA,EAAA,GAAA,GAAA,IAAA"}

package/dist/index.js

@@ -0,0 +1,100 @@
+import { randomUUID } from "node:crypto";
+import { runHostTransportSession } from "@mcploom/codexec-protocol";
+import { createTimeoutExecuteResult } from "@mcploom/codexec";
+import { attachQuickJsProtocolEndpoint } from "@mcploom/codexec-quickjs/runner/protocol-endpoint";
+
+//#region src/remoteExecutor.ts
+const DEFAULT_CANCEL_GRACE_MS = 25;
+const DEFAULT_MAX_LOG_CHARS = 64e3;
+const DEFAULT_MAX_LOG_LINES = 100;
+const DEFAULT_MEMORY_LIMIT_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 5e3;
+function createRuntimeOptions(options, overrides = {}) {
+	return {
+		maxLogChars: overrides.maxLogChars ?? options.maxLogChars ?? DEFAULT_MAX_LOG_CHARS,
+		maxLogLines: overrides.maxLogLines ?? options.maxLogLines ?? DEFAULT_MAX_LOG_LINES,
+		memoryLimitBytes: overrides.memoryLimitBytes ?? options.memoryLimitBytes ?? DEFAULT_MEMORY_LIMIT_BYTES,
+		timeoutMs: overrides.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	};
+}
+/**
+* Transport-backed executor that runs guest code outside the host process.
+*/
+var RemoteExecutor = class {
+	cancelGraceMs;
+	options;
+	/**
+	* Creates a transport-backed executor with caller-supplied remote connectivity.
+	*/
+	constructor(options) {
+		this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
+		this.options = options;
+	}
+	/**
+	* Executes JavaScript against the provided tool namespaces over a remote transport.
+	*/
+	async execute(code, providers, options = {}) {
+		if (options.signal?.aborted) return createTimeoutExecuteResult();
+		let transport;
+		try {
+			transport = await this.options.connectTransport();
+		} catch (error) {
+			return {
+				durationMs: 0,
+				error: {
+					code: "internal_error",
+					message: error instanceof Error ? error.message : String(error)
+				},
+				logs: [],
+				ok: false
+			};
+		}
+		return await runHostTransportSession({
+			cancelGraceMs: this.cancelGraceMs,
+			code,
+			executionId: randomUUID(),
+			providers,
+			runtimeOptions: createRuntimeOptions(this.options, options),
+			signal: options.signal,
+			transport
+		});
+	}
+};
+
+//#endregion
+//#region src/runnerEndpoint.ts
+/**
+* Attaches the shared QuickJS protocol endpoint to a remote runner transport
+* and tears it down automatically when the transport closes or errors.
+*/
+function attachQuickJsRemoteEndpoint(port) {
+	const detachProtocol = attachQuickJsProtocolEndpoint({
+		onMessage(handler) {
+			const maybeDetach = port.onMessage((message) => {
+				handler(message);
+			});
+			return () => {
+				if (typeof maybeDetach === "function") maybeDetach();
+			};
+		},
+		send(message) {
+			Promise.resolve(port.send(message)).catch(() => {});
+		}
+	});
+	const offClose = port.onClose?.(() => {
+		cleanup();
+	});
+	const offError = port.onError?.(() => {
+		cleanup();
+	});
+	function cleanup() {
+		if (typeof offClose === "function") offClose();
+		if (typeof offError === "function") offError();
+		detachProtocol();
+	}
+	return cleanup;
+}
+
+//#endregion
+export { RemoteExecutor, attachQuickJsRemoteEndpoint };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["transport: HostTransport"],"sources":["../src/remoteExecutor.ts","../src/runnerEndpoint.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport {\n  runHostTransportSession,\n  type HostTransport,\n  type ExecutorRuntimeOptions,\n} from \"@mcploom/codexec-protocol\";\nimport {\n  createTimeoutExecuteResult,\n  type ExecutionOptions,\n  type ExecuteResult,\n  type Executor,\n  type ResolvedToolProvider,\n} from \"@mcploom/codexec\";\n\nimport type { RemoteExecutorOptions } from \"./types\";\n\nconst DEFAULT_CANCEL_GRACE_MS = 25;\nconst DEFAULT_MAX_LOG_CHARS = 64_000;\nconst DEFAULT_MAX_LOG_LINES = 100;\nconst DEFAULT_MEMORY_LIMIT_BYTES = 64 * 1024 * 1024;\nconst DEFAULT_TIMEOUT_MS = 5000;\n\nfunction createRuntimeOptions(\n  options: RemoteExecutorOptions,\n  overrides: ExecutionOptions = {},\n): Required<ExecutorRuntimeOptions> {\n  return {\n    maxLogChars:\n      overrides.maxLogChars ?? options.maxLogChars ?? DEFAULT_MAX_LOG_CHARS,\n    maxLogLines:\n      overrides.maxLogLines ?? options.maxLogLines ?? DEFAULT_MAX_LOG_LINES,\n    memoryLimitBytes:\n      overrides.memoryLimitBytes ??\n      options.memoryLimitBytes ??\n      DEFAULT_MEMORY_LIMIT_BYTES,\n    timeoutMs: overrides.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n  };\n}\n\n/**\n * Transport-backed executor that runs guest code outside the host process.\n */\nexport class RemoteExecutor implements Executor {\n  private readonly cancelGraceMs: number;\n  private readonly options: RemoteExecutorOptions;\n\n  /**\n   * Creates a transport-backed executor with caller-supplied remote connectivity.\n   */\n  constructor(options: RemoteExecutorOptions) {\n    this.cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;\n    this.options = options;\n  }\n\n  /**\n   * Executes JavaScript against the provided tool namespaces over a remote transport.\n   */\n  async execute(\n    code: string,\n    providers: ResolvedToolProvider[],\n    options: ExecutionOptions = {},\n  ): Promise<ExecuteResult> {\n    if (options.signal?.aborted) {\n      return createTimeoutExecuteResult();\n    }\n\n    let transport: HostTransport;\n\n    try {\n      transport = await this.options.connectTransport();\n    } catch (error) {\n      return {\n        durationMs: 0,\n        error: {\n          code: \"internal_error\",\n          message: error instanceof Error ? error.message : String(error),\n        },\n        logs: [],\n        ok: false,\n      };\n    }\n\n    return await runHostTransportSession({\n      cancelGraceMs: this.cancelGraceMs,\n      code,\n      executionId: randomUUID(),\n      providers,\n      runtimeOptions: createRuntimeOptions(this.options, options),\n      signal: options.signal,\n      transport,\n    });\n  }\n}\n","import { attachQuickJsProtocolEndpoint } from \"@mcploom/codexec-quickjs/runner/protocol-endpoint\";\nimport type {\n  DispatcherMessage,\n  RunnerMessage,\n} from \"@mcploom/codexec-protocol\";\n\nimport type { RemoteRunnerPort } from \"./types\";\n\n/**\n * Attaches the shared QuickJS protocol endpoint to a remote runner transport\n * and tears it down automatically when the transport closes or errors.\n */\nexport function attachQuickJsRemoteEndpoint(port: RemoteRunnerPort): () => void {\n  const detachProtocol = attachQuickJsProtocolEndpoint({\n    onMessage(handler: (message: DispatcherMessage) => void): () => void {\n      const maybeDetach = port.onMessage((message: unknown) => {\n        handler(message as DispatcherMessage);\n      });\n\n      return () => {\n        if (typeof maybeDetach === \"function\") {\n          maybeDetach();\n        }\n      };\n    },\n    send(message: RunnerMessage): void {\n      void Promise.resolve(port.send(message)).catch(() => {});\n    },\n  });\n\n  const offClose = port.onClose?.(() => {\n    cleanup();\n  });\n  const offError = port.onError?.(() => {\n    cleanup();\n  });\n\n  function cleanup(): void {\n    if (typeof offClose === \"function\") {\n      offClose();\n    }\n    if (typeof offError === \"function\") {\n      offError();\n    }\n    detachProtocol();\n  }\n\n  return cleanup;\n}\n"],"mappings":";;;;;;AAiBA,MAAM,0BAA0B;AAChC,MAAM,wBAAwB;AAC9B,MAAM,wBAAwB;AAC9B,MAAM,6BAA6B,KAAK,OAAO;AAC/C,MAAM,qBAAqB;AAE3B,SAAS,qBACP,SACA,YAA8B,EAAE,EACE;AAClC,QAAO;EACL,aACE,UAAU,eAAe,QAAQ,eAAe;EAClD,aACE,UAAU,eAAe,QAAQ,eAAe;EAClD,kBACE,UAAU,oBACV,QAAQ,oBACR;EACF,WAAW,UAAU,aAAa,QAAQ,aAAa;EACxD;;;;;AAMH,IAAa,iBAAb,MAAgD;CAC9C,AAAiB;CACjB,AAAiB;;;;CAKjB,YAAY,SAAgC;AAC1C,OAAK,gBAAgB,QAAQ,iBAAiB;AAC9C,OAAK,UAAU;;;;;CAMjB,MAAM,QACJ,MACA,WACA,UAA4B,EAAE,EACN;AACxB,MAAI,QAAQ,QAAQ,QAClB,QAAO,4BAA4B;EAGrC,IAAIA;AAEJ,MAAI;AACF,eAAY,MAAM,KAAK,QAAQ,kBAAkB;WAC1C,OAAO;AACd,UAAO;IACL,YAAY;IACZ,OAAO;KACL,MAAM;KACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;KAChE;IACD,MAAM,EAAE;IACR,IAAI;IACL;;AAGH,SAAO,MAAM,wBAAwB;GACnC,eAAe,KAAK;GACpB;GACA,aAAa,YAAY;GACzB;GACA,gBAAgB,qBAAqB,KAAK,SAAS,QAAQ;GAC3D,QAAQ,QAAQ;GAChB;GACD,CAAC;;;;;;;;;;AC/EN,SAAgB,4BAA4B,MAAoC;CAC9E,MAAM,iBAAiB,8BAA8B;EACnD,UAAU,SAA2D;GACnE,MAAM,cAAc,KAAK,WAAW,YAAqB;AACvD,YAAQ,QAA6B;KACrC;AAEF,gBAAa;AACX,QAAI,OAAO,gBAAgB,WACzB,cAAa;;;EAInB,KAAK,SAA8B;AACjC,GAAK,QAAQ,QAAQ,KAAK,KAAK,QAAQ,CAAC,CAAC,YAAY,GAAG;;EAE3D,CAAC;CAEF,MAAM,WAAW,KAAK,gBAAgB;AACpC,WAAS;GACT;CACF,MAAM,WAAW,KAAK,gBAAgB;AACpC,WAAS;GACT;CAEF,SAAS,UAAgB;AACvB,MAAI,OAAO,aAAa,WACtB,WAAU;AAEZ,MAAI,OAAO,aAAa,WACtB,WAAU;AAEZ,kBAAgB;;AAGlB,QAAO"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mcploom/codexec-remote",
+  "version": "0.1.1",
+  "description": "Transport-backed remote executor for the mcploom codexec core package.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "remote",
+    "sandbox",
+    "code-execution"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aallam/mcploom.git",
+    "directory": "packages/codexec-remote"
+  },
+  "homepage": "https://github.com/aallam/mcploom/tree/main/packages/codexec-remote#readme",
+  "bugs": "https://github.com/aallam/mcploom/issues",
+  "dependencies": {
+    "@mcploom/codexec": "^0.3.0",
+    "@mcploom/codexec-protocol": "^0.1.1",
+    "@mcploom/codexec-quickjs": "^0.2.0"
+  }
+}