@aegisagentics/agent 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+# Aegis Agent
+
+Local installer, hook runtime, and public npm bootstrapper for Aegis ControlTower coding-agent telemetry.
+
+`@aegisagentics/agent` installs a native `aegis-agent` runtime, registers supported local agent hooks, and sends safe, governed telemetry to Aegis ControlTower. The npm package is intentionally thin: it does not ship platform binaries. Release binaries are built by CI, checksummed, uploaded to the Aegis website release path, then downloaded and verified during install.
+
+## Quick Start
+
+Create an agent installation in ControlTower, then run the generated command:
+
+```bash
+AEGIS_API_KEY="agk_or_bootstrap_token" npx -y @aegisagentics/agent install \
+  --api-base-url "https://stage.0.aegisagentics.com" \
+  --otlp-http-base-url "https://otel.stage.0.aegisagentics.com" \
+  --installation-id "agent_install_..." \
+  --vendors codex
+```
+
+Useful follow-up commands:
+
+```bash
+aegis-agent status
+aegis-agent doctor
+aegis-agent flush
+npx -y @aegisagentics/agent codex-plugin uninstall
+npx -y @aegisagentics/agent uninstall --vendors codex
+```
+
+For local development without downloading a release binary:
+
+```bash
+cargo build --release
+AEGIS_AGENT_BINARY_PATH="$PWD/target/release/aegis-agent" npm exec -- aegis-agent --help
+```
+
+## What This Repo Contains
+
+```text
+package.json                         Public npm bootstrapper metadata
+npm/install.js                       User-facing npx entrypoint
+npm/lib/                             Bootstrapper, Codex hook, and release download logic
+npm/test/                            Node test suite
+npm/release-manifest.json            Publish-time manifest embedded in the npm package
+crates/aegis-agent/                  Native Rust runtime
+.github/workflows/release.yml        CI release workflow for binaries + npm
+```
+
+## Install Lifecycle
+
+1. A ControlTower admin creates an agent installation.
+2. ControlTower returns an install command with API base URL, OTLP collector URL, installation ID, and scoped agent key.
+3. The npm bootstrapper detects the user's platform.
+4. If the native runtime is missing, the bootstrapper downloads the matching release artifact from `https://aegisagentics.com/releases/aegis-agent`.
+5. The bootstrapper verifies byte size and SHA-256 before extracting.
+6. The native runtime writes local config and owner-only credentials.
+7. Vendor-specific hook files are installed. Codex currently uses both plugin registration and Aegis-owned direct `hooks.json` entries for reliable local execution.
+8. Agent hooks send safe metadata, OTLP facts, queue-backed human-readable logs, and governed capture candidates according to local capture policy.
+
+## Local Files
+
+```text
+~/.config/aegis-agent/config.json
+~/.config/aegis-agent/credentials.json
+~/.local/share/aegis-agent/bin/aegis-agent
+~/.local/share/aegis-agent/queue/events.jsonl
+~/.local/share/aegis-agent/codex-marketplace
+```
+
+`credentials.json` is written with owner-only permissions on Unix systems. Production installers should move to OS keychain storage where available, but file permissions are enforced today.
+
+## Codex Integration
+
+The Codex marketplace generated by this package creates:
+
+```text
+codex-marketplace/.agents/plugins/marketplace.json
+codex-marketplace/plugins/aegis/.codex-plugin/plugin.json
+codex-marketplace/plugins/aegis/hooks/hooks.json
+```
+
+Hook commands point to the installed native runtime:
+
+```bash
+~/.local/share/aegis-agent/bin/aegis-agent hook --vendor=codex --event=PostToolUse
+```
+
+Codex passes hook payloads on stdin. Command-line arguments only identify the vendor and lifecycle event.
+
+## Telemetry Paths
+
+The plugin intentionally separates facts, logs, and artifacts:
+
+| Data type | Path | Notes |
+| --- | --- | --- |
+| Run/session/tool facts | Plugin -> OTLP collector -> ControlTower API | Metadata and span facts. Collector forwards agent auth. |
+| Human-readable logs | Plugin -> API -> queue -> worker -> Postgres | Safe operator log lines only. No raw prompts or tool payloads. |
+| Capture artifacts | Plugin/gateway -> Capture API -> queue -> worker -> Presidio -> database | Redacted content only after server-side sanitization. |
+
+The local safe queue is removed only after required downstream delivery succeeds. If the collector or API is unavailable, retry with:
+
+```bash
+aegis-agent flush
+```
+
+## Capture Policy
+
+The default capture policy is `metadata`.
+
+Stored metadata may include:
+
+- vendor and lifecycle event
+- vendor event name
+- session, turn, trace, and span identifiers
+- model and source
+- tool name and tool call id
+- working directory and transcript path when the agent provides them
+- vendor timestamp, status, duration, and raw payload size
+
+Raw prompts, agent messages, tool inputs, and tool outputs are not sent in facts, logs, local queues, or ClickHouse telemetry. If `redacted` capture is enabled, content candidates are sent to the capture API for server-side Presidio redaction before persistence.
+
+## Release Architecture
+
+The public npm package does not contain Rust binaries. Release files live under the Aegis website bucket and are served through CloudFront:
+
+```text
+https://aegisagentics.com/releases/aegis-agent/channels/stable.json
+https://aegisagentics.com/releases/aegis-agent/versions/<version>/manifest.json
+https://aegisagentics.com/releases/aegis-agent/versions/<version>/<platform>/aegis-agent.tar.gz
+https://aegisagentics.com/releases/aegis-agent/versions/<version>/<platform>/aegis-agent.tar.gz.sha256
+```
+
+Supported platform keys:
+
+- `darwin-arm64`
+- `darwin-x64`
+- `linux-arm64`
+- `linux-x64`
+
+The release workflow:
+
+1. Validates the release version against `package.json`.
+2. Runs npm tests.
+3. Runs Cargo tests.
+4. Builds native release binaries for supported targets.
+5. Packages `aegis-agent.tar.gz`.
+6. Computes SHA-256 and byte size.
+7. Generates version and channel manifests.
+8. Uploads release files under `s3://aegis-agentics-website/releases/aegis-agent/*`.
+9. Invalidates the CloudFront channel and manifest paths.
+10. Runs `npm pack --dry-run`.
+11. Publishes `@aegisagentics/agent` to npm.
+
+## GitHub Release Configuration
+
+Required repository secrets:
+
+```text
+AWS_ROLE_ARN=<release publisher IAM role ARN from website infrastructure output>
+NPM_TOKEN=<npm automation token with publish rights for @aegisagentics/agent>
+```
+
+Optional repository variables:
+
+```text
+AWS_REGION=us-east-1
+SSM_ROOT_PREFIX=/aegis-agentics
+```
+
+The AWS role is scoped to:
+
+- read the website bucket and CloudFront distribution ID from SSM
+- list only the `releases/aegis-agent` prefix
+- put/get objects only under `releases/aegis-agent/*`
+- create CloudFront invalidations
+
+It does not grant general website deploy permissions or S3 delete access.
+
+## Publishing a Release
+
+The release workflow runs when a tag matching `v*.*.*` is pushed. Update
+`package.json`, `Cargo.toml`, and `Cargo.lock` to the same semver version,
+commit the change, then push `main` and the version tag:
+
+```bash
+git status
+git add package.json Cargo.toml Cargo.lock
+git commit -m "Release 0.1.0"
+git push origin main
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+If `main` already contains the exact release version, only the tag push is
+needed:
+
+```bash
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+Manual release runs are also supported from GitHub Actions with
+`workflow_dispatch`; the requested version must still match `package.json`.
+
+## Development
+
+Run the npm tests:
+
+```bash
+npm test
+```
+
+Run Rust tests:
+
+```bash
+cargo test --locked
+```
+
+Validate publish contents:
+
+```bash
+npm pack --dry-run
+```
+
+Useful release-download overrides:
+
+```bash
+AEGIS_AGENT_RELEASE_BASE_URL="https://localhost/releases/aegis-agent"
+AEGIS_AGENT_RELEASE_VERSION="0.1.0"
+AEGIS_AGENT_FORCE_BINARY_DOWNLOAD=1
+```
+
+## Security Notes
+
+- Do not commit `.env`, private keys, generated packages, or local credentials.
+- The npm `files` allowlist keeps the package limited to the bootstrapper, README, and generated release manifest.
+- Archive extraction rejects absolute paths and `..` path traversal.
+- Downloaded binaries are size-checked and SHA-256 checked before install.
+- Activity logs are intentionally human-readable and metadata-only.
+- Tool input/output belongs to the governed capture artifact pipeline, not activity logs.

