@xelexis/x-broker 0.0.0-stage → 0.9.2

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @xelexis/x-broker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`npx` launcher for `asb-client`, the local MCP client of the Agent Session Broker. The package contains the prebuilt `asb-client` 0.9.2 for every supported platform (about 15 MB to download, 38 MB installed, no install scripts); the launcher starts the one for this computer and passes all arguments, standard input and output through unchanged.
+
+Supported: macOS Apple Silicon and Intel, Linux x64, Windows x64. Node.js 18 or later and npm are required. Other platforms, including Linux ARM64, are not supported.
+
+## MCP configuration
+
+Pin the version to match your broker server, so the first start does not resolve a different release.
+
+`.mcp.json` (Claude Code, macOS/Linux):
+
+```json
+{
+  "mcpServers": {
+    "x-broker": {
+      "command": "npx",
+      "args": ["-y", "@xelexis/x-broker@0.9.2", "--broker-url", "https://broker.example/mcp?project=brk", "--token", "<project token>"]
+    }
+  }
+}
+```
+
+`.codex/config.toml` (Codex, macOS/Linux):
+
+```toml
+[mcp_servers.x-broker]
+command = "npx"
+args = ["-y", "@xelexis/x-broker@0.9.2", "--broker-url", "https://broker.example/mcp?project=brk", "--token", "<project token>"]
+```
+
+On Windows use `"command": "cmd"` and put `"/c", "npx"` before the other arguments. The first start downloads the package; if your MCP host times out, run `npx -y @xelexis/x-broker@0.9.2 --version` once beforehand or install it with `npm install -g @xelexis/x-broker@0.9.2` and use `x-broker` as the command.
+
+`x-broker --help` shows the client options. Session credentials are kept in the client's usual user configuration directory, independent of the npm cache.

package/bin/x-broker.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+
+// npm launcher for asb-client. It writes nothing to stdout (the MCP stdio
+// channel) and relays stdin/stdout through pipes rather than inheriting them:
+// if this process is killed, the client's stdin closes and it exits on EOF
+// instead of outliving its host. Diagnostics go to stderr only.
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const binaries = {
+  "darwin-arm64": "asb-client",
+  "darwin-x64": "asb-client",
+  "linux-x64": "asb-client",
+  "win32-x64": "asb-client.exe",
+};
+
+// Every supported client is bundled under bin/<platform>/ next to this file.
+function binaryPath({ platform = process.platform, arch = process.arch, dir = __dirname } = {}) {
+  const key = `${platform}-${arch}`;
+  if (!Object.hasOwn(binaries, key)) {
+    throw new Error(`unsupported platform ${key}; supported: ${Object.keys(binaries).join(", ")}`);
+  }
+  return path.join(dir, key, binaries[key]);
+}
+
+// A missing or non-executable client means a damaged installation; say so
+// before spawning so stdout stays empty.
+function checkBinary(file) {
+  const { name, version } = require("../package.json");
+  const reinstall = `reinstall ${name}@${version}`;
+  if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`${file} is missing; ${reinstall}`);
+  if (process.platform !== "win32") {
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+    } catch {
+      throw new Error(`${file} is not executable; ${reinstall}`);
+    }
+  }
+}
+
+function main() {
+  let file;
+  try {
+    file = binaryPath();
+    checkBinary(file);
+  } catch (err) {
+    process.stderr.write(`x-broker: ${err.message}\n`);
+    process.exit(1);
+  }
+  const child = spawn(file, process.argv.slice(2), { stdio: ["pipe", "pipe", "inherit"], windowsHide: true });
+  const signals = process.platform === "win32" ? ["SIGINT", "SIGTERM", "SIGBREAK"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+  const forward = (signal) => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  };
+  for (const signal of signals) process.on(signal, forward);
+
+  process.stdin.pipe(child.stdin);
+  child.stdout.pipe(process.stdout, { end: false });
+  // The client may exit before reading everything, and the host may close
+  // our stdout; neither is a launcher error.
+  child.stdin.on("error", () => {});
+  process.stdout.on("error", () => forward("SIGTERM"));
+
+  child.on("error", (err) => {
+    process.stderr.write(`x-broker: cannot start ${file}: ${err.message}\n`);
+    process.exit(1);
+  });
+  child.on("close", (code, signal) => {
+    process.stdin.unpipe(child.stdin);
+    process.stdin.destroy();
+    for (const s of signals) process.removeListener(s, forward);
+    // Flush relayed output before mirroring the client's exit.
+    process.stdout.write("", () => {
+      if (signal) process.kill(process.pid, signal);
+      process.exit(code ?? 1);
+    });
+  });
+}
+
+if (require.main === module) main();
+module.exports = { binaryPath };

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@xelexis/x-broker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.2",
+  "description": "npx launcher and bundled clients for the Agent Session Broker MCP client (asb-client)",
+  "bin": {
+    "x-broker": "bin/x-broker.js"
+  },
+  "files": [
+    "bin/x-broker.js",
+    "bin/darwin-arm64/asb-client",
+    "bin/darwin-x64/asb-client",
+    "bin/linux-x64/asb-client",
+    "bin/win32-x64/asb-client.exe"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xelexis-dev/agent-session-broker-deploy.git"
+  },
+  "homepage": "https://github.com/xelexis-dev/agent-session-broker-deploy#readme",
+  "bugs": {
+    "url": "https://github.com/xelexis-dev/agent-session-broker-deploy#readme"
+  },
+  "xBrokerClientInputs": "sha256:ac0be4608711eb30a44cd12c1d748671c4edf1b489e704bd3e09a34c402b308c"
+}