@webority/ensemble 0.0.1

package/README.md

@@ -0,0 +1,41 @@
+# @webority/ensemble
+
+Connect a machine to your [Ensemble](https://ensemble.host) control plane. Installs the local **agent
+runner** (runs your AI coding sessions, appears in your fleet) and wires **ensemble-bus** into your
+coding CLIs so your sessions message each other — all **scoped to your organization**.
+
+## Install & enrol
+Get an **enrollment token** from the portal → *Connect Runner*, then:
+
+```sh
+npm i -g @webority/ensemble
+ensemble enroll --token <ENROLLMENT_TOKEN>
+```
+
+Or one line (no npm knowledge needed):
+
+```sh
+curl -fsSL https://ensemble.host/install.sh | sh -s -- --token <ENROLLMENT_TOKEN>
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://ensemble.host/install.ps1 | iex   # then: ensemble enroll --token <TOKEN>
+```
+
+`enroll` exchanges your enrollment token for a **per-machine token** (revocable individually from the
+portal), downloads + configures + auto-starts the runner, and wires the bus into whichever of
+`claude` / `codex` / `grok` / `gemini` / `opencode` it finds. **Your subscription logins never leave
+your machine** — the server only ever sees a machine token.
+
+## Commands
+- `ensemble enroll --token <t> [--api <url>] [--name <machine>]`
+- `ensemble status` — connection + your org's live session mailboxes
+- `ensemble hooks` — re-wire the bus after installing a new coding CLI
+
+## Security model
+Machine ⇄ server auth is a **per-machine token**, resolved server-side to your organization; every
+row is tenant-isolated by a global query filter, so no machine can reach another org's data. The
+runner dials **outbound only** (no inbound port). Revoke any machine — or the enrollment token — from
+the portal at any time.

package/bin/ensemble.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+'use strict';
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const core = require('../lib/core');
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const v = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      args[k] = v;
+    } else args._.push(a);
+  }
+  return args;
+}
+
+async function enroll(args) {
+  const token = args.token || process.env.ENSEMBLE_ENROLL_TOKEN;
+  if (!token) core.die('missing --token <enrollment-token> — get it from your Ensemble portal → Connect Runner');
+  const api = args.api || core.DEFAULT_API;
+  const name = args.name || os.hostname();
+  core.log('Ensemble — enrolling "' + name + '" with ' + api);
+  core.log('• fetching runner + bus binaries');
+  const { runnerPath } = await core.ensureBinaries();
+  core.log('• exchanging enrollment token for a per-machine token');
+  const machineToken = await core.enrollMachine(api, token, name);
+  core.writeRunnerConfig(api, machineToken);
+  const wired = core.wireHooks();
+  core.log('• wired session hooks: ' + (wired.join(', ') || '(no supported coding CLI found — run `ensemble hooks` after installing claude/codex/grok)'));
+  core.log('• installing auto-start + launching the runner');
+  core.installAutostart(runnerPath);
+  core.startRunner(runnerPath);
+  core.log('\n✓ Enrolled. This machine runs your Ensemble runner and its coding sessions now share the bus (scoped to your org).');
+  core.log('  Open a NEW terminal (so ENSEMBLE_MACHINE_TOKEN loads), then start Claude/Codex/Grok as usual.');
+}
+
+async function status(args) {
+  const api = args.api || core.DEFAULT_API;
+  const tokenFile = path.join(core.ENSEMBLE_DIR, 'machine-token');
+  if (!fs.existsSync(tokenFile)) return core.log('not enrolled — run: ensemble enroll --token <token>');
+  const t = fs.readFileSync(tokenFile, 'utf8').trim();
+  const res = await core.request('GET', api.replace(/\/$/, '') + '/api/bus/who', { 'X-Ensemble-Machine-Token': t });
+  if (res.status === 200) {
+    const mbx = JSON.parse(res.body);
+    core.log('✓ connected to ' + api + ' — your org has ' + mbx.length + ' mailbox(es):');
+    mbx.slice(0, 25).forEach((m) => core.log('   ' + m.name + '  (' + m.engine + ')'));
+  } else {
+    core.log('✗ machine token not accepted (HTTP ' + res.status + ') — re-enroll with a fresh enrollment token.');
+  }
+}
+
+function usage() {
+  core.log(
+`ensemble — connect this machine to your Ensemble control plane
+
+  ensemble enroll --token <enrollment-token> [--api <url>] [--name <machine>]
+        download + enrol the runner, wire session hooks, and start it
+  ensemble status         show connection + your org's live session mailboxes
+  ensemble hooks          (re)wire ensemble-bus into installed coding CLIs
+  ensemble version
+
+Get your enrollment token from the Ensemble portal → Connect Runner.`);
+}
+
+(async () => {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const args = parseArgs(argv.slice(1));
+  try {
+    if (cmd === 'enroll') await enroll(args);
+    else if (cmd === 'status') await status(args);
+    else if (cmd === 'hooks') { await core.ensureBinaries(); core.log('wired: ' + (core.wireHooks().join(', ') || 'none')); }
+    else if (cmd === 'version' || cmd === '--version' || cmd === '-v') core.log(require('../package.json').version);
+    else usage();
+  } catch (e) {
+    core.die(e && e.message ? e.message : String(e));
+  }
+})();