package/npm/install.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { aegisPaths } from "./lib/config.js";
+import { parseBootstrapCommand } from "./lib/cli.js";
+import {
+  hookFilesForCodexUninstall,
+  installAegisHooksFiles,
+  scrubAegisHooksFiles
+} from "./lib/codex-hooks.js";
+import { installCodexPlugin, uninstallCodexPlugin } from "./lib/codex-plugin.js";
+import {
+  detectCodexHome,
+  prepareCodexPluginInstallTarget
+} from "./lib/codex-runtime.js";
+import { ensureNativeBinary } from "./lib/release-download.js";
+
+async function main() {
+  const binaryPath = resolveBinaryPath();
+  const args = process.argv.slice(2);
+  const paths = aegisPaths(process.env.HOME);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    printHelp(binaryPath);
+    return 0;
+  }
+
+  let command;
+  try {
+    command = parseBootstrapCommand(args);
+  } catch (error) {
+    console.error(`aegis-agent: ${error.message}`);
+    return 2;
+  }
+
+  if (command.kind === "codex-plugin") {
+    if (command.codexPluginAction === "install") {
+      const status = await ensureBootstrapBinary(binaryPath);
+      if (status !== 0) {
+        return status;
+      }
+    }
+    return await runCodexPluginAction(command.codexPluginAction, paths, {
+      softFail: false
+    });
+  }
+
+  let codexPluginFailed = false;
+  if (command.codexPluginAction === "uninstall") {
+    const status = await runCodexPluginAction("uninstall", paths, {
+      softFail: true
+    });
+    codexPluginFailed = status !== 0;
+  }
+
+  if (!fs.existsSync(binaryPath) && command.nativeArgs[0] !== "uninstall") {
+    const status = await ensureBootstrapBinary(binaryPath);
+    if (status !== 0) {
+      return status;
+    }
+  }
+
+  if (!fs.existsSync(binaryPath)) {
+    if (args[0] === "uninstall") {
+      console.log(`Aegis Agent runtime already missing at ${binaryPath}`);
+      return codexPluginFailed ? 1 : 0;
+    }
+    printMissingBinary(binaryPath);
+    return 1;
+  }
+
+  const result = spawnSync(binaryPath, command.nativeArgs, {
+    env: process.env,
+    stdio: "inherit"
+  });
+
+  if (result.error) {
+    console.error(`aegis-agent: failed to execute ${binaryPath}: ${result.error.message}`);
+    return 1;
+  }
+  const nativeStatus = result.status ?? 1;
+  if (nativeStatus !== 0) {
+    return nativeStatus;
+  }
+
+  if (command.codexPluginAction === "install") {
+    return await runCodexPluginAction("install", paths, {
+      softFail: false
+    });
+  }
+
+  return codexPluginFailed ? 1 : 0;
+}
+
+async function ensureBootstrapBinary(binaryPath) {
+  if (process.env.AEGIS_AGENT_BINARY_PATH) {
+    return 0;
+  }
+  if (fs.existsSync(binaryPath) && process.env.AEGIS_AGENT_FORCE_BINARY_DOWNLOAD !== "1") {
+    return 0;
+  }
+  try {
+    const result = await ensureNativeBinary({ binaryPath });
+    if (result.downloaded) {
+      console.log(`Downloaded Aegis Agent runtime: ${binaryPath}`);
+    }
+    return 0;
+  } catch (error) {
+    console.error(`aegis-agent: failed to install native runtime: ${error.message}`);
+    return 1;
+  }
+}
+
+function resolveBinaryPath() {
+  if (process.env.AEGIS_AGENT_BINARY_PATH) {
+    return process.env.AEGIS_AGENT_BINARY_PATH;
+  }
+  const paths = aegisPaths(process.env.HOME);
+  if (fs.existsSync(paths.binaryFile)) {
+    return paths.binaryFile;
+  }
+
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const devBinary = path.resolve(moduleDir, "..", "target", "release", "aegis-agent");
+  if (fs.existsSync(devBinary)) {
+    return devBinary;
+  }
+  return paths.binaryFile;
+}
+
+function printHelp(binaryPath) {
+  console.log(`Aegis Agent installer bootstrap
+
+Usage:
+  AEGIS_API_KEY="<one-time-key>" npx -y @aegisagentics/agent install --api-base-url "https://controltower.example.com" --otlp-http-base-url "https://otel.controltower.example.com" --installation-id "agent_install_..." --vendors codex,claude,cursor
+  npx -y @aegisagentics/agent codex-plugin install
+  npx -y @aegisagentics/agent codex-plugin uninstall
+  npx -y @aegisagentics/agent uninstall --vendors codex
+  aegis-agent-install install --api-key "$AEGIS_API_KEY" --api-base-url "https://controltower.example.com" --otlp-http-base-url "https://otel.controltower.example.com" --installation-id "agent_install_..." --vendors codex
+
+The npm package is a bootstrapper. The hook runtime is the native binary:
+  ${binaryPath}
+
+For source builds, set AEGIS_AGENT_BINARY_PATH to a locally built aegis-agent binary.
+`);
+}
+
+async function runCodexPluginAction(action, paths, { softFail }) {
+  try {
+    if (action === "install") {
+      const target = await prepareCodexPluginInstallTarget({
+        userPaths: paths
+      });
+      if (!fs.existsSync(target.marketplaceFile)) {
+        throw new Error(
+          `Codex marketplace file not found at ${target.marketplaceFile}. Run the Aegis install command first.`
+        );
+      }
+      const hookInstallResults = await installAegisHooksFiles({
+        binaryPath: target.binaryFile,
+        files: hookFilesForCodexUninstall({
+          codexHome: target.codexHome,
+          userPaths: paths
+        })
+      });
+      const addedHooks = hookInstallResults.reduce((sum, result) => sum + result.added, 0);
+      const replacedHooks = hookInstallResults.reduce((sum, result) => sum + result.replaced, 0);
+      await installCodexPlugin({ marketplaceFile: target.marketplaceFile });
+      if (target.mirrored) {
+        console.log(`Prepared Codex-isolated Aegis runtime: ${target.codexHome}`);
+      }
+      console.log(
+        `Installed Aegis Codex hooks.json entries: ${addedHooks} added, ${replacedHooks} replaced`
+      );
+      console.log("Codex plugin installed: aegis@aegis");
+      return 0;
+    }
+
+    if (action === "uninstall") {
+      let pluginError = null;
+      try {
+        await uninstallCodexPlugin();
+      } catch (error) {
+        pluginError = error;
+      }
+      const scrubResults = await scrubAegisHooksFiles(
+        hookFilesForCodexUninstall({
+          codexHome: detectCodexHome(),
+          userPaths: paths
+        })
+      );
+      const removedHooks = scrubResults.reduce((sum, result) => sum + result.removed, 0);
+      if (removedHooks > 0) {
+        console.log(`Removed ${removedHooks} Aegis hook entr${removedHooks === 1 ? "y" : "ies"} from Codex hooks.json`);
+      }
+      if (pluginError) {
+        throw pluginError;
+      }
+      console.log("Codex plugin uninstalled: aegis@aegis");
+      return 0;
+    }
+
+    throw new Error(`Unsupported Codex plugin action: ${action}`);
+  } catch (error) {
+    const message = `Codex plugin ${action} failed: ${error.message}`;
+    if (softFail) {
+      console.warn(`aegis-agent: ${message}`);
+      return 1;
+    }
+    console.error(`aegis-agent: ${message}`);
+    return 1;
+  }
+}
+
+function printMissingBinary(binaryPath) {
+  console.error(`aegis-agent: native binary not found at ${binaryPath}
+
+The npm bootstrapper downloads and verifies the release runtime when it is missing.
+For local development:
+  cd crates/aegis-agent
+  cargo build --release
+  AEGIS_AGENT_BINARY_PATH="$PWD/target/release/aegis-agent" node ../../npm/install.js --help
+`);
+}
+
+process.exitCode = await main();

