agentcontroll 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Control contributors
+
+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

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# agentcontroll
+
+**Local-first control plane for coding agents (Antigravity, Claude Code, Codex, Devin CLI)**
+
+`agentcontroll` manages, sandboxes, switches between, and monitors autonomous coding agents inside full-fidelity terminal sessions with hardware-isolated account profiles and zero-configuration launch flows.
+
+## Quick Start
+
+You can run AgentControll without manual compilation using `npx`:
+
+```bash
+npx agentcontroll
+```
+
+Or install it globally:
+
+```bash
+npm install -g agentcontroll
+agentcontroll
+```
+
+On first execution, the runner detects your host operating system and CPU architecture, downloads the matching prebuilt release binary, and invokes the terminal interface with transparent signal and stdio forwarding.
+
+## Commands
+
+The package includes the standard suite of commands:
+
+```bash
+# Launch the interactive terminal UI
+agentcontroll
+
+# Shorthand alias
+ac
+
+# Launch or switch Antigravity (agy) agent sessions directly
+agy
+
+# Inspect daemon state or start the background control daemon
+agentcontrold --help
+```
+
+## Supported Systems
+
+- **Linux x86_64** (glibc 2.31+)
+- **macOS x86_64** (Intel)
+- **macOS aarch64** (Apple Silicon)
+- **Windows**: Run natively inside [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (`npx agentcontroll`)
+
+## License
+
+MIT © AgentControll contributors. See [LICENSE](https://github.com/vijaygovindBiju/AgentControll/blob/main/LICENSE) for details.
 
-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.

package/bin/ac.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runBinary } = require('../lib/runner');
+runBinary('ac');

package/bin/agent-control.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runBinary } = require('../lib/runner');
+runBinary('agentcontroll');

package/bin/agentcontrold.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runBinary } = require('../lib/runner');
+runBinary('agentcontrold');

package/bin/agentcontroll.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runBinary } = require('../lib/runner');
+runBinary('agentcontroll');

package/bin/agy.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runBinary } = require('../lib/runner');
+runBinary('agy');