package/lib/core.js

@@ -0,0 +1,237 @@
+'use strict';
+// Core logic for the `ensemble` CLI — zero runtime deps (Node built-ins only), cross-platform.
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { spawn, spawnSync } = require('child_process');
+
+const HOME = os.homedir();
+const ENSEMBLE_DIR = path.join(HOME, '.ensemble');
+const BIN_DIR = path.join(ENSEMBLE_DIR, 'bin');
+const RUNNER_DIR = path.join(ENSEMBLE_DIR, 'runner');
+const DEFAULT_API = process.env.ENSEMBLE_API || 'https://api.ensemble.host';
+// Public host for the prebuilt binaries (runner + bus). Overridable for testing.
+const DL_BASE = process.env.ENSEMBLE_DL_BASE || 'https://ensembledl.blob.core.windows.net/cli';
+
+function log(msg) { process.stdout.write(msg + '\n'); }
+function warn(msg) { process.stderr.write(msg + '\n'); }
+function die(msg) { warn('ensemble: ' + msg); process.exit(1); }
+
+function platform() {
+  const p = process.platform, a = process.arch;
+  if (p === 'win32') return { key: 'win-x64', exe: '.exe', os: 'windows' };
+  if (p === 'darwin') return { key: a === 'arm64' ? 'osx-arm64' : 'osx-x64', exe: '', os: 'mac' };
+  return { key: a === 'arm64' ? 'linux-arm64' : 'linux-x64', exe: '', os: 'linux' };
+}
+
+function ensureDirs() {
+  for (const d of [ENSEMBLE_DIR, BIN_DIR, RUNNER_DIR]) fs.mkdirSync(d, { recursive: true });
+}
+
+// --- HTTP helpers ---
+function request(method, url, headers, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const req = https.request(u, { method, headers }, (res) => {
+      let data = '';
+      res.on('data', (c) => (data += c));
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    });
+    req.on('error', reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+function downloadTo(url, dest) {
+  return new Promise((resolve, reject) => {
+    const doGet = (u, redirects) => {
+      https.get(u, (res) => {
+        if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirects < 5) {
+          res.resume();
+          return doGet(res.headers.location, redirects + 1);
+        }
+        if (res.statusCode !== 200) { res.resume(); return reject(new Error('HTTP ' + res.statusCode + ' for ' + u)); }
+        const tmp = dest + '.download';
+        const out = fs.createWriteStream(tmp);
+        res.pipe(out);
+        out.on('finish', () => out.close(() => { fs.renameSync(tmp, dest); resolve(); }));
+        out.on('error', reject);
+      }).on('error', reject);
+    };
+    doGet(url, 0);
+  });
+}
+
+async function ensureBinaries() {
+  ensureDirs();
+  const pf = platform();
+  const busPath = path.join(BIN_DIR, 'ensemble-bus' + pf.exe);
+  const runnerPath = path.join(RUNNER_DIR, 'Ensemble.Runner' + pf.exe);
+  const targets = [
+    { name: 'ensemble-bus-' + pf.key + pf.exe, dest: busPath },
+    { name: 'ensemble-runner-' + pf.key + pf.exe, dest: runnerPath },
+  ];
+  for (const t of targets) {
+    if (fs.existsSync(t.dest) && fs.statSync(t.dest).size > 0) continue;
+    log('  downloading ' + t.name + ' …');
+    await downloadTo(DL_BASE + '/' + t.name, t.dest);
+    if (pf.os !== 'windows') {
+      fs.chmodSync(t.dest, 0o755);
+      // macOS requires at least an ad-hoc signature to run an unsigned binary.
+      if (pf.os === 'mac') spawnSync('codesign', ['-s', '-', '-f', t.dest], { stdio: 'ignore' });
+    }
+  }
+  return { busPath, runnerPath, pf };
+}
+
+// --- enrollment: exchange the enrollment token for a per-machine runner token ---
+async function enrollMachine(api, enrollToken, name) {
+  const res = await request('POST', api.replace(/\/$/, '') + '/api/runner-tokens/enroll',
+    { 'X-Ensemble-Machine-Token': enrollToken, 'Content-Type': 'application/json' },
+    JSON.stringify({ name }));
+  if (res.status === 401) throw new Error('enrollment token was rejected (invalid or revoked).');
+  if (res.status !== 200) throw new Error('enroll failed: HTTP ' + res.status + ' ' + res.body);
+  const token = JSON.parse(res.body).token;
+  if (!token) throw new Error('enroll returned no token');
+  return token;
+}
+
+function writeRunnerConfig(api, machineToken) {
+  ensureDirs();
+  const hubUrl = api.replace(/\/$/, '') + '/hubs/runner';
+  const cfg = {
+    Logging: { LogLevel: { Default: 'Information', 'Microsoft.Hosting.Lifetime': 'Information' } },
+    Ensemble: { HubUrl: hubUrl, MachineToken: machineToken },
+  };
+  fs.writeFileSync(path.join(RUNNER_DIR, 'appsettings.json'), JSON.stringify(cfg, null, 2));
+  // ensemble-bus reads ENSEMBLE_MACHINE_TOKEN from env — persist it to the shell rc + a dotfile.
+  fs.writeFileSync(path.join(ENSEMBLE_DIR, 'machine-token'), machineToken, { mode: 0o600 });
+  const pf = platform();
+  if (pf.os === 'windows') {
+    spawnSync('setx', ['ENSEMBLE_MACHINE_TOKEN', machineToken], { stdio: 'ignore' });
+  }
+  const rc = path.join(HOME, pf.os === 'mac' ? '.zshrc' : '.bashrc');
+  try {
+    let cur = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
+    cur = cur.replace(/\nexport ENSEMBLE_MACHINE_TOKEN=.*\n?/g, '\n');
+    if (!cur.endsWith('\n')) cur += '\n';
+    cur += `export ENSEMBLE_MACHINE_TOKEN="${machineToken}"\n`;
+    if (!/\.ensemble\/bin/.test(cur)) cur += `export PATH="$HOME/.ensemble/bin:$PATH"\n`;
+    fs.writeFileSync(rc, cur);
+  } catch (e) { /* best-effort */ }
+}
+
+// --- wire ensemble-bus into each installed harness's session hooks ---
+function wireHooks() {
+  const pf = platform();
+  const busExe = path.join(BIN_DIR, 'ensemble-bus' + pf.exe);
+  const busInvoke = pf.os === 'windows' ? busExe.replace(/\\/g, '\\\\') : busExe;
+  const wired = [];
+
+  // Claude Code — settings.json hooks
+  const claudeSettings = path.join(HOME, '.claude', 'settings.json');
+  if (has('claude')) { mergeClaudeHooks(claudeSettings, busInvoke); wired.push('claude'); }
+
+  // Codex — ~/.codex/hooks.json
+  if (has('codex')) { writeEngineHooks(path.join(HOME, '.codex', 'hooks.json'), busInvoke, 'codex'); wired.push('codex'); }
+  // Grok — ~/.grok/hooks/agent-bus.json
+  if (has('grok')) { writeEngineHooks(path.join(HOME, '.grok', 'hooks', 'agent-bus.json'), busInvoke, 'grok'); wired.push('grok'); }
+  // Gemini / OpenCode — best-effort (same hook shape if the engine supports lifecycle hooks)
+  if (has('gemini')) wired.push('gemini(detected)');
+  if (has('opencode')) wired.push('opencode(detected)');
+  return wired;
+}
+
+function has(cmd) {
+  const pf = platform();
+  const which = pf.os === 'windows' ? spawnSync('where', [cmd], { stdio: 'ignore' }) : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return which.status === 0;
+}
+
+function writeEngineHooks(file, busInvoke, engine) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const hook = (ev) => `"${busInvoke}" hook ${ev} --engine ${engine}`;
+  const cfg = {
+    hooks: {
+      'session-start': hook('session-start'),
+      'user-prompt': hook('user-prompt'),
+      'stop': hook('stop'),
+      'session-end': hook('session-end'),
+    },
+  };
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+}
+
+function mergeClaudeHooks(file, busInvoke) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let s = {};
+  try { if (fs.existsSync(file)) s = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { s = {}; }
+  s.hooks = s.hooks || {};
+  const cmd = (ev) => ({ hooks: [{ type: 'command', command: `"${busInvoke}" hook ${ev} --engine claude 2>/dev/null || true` }] });
+  s.hooks.SessionStart = [cmd('session-start')];
+  s.hooks.UserPromptSubmit = [cmd('user-prompt')];
+  s.hooks.Stop = [cmd('stop')];
+  s.hooks.SessionEnd = [cmd('session-end')];
+  fs.writeFileSync(file, JSON.stringify(s, null, 2));
+}
+
+// --- per-user auto-start of the runner (per OS), plus start it now ---
+function installAutostart(runnerPath) {
+  const pf = platform();
+  if (pf.os === 'windows') {
+    const startup = path.join(process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming'),
+      'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+    fs.mkdirSync(startup, { recursive: true });
+    const vbs = path.join(RUNNER_DIR, 'run-hidden.vbs');
+    fs.writeFileSync(vbs,
+      `Set sh = CreateObject("WScript.Shell")\r\nsh.CurrentDirectory = "${RUNNER_DIR}"\r\nsh.Run """${runnerPath}""", 0, False\r\n`);
+    fs.copyFileSync(vbs, path.join(startup, 'EnsembleRunner.vbs'));
+  } else if (pf.os === 'mac') {
+    const plist = path.join(HOME, 'Library', 'LaunchAgents', 'host.ensemble.runner.plist');
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist,
+`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>host.ensemble.runner</string>
+  <key>ProgramArguments</key><array><string>${runnerPath}</string></array>
+  <key>WorkingDirectory</key><string>${RUNNER_DIR}</string>
+  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${path.join(RUNNER_DIR, 'runner.log')}</string>
+  <key>StandardErrorPath</key><string>${path.join(RUNNER_DIR, 'runner.log')}</string>
+</dict></plist>`);
+    spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' });
+    spawnSync('launchctl', ['load', plist], { stdio: 'ignore' });
+  } else {
+    const unitDir = path.join(HOME, '.config', 'systemd', 'user');
+    fs.mkdirSync(unitDir, { recursive: true });
+    fs.writeFileSync(path.join(unitDir, 'ensemble-runner.service'),
+`[Unit]
+Description=Ensemble runner daemon
+After=network-online.target
+[Service]
+WorkingDirectory=${RUNNER_DIR}
+ExecStart=${runnerPath}
+Restart=always
+RestartSec=5
+[Install]
+WantedBy=default.target`);
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+    spawnSync('systemctl', ['--user', 'enable', '--now', 'ensemble-runner.service'], { stdio: 'ignore' });
+    spawnSync('loginctl', ['enable-linger', os.userInfo().username], { stdio: 'ignore' });
+  }
+}
+
+function startRunner(runnerPath) {
+  const pf = platform();
+  if (pf.os === 'mac' || pf.os === 'linux') return; // launchd/systemd already started it
+  const child = spawn(runnerPath, [], { cwd: RUNNER_DIR, detached: true, stdio: 'ignore', env: { ...process.env, DOTNET_ENVIRONMENT: 'Production' } });
+  child.unref();
+}
+
+module.exports = {
+  log, warn, die, platform, DEFAULT_API, ENSEMBLE_DIR, RUNNER_DIR, BIN_DIR,
+  ensureBinaries, enrollMachine, writeRunnerConfig, wireHooks, installAutostart, startRunner, request,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@webority/ensemble",
+  "version": "0.0.1",
+  "description": "Connect this machine to your Ensemble control plane — runs the local agent runner and wires the ensemble-bus session bus so your coding sessions talk (per-org, isolated).",
+  "bin": {
+    "ensemble": "bin/ensemble.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "ensemble",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "control-plane",
+    "agent-runner"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Webority/ensemble.git",
+    "directory": "Ensemble.Cli"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}