package/npm/lib/cli.js

@@ -0,0 +1,80 @@
+import { normalizeVendorList } from "./config.js";
+
+export function parseBootstrapCommand(args) {
+  const command = args[0] ?? "";
+
+  if (command === "codex-plugin") {
+    const action = args[1] ?? "";
+    if (action !== "install" && action !== "uninstall") {
+      throw new Error(
+        "Usage: aegis-agent codex-plugin <install|uninstall>"
+      );
+    }
+    return {
+      codexPluginAction: action,
+      kind: "codex-plugin",
+      nativeArgs: []
+    };
+  }
+
+  if (command === "install") {
+    const vendors = extractVendorList(args, "codex");
+    return {
+      codexPluginAction: vendors.includes("codex") ? "install" : null,
+      kind: "native",
+      nativeArgs: args
+    };
+  }
+
+  if (command === "uninstall") {
+    const vendors = extractVendorList(args, "codex");
+    return {
+      codexPluginAction: vendors.includes("codex") ? "uninstall" : null,
+      kind: "native",
+      nativeArgs: stripOption(args, "--vendors")
+    };
+  }
+
+  return {
+    codexPluginAction: null,
+    kind: "native",
+    nativeArgs: args
+  };
+}
+
+function extractVendorList(args, fallback) {
+  const values = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--vendors") {
+      if (index + 1 >= args.length) {
+        throw new Error("--vendors requires a value");
+      }
+      values.push(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--vendors=")) {
+      values.push(arg.slice("--vendors=".length));
+    }
+  }
+
+  return normalizeVendorList(values.length > 0 ? values.join(",") : fallback);
+}
+
+function stripOption(args, optionName) {
+  const stripped = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === optionName) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith(`${optionName}=`)) {
+      continue;
+    }
+    stripped.push(arg);
+  }
+  return stripped;
+}