package/lib/downloader.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const http = require('http');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const { getTargetTriple, getArchiveName } = require('./platform');
+
+const VERSION = require('../package.json').version;
+const GITHUB_REPO = 'vijaygovindBiju/AgentControll';
+
+/**
+ * Returns the directory where AgentControll binaries are cached.
+ */
+function getCacheDir(version = VERSION) {
+  const baseCache = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(baseCache, 'agentcontrol', 'bin', `v${version}`);
+}
+
+/**
+ * HTTP GET request helper that follows redirects.
+ */
+function downloadFile(url, destPath, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects < 0) {
+      return reject(new Error(`Too many redirects when downloading ${url}`));
+    }
+
+    const client = url.startsWith('https:') ? https : http;
+    const req = client.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        const redirectUrl = new URL(res.headers.location, url).toString();
+        res.resume(); // Drain stream
+        return resolve(downloadFile(redirectUrl, destPath, maxRedirects - 1));
+      }
+
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`Download failed with HTTP status ${res.statusCode} from ${url}`));
+      }
+
+      const fileStream = fs.createWriteStream(destPath);
+      res.pipe(fileStream);
+
+      fileStream.on('finish', () => {
+        fileStream.close(resolve);
+      });
+
+      fileStream.on('error', (err) => {
+        fs.unlink(destPath, () => {});
+        reject(err);
+      });
+    });
+
+    req.on('error', (err) => {
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Calculates SHA256 checksum of a file.
+ */
+function getFileSha256(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('data', (data) => hash.update(data));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+/**
+ * Ensures the binary exists and is executable.
+ * Downloads from GitHub releases if not already cached.
+ *
+ * @param {string} binaryName Name of the binary (e.g. 'agentcontroll', 'agent-control', 'agentcontrold', 'agy', 'ac')
+ * @returns {Promise<string>} Absolute path to the executable binary
+ */
+async function ensureBinary(binaryName = 'agentcontroll') {
+  // 1. Check AGENTCONTROL_BIN_DIR override (useful for dev or custom installations)
+  if (process.env.AGENTCONTROL_BIN_DIR) {
+    const overridePath = path.join(process.env.AGENTCONTROL_BIN_DIR, binaryName);
+    if (fs.existsSync(overridePath)) {
+      return overridePath;
+    }
+  }
+
+  // 2. Check local cache directory
+  const cacheDir = getCacheDir(VERSION);
+  const binaryPath = path.join(cacheDir, binaryName);
+
+  if (fs.existsSync(binaryPath)) {
+    try {
+      fs.accessSync(binaryPath, fs.constants.X_OK);
+      return binaryPath;
+    } catch {
+      // If not executable, make it executable
+      fs.chmodSync(binaryPath, 0o755);
+      return binaryPath;
+    }
+  }
+
+  // 3. Need to download archive
+  const targetTriple = getTargetTriple();
+  const archiveName = getArchiveName(VERSION, targetTriple);
+  const baseUrl = process.env.AGENTCONTROL_DOWNLOAD_URL_BASE ||
+    `https://github.com/${GITHUB_REPO}/releases/download/v${VERSION}`;
+  const archiveUrl = `${baseUrl}/${archiveName}`;
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const tempArchive = path.join(cacheDir, `${archiveName}.tmp`);
+
+  process.stderr.write(`[agentcontroll] Downloading AgentControll v${VERSION} for ${targetTriple}...\n`);
+
+  try {
+    await downloadFile(archiveUrl, tempArchive);
+
+    // Extract using system tar
+    process.stderr.write(`[agentcontroll] Extracting binary archive...\n`);
+    execFileSync('tar', ['-xzf', tempArchive, '-C', cacheDir]);
+
+    // Ensure permissions
+    const binaries = ['agentcontroll', 'agent-control', 'agentcontrold', 'agy', 'ac'];
+    for (const bin of binaries) {
+      const p = path.join(cacheDir, bin);
+      if (fs.existsSync(p)) {
+        fs.chmodSync(p, 0o755);
+      }
+    }
+
+    // Clean up temporary archive
+    try {
+      fs.unlinkSync(tempArchive);
+    } catch {}
+
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Expected binary '${binaryName}' was not found in downloaded release archive.`);
+    }
+
+    process.stderr.write(`[agentcontroll] Ready.\n`);
+    return binaryPath;
+  } catch (err) {
+    try {
+      if (fs.existsSync(tempArchive)) fs.unlinkSync(tempArchive);
+    } catch {}
+    throw new Error(
+      `Failed to download prebuilt AgentControll binary from ${archiveUrl}:\n${err.message}\n` +
+      `You can build from source using 'cargo build --release' or set AGENTCONTROL_BIN_DIR.`
+    );
+  }
+}
+
+module.exports = {
+  getCacheDir,
+  downloadFile,
+  getFileSha256,
+  ensureBinary,
+};

package/lib/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const platform = require('./platform');
+const downloader = require('./downloader');
+const runner = require('./runner');
+
+module.exports = {
+  ...platform,
+  ...downloader,
+  ...runner,
+};

package/lib/platform.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const os = require('os');
+
+/**
+ * Supported release targets and their mapping to GitHub Release archives.
+ */
+const SUPPORTED_TARGETS = {
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+};
+
+/**
+ * Returns the target triple for the current system, or throws a helpful error.
+ */
+function getTargetTriple() {
+  const platform = process.env.AGENTCONTROL_PLATFORM || os.platform();
+  const arch = process.env.AGENTCONTROL_ARCH || os.arch();
+
+  if (platform === 'win32') {
+    throw new Error(
+      'AgentControll requires POSIX Unix domain sockets (mode 0600) and native terminal signals.\n' +
+      'Windows users should run AgentControll inside WSL2 (Windows Subsystem for Linux):\n' +
+      '  wsl --install\n' +
+      'Inside WSL2, run: npx agentcontroll'
+    );
+  }
+
+  const key = `${platform}-${arch}`;
+  const target = SUPPORTED_TARGETS[key];
+
+  if (!target) {
+    throw new Error(
+      `Unsupported platform/architecture: ${platform}-${arch}.\n` +
+      `AgentControll currently provides prebuilt binaries for:\n` +
+      Object.keys(SUPPORTED_TARGETS).map(k => `  - ${k}`).join('\n') +
+      `\nTo build from source on your platform, run: cargo build --release`
+    );
+  }
+
+  return target;
+}
+
+/**
+ * Returns the release archive name for a given version and target triple.
+ */
+function getArchiveName(version, target) {
+  return `agentcontroll-v${version}-${target}.tar.gz`;
+}
+
+
+module.exports = {
+  SUPPORTED_TARGETS,
+  getTargetTriple,
+  getArchiveName,
+};

package/lib/runner.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const { ensureBinary } = require('./downloader');
+
+/**
+ * Executes a target AgentControll binary, forwarding arguments, stdio, and signals.
+ *
+ * @param {string} binaryName Name of the binary to run ('agentcontroll', 'agy', etc.)
+ */
+async function runBinary(binaryName) {
+  try {
+    const binaryPath = await ensureBinary(binaryName);
+
+    const child = spawn(binaryPath, process.argv.slice(2), {
+      stdio: 'inherit',
+    });
+
+    // Forward terminal resize signal (vital for TUI layout updates)
+    const onResize = () => {
+      if (child.pid && !child.killed) {
+        try {
+          child.kill('SIGWINCH');
+        } catch {}
+      }
+    };
+    process.on('SIGWINCH', onResize);
+
+    // Forward termination signals
+    const onSignal = (sig) => {
+      if (child.pid && !child.killed) {
+        try {
+          child.kill(sig);
+        } catch {}
+      }
+    };
+    process.on('SIGINT', () => onSignal('SIGINT'));
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+
+    child.on('close', (code, signal) => {
+      process.removeListener('SIGWINCH', onResize);
+      if (signal) {
+        process.kill(process.pid, signal);
+      } else {
+        process.exit(code !== null ? code : 0);
+      }
+    });
+
+    child.on('error', (err) => {
+      console.error(`[agentcontroll] Failed to execute ${binaryName}: ${err.message}`);
+      process.exit(1);
+    });
+  } catch (err) {
+    console.error(`[agentcontroll] Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  runBinary,
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "agentcontroll",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Local-first control plane for coding agents (Antigravity, Claude Code, Codex, Devin CLI)",
+  "bin": {
+    "agentcontroll": "bin/agentcontroll.js",
+    "agent-control": "bin/agent-control.js",
+    "agy": "bin/agy.js",
+    "ac": "bin/ac.js",
+    "agentcontrold": "bin/agentcontrold.js"
+  },
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "node test/platform.test.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "coding-agent",
+    "antigravity",
+    "claude-code",
+    "pty",
+    "terminal",
+    "tui",
+    "ai-agents",
+    "developer-tools"
+  ],
+  "author": "AgentControll contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vijaygovindBiju/AgentControll"
+  },
+  "bugs": {
+    "url": "https://github.com/vijaygovindBiju/AgentControll/issues"
+  },
+  "homepage": "https://github.com/vijaygovindBiju/AgentControll#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+