@agent-sh/agent-workspace-linux 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @agent-sh/agent-workspace-linux
+
+npm distribution wrapper for the [`agent-workspace-linux`](https://github.com/agent-sh/agent-workspace-linux) MCP server — isolated Linux desktop workspaces for AI agents.
+
+## Installation
+
+```sh
+npm install -g @agent-sh/agent-workspace-linux
+```
+
+The installer automatically downloads the prebuilt binary for your architecture from the matching [GitHub Release](https://github.com/agent-sh/agent-workspace-linux/releases).
+
+**Linux only.** `x64` (x86_64) and `arm64` (aarch64) are supported.
+
+> **Note — `--ignore-scripts`:** package managers that skip lifecycle scripts (e.g. `pnpm` with `ignore-scripts=true`, some CI setups) will not download the binary automatically. Run the postinstall manually to recover:
+> ```sh
+> node $(npm root -g)/@agent-sh/agent-workspace-linux/scripts/postinstall.js
+> ```
+
+## Usage
+
+Once installed, the server is on your PATH (the command stays unscoped):
+
+```sh
+agent-workspace-linux
+```
+
+It is an [MCP](https://modelcontextprotocol.io/) server that speaks JSON-RPC over stdio. Wire it into your MCP client config, e.g. for Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "agent-workspace-linux": {
+      "command": "agent-workspace-linux",
+      "args": []
+    }
+  }
+}
+```
+
+## Source and full documentation
+
+All source code, tool documentation, and issue tracking are at:
+**<https://github.com/agent-sh/agent-workspace-linux>**
+
+## License
+
+MIT

package/bin/agent-workspace-linux.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// agent-workspace-linux.js — thin launcher for the native MCP server binary.
+//
+// Why a JS launcher instead of pointing `bin` directly at the native binary?
+// - npm resolves `bin` entries from the tarball at install time; the downloaded
+//   binary is placed there by postinstall, which runs AFTER npm creates shims.
+//   Pointing `bin` at the native binary directly is therefore unreliable across
+//   npm versions and install modes.
+// - The JS shim is always present in the tarball, so npm can always create the
+//   global shim. At runtime the shim locates the native binary relative to its
+//   own __dirname and execs it.
+//
+// This pattern mirrors what esbuild, @swc/core, and rollup use for their own
+// native binaries published via npm.
+//
+// Signal handling: SIGINT is ignored in this parent process so the child MCP
+// server handles Ctrl-C itself without the shell printing a double ^C.
+
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const binaryPath = path.join(__dirname, "agent-workspace-linux");
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    "agent-workspace-linux: native binary not found at " + binaryPath + "\n" +
+    "The binary is downloaded during installation (postinstall). " +
+    "If --ignore-scripts was used, run:\n" +
+    "  node " + path.join(__dirname, "..", "scripts", "postinstall.js")
+  );
+  process.exit(1);
+}
+
+// Ignore SIGINT in the launcher: let the child (MCP server) handle its own
+// shutdown. Without this both processes would receive the signal and the child
+// might not get a chance to flush stdio cleanly.
+process.on("SIGINT", () => {});
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  // Detach false (default): child shares the session, gets signals from tty.
+});
+
+child.on("close", (code, signal) => {
+  if (signal) {
+    // Propagate signal so the parent's exit looks like a signalled death to
+    // any caller (e.g. npm run scripts that check $?).
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+child.on("error", (err) => {
+  console.error("agent-workspace-linux: failed to start binary —", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@agent-sh/agent-workspace-linux",
+  "version": "0.1.0",
+  "description": "Isolated Linux desktop workspaces for AI agents — MCP server binary wrapper.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agent-sh/agent-workspace-linux.git",
+    "directory": "npm"
+  },
+  "homepage": "https://github.com/agent-sh/agent-workspace-linux#readme",
+  "bugs": {
+    "url": "https://github.com/agent-sh/agent-workspace-linux/issues"
+  },
+  "keywords": [
+    "mcp",
+    "linux",
+    "desktop",
+    "automation",
+    "workspace",
+    "agent"
+  ],
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agent-workspace-linux": "bin/agent-workspace-linux.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/agent-workspace-linux.js",
+    "scripts/postinstall.js",
+    "README.md"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// postinstall.js — downloads the matching prebuilt binary from GitHub Releases.
+//
+// Invoked automatically by npm after `npm install -g @agent-sh/agent-workspace-linux`.
+// If --ignore-scripts was used (e.g. pnpm default, some CI setups) this script
+// will NOT run; the binary won't be present and the launcher will print a clear
+// error at runtime. To recover, re-run installation with scripts enabled or
+// invoke this file directly: `node node_modules/@agent-sh/agent-workspace-linux/scripts/postinstall.js`
+//
+// Checksum verification is not wired in because the release workflow contract
+// does not publish .sha256 sidecar files. If that changes, add a step here that
+// downloads <asset>.sha256 and verifies it against the tmp file before rename.
+
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+// ── Platform / arch guard ────────────────────────────────────────────────────
+
+if (process.platform !== "linux") {
+  console.error(
+    `agent-workspace-linux: unsupported platform "${process.platform}". ` +
+      "This package only works on Linux."
+  );
+  process.exit(1);
+}
+
+const ARCH_MAP = {
+  x64: "x86_64-unknown-linux-gnu",
+  arm64: "aarch64-unknown-linux-gnu",
+};
+
+const rustTarget = ARCH_MAP[process.arch];
+if (!rustTarget) {
+  console.error(
+    `agent-workspace-linux: unsupported CPU architecture "${process.arch}". ` +
+      `Supported: ${Object.keys(ARCH_MAP).join(", ")}.`
+  );
+  process.exit(1);
+}
+
+// ── Paths ────────────────────────────────────────────────────────────────────
+
+const pkg = require("../package.json");
+const version = pkg.version; // e.g. "0.1.0"
+const assetName = `agent-workspace-linux-${rustTarget}`;
+const downloadUrl =
+  `https://github.com/agent-sh/agent-workspace-linux/releases/download/` +
+  `v${version}/${assetName}`;
+
+const binDir = path.join(__dirname, "..", "bin");
+const destPath = path.join(binDir, "agent-workspace-linux");
+const tmpPath = destPath + ".tmp";
+
+// ── Download helper (follows redirects, max 5 hops) ─────────────────────────
+
+/**
+ * Download `url` to `tmpFile`, following up to `maxRedirects` 3xx responses.
+ * Resolves when the file is fully written, rejects on error or bad status.
+ */
+function download(url, tmpFile, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    function get(currentUrl, hopsLeft) {
+      https
+        .get(currentUrl, { headers: { "User-Agent": "node-fetch/postinstall" } }, (res) => {
+          const { statusCode, headers } = res;
+
+          // Follow redirects (GitHub releases always redirect to S3).
+          if (statusCode >= 300 && statusCode < 400 && headers.location) {
+            if (hopsLeft === 0) {
+              res.resume();
+              return reject(new Error(`Too many redirects downloading ${url}`));
+            }
+            res.resume(); // drain and ignore body
+            return get(headers.location, hopsLeft - 1);
+          }
+
+          if (statusCode !== 200) {
+            res.resume();
+            return reject(
+              new Error(
+                `Failed to download ${url}: HTTP ${statusCode}. ` +
+                  "Check that the release exists and the version in package.json matches."
+              )
+            );
+          }
+
+          const out = fs.createWriteStream(tmpFile);
+          res.pipe(out);
+          out.on("finish", () => out.close(resolve));
+          out.on("error", (err) => {
+            fs.unlink(tmpFile, () => {}); // best-effort cleanup
+            reject(err);
+          });
+          res.on("error", (err) => {
+            fs.unlink(tmpFile, () => {});
+            reject(err);
+          });
+        })
+        .on("error", (err) => {
+          fs.unlink(tmpFile, () => {});
+          reject(err);
+        });
+    }
+
+    get(url, maxRedirects);
+  });
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+(async () => {
+  // Ensure bin/ directory exists (it should, tracked by git via .gitkeep, but
+  // be defensive for edge-case installs).
+  fs.mkdirSync(binDir, { recursive: true });
+
+  // Remove stale tmp file from a previous interrupted install.
+  try {
+    fs.unlinkSync(tmpPath);
+  } catch (_) {}
+
+  console.log(
+    `agent-workspace-linux: downloading ${assetName} v${version}…`
+  );
+  console.log(`  URL: ${downloadUrl}`);
+
+  try {
+    await download(downloadUrl, tmpPath);
+  } catch (err) {
+    // Clean up in case the file was partially created.
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_) {}
+    console.error(`\nagent-workspace-linux: download failed — ${err.message}`);
+    process.exit(1);
+  }
+
+  // Atomic rename: avoids leaving a half-written binary.
+  try {
+    fs.renameSync(tmpPath, destPath);
+  } catch (err) {
+    console.error(
+      `agent-workspace-linux: could not move binary into place — ${err.message}`
+    );
+    process.exit(1);
+  }
+
+  // Mark executable.
+  try {
+    fs.chmodSync(destPath, 0o755);
+  } catch (err) {
+    console.error(
+      `agent-workspace-linux: chmod failed — ${err.message}. ` +
+        `Try: chmod 755 ${destPath}`
+    );
+    process.exit(1);
+  }
+
+  console.log(`agent-workspace-linux: binary installed at ${destPath}`);
+})();