package/npm/lib/codex-hooks.js

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { buildCodexHooks } from "./codex.js";
+
+const AEGIS_COMMAND_MARKERS = [
+  "/aegis-agent/bin/aegis-agent hook --vendor=codex",
+  "/aegis-agent hook --vendor=codex",
+  "aegis-agent hook --vendor=codex"
+];
+
+export function hookFilesForCodexUninstall({ codexHome, userPaths }) {
+  const files = [path.join(userPaths.homeDir, ".codex", "hooks.json")];
+  if (codexHome && path.resolve(codexHome) !== path.resolve(userPaths.homeDir)) {
+    files.push(path.join(codexHome, "hooks.json"));
+  }
+  return [...new Set(files.map((file) => path.resolve(file)))];
+}
+
+export async function scrubAegisHooksFiles(files) {
+  const results = [];
+  for (const file of files) {
+    results.push({
+      file,
+      ...(await scrubAegisHooksFile(file))
+    });
+  }
+  return results;
+}
+
+export async function installAegisHooksFiles({ binaryPath, files }) {
+  const results = [];
+  for (const hooksFile of files) {
+    results.push({
+      file: hooksFile,
+      ...(await installAegisHooksFile({ binaryPath, hooksFile }))
+    });
+  }
+  return results;
+}
+
+export async function installAegisHooksFile({ binaryPath, hooksFile }) {
+  let document = { hooks: {} };
+  try {
+    document = JSON.parse(await fs.readFile(hooksFile, "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    document = { hooks: {} };
+  }
+  if (!isObject(document.hooks)) {
+    document.hooks = {};
+  }
+
+  const scrubbed = removeAegisHandlers(document);
+  const aegisHooks = buildCodexHooks({ binaryPath }).hooks;
+
+  for (const [eventName, groups] of Object.entries(aegisHooks)) {
+    const currentGroups = Array.isArray(scrubbed.document.hooks[eventName])
+      ? scrubbed.document.hooks[eventName]
+      : [];
+    scrubbed.document.hooks[eventName] = [...currentGroups, ...groups];
+  }
+
+  await fs.mkdir(path.dirname(hooksFile), { recursive: true });
+  await fs.writeFile(hooksFile, `${JSON.stringify(scrubbed.document, null, 2)}\n`, "utf8");
+
+  return {
+    added: Object.keys(aegisHooks).length,
+    replaced: scrubbed.removed
+  };
+}
+
+export async function scrubAegisHooksFile(file) {
+  let raw;
+  try {
+    raw = await fs.readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { missing: true, removed: 0, removedFile: false };
+    }
+    throw error;
+  }
+
+  const document = JSON.parse(raw);
+  if (!document || typeof document !== "object" || !isObject(document.hooks)) {
+    return { missing: false, removed: 0, removedFile: false };
+  }
+
+  const { document: nextDocument, removed } = removeAegisHandlers(document);
+
+  if (removed === 0) {
+    return { missing: false, removed: 0, removedFile: false };
+  }
+
+  if (Object.keys(nextDocument.hooks).length === 0 && Object.keys(nextDocument).length === 1) {
+    await fs.unlink(file);
+    return { missing: false, removed, removedFile: true };
+  }
+
+  await fs.writeFile(file, `${JSON.stringify(nextDocument, null, 2)}\n`, "utf8");
+  return { missing: false, removed, removedFile: false };
+}
+
+function removeAegisHandlers(document) {
+  let removed = 0;
+  const nextHooks = {};
+
+  for (const [eventName, groups] of Object.entries(document.hooks ?? {})) {
+    if (!Array.isArray(groups)) {
+      nextHooks[eventName] = groups;
+      continue;
+    }
+
+    const nextGroups = [];
+    for (const group of groups) {
+      if (!isObject(group) || !Array.isArray(group.hooks)) {
+        nextGroups.push(group);
+        continue;
+      }
+
+      const nextHandlers = group.hooks.filter((handler) => {
+        if (isAegisHookHandler(handler)) {
+          removed += 1;
+          return false;
+        }
+        return true;
+      });
+
+      if (nextHandlers.length > 0) {
+        nextGroups.push({
+          ...group,
+          hooks: nextHandlers
+        });
+      }
+    }
+
+    if (nextGroups.length > 0) {
+      nextHooks[eventName] = nextGroups;
+    }
+  }
+
+  return {
+    document: {
+      ...document,
+      hooks: nextHooks
+    },
+    removed
+  };
+}
+
+function isAegisHookHandler(handler) {
+  if (!isObject(handler) || typeof handler.command !== "string") {
+    return false;
+  }
+  return AEGIS_COMMAND_MARKERS.some((marker) => handler.command.includes(marker));
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}