@aegisagentics/agent 0.1.0

package/npm/lib/codex-plugin.js

@@ -0,0 +1,186 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+export const DEFAULT_CODEX_PLUGIN_ID = "aegis@aegis";
+export const DEFAULT_CODEX_PLUGIN_NAME = "aegis";
+
+export function codexMarketplaceFile(paths) {
+  return path.join(paths.codexMarketplaceDir, ".agents", "plugins", "marketplace.json");
+}
+
+export function buildCodexPluginInstallRequest({
+  id = 2,
+  marketplaceFile,
+  pluginName = DEFAULT_CODEX_PLUGIN_NAME
+}) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "plugin/install",
+    params: {
+      marketplacePath: marketplaceFile,
+      pluginName
+    }
+  };
+}
+
+export function buildCodexPluginUninstallRequest({
+  id = 2,
+  pluginId = DEFAULT_CODEX_PLUGIN_ID
+} = {}) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "plugin/uninstall",
+    params: {
+      pluginId
+    }
+  };
+}
+
+export async function installCodexPlugin({
+  codexCommand = "codex",
+  marketplaceFile,
+  pluginName = DEFAULT_CODEX_PLUGIN_NAME,
+  timeoutMs = 15_000
+}) {
+  const request = buildCodexPluginInstallRequest({
+    marketplaceFile,
+    pluginName
+  });
+  return runCodexPluginRequest({
+    codexCommand,
+    request,
+    timeoutMs
+  });
+}
+
+export async function uninstallCodexPlugin({
+  codexCommand = "codex",
+  pluginId = DEFAULT_CODEX_PLUGIN_ID,
+  timeoutMs = 15_000
+} = {}) {
+  const request = buildCodexPluginUninstallRequest({ pluginId });
+  return runCodexPluginRequest({
+    codexCommand,
+    request,
+    timeoutMs
+  });
+}
+
+async function runCodexPluginRequest({ codexCommand, request, timeoutMs }) {
+  const appServer = spawn(codexCommand, ["app-server", "--listen", "stdio://"], {
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+
+  let stderr = "";
+  let stdoutBuffer = "";
+  let settled = false;
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      finish(
+        reject,
+        new Error(
+          `Timed out waiting for Codex app-server response to ${request.method}`
+        )
+      );
+    }, timeoutMs);
+
+    appServer.on("error", (error) => {
+      clearTimeout(timer);
+      finish(
+        reject,
+        new Error(
+          `Unable to start Codex CLI (${codexCommand}) for plugin management: ${error.message}`
+        )
+      );
+    });
+
+    appServer.stderr.setEncoding("utf8");
+    appServer.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+
+    appServer.stdout.setEncoding("utf8");
+    appServer.stdout.on("data", (chunk) => {
+      stdoutBuffer += chunk;
+      const lines = stdoutBuffer.split(/\r?\n/);
+      stdoutBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim() === "") {
+          continue;
+        }
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        handleMessage(message);
+      }
+    });
+
+    appServer.on("close", (code) => {
+      if (!settled) {
+        clearTimeout(timer);
+        finish(
+          reject,
+          new Error(
+            `Codex app-server exited before ${request.method} completed (exit ${code ?? "unknown"}): ${stderr.trim()}`
+          )
+        );
+      }
+    });
+
+    writeJsonRpc({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: {
+          name: "aegis-agent",
+          version: "0.1.0"
+        }
+      }
+    });
+
+    function handleMessage(message) {
+      if (message.id === 1) {
+        writeJsonRpc(request);
+        return;
+      }
+      if (message.id !== request.id) {
+        return;
+      }
+      clearTimeout(timer);
+      if (message.error) {
+        finish(
+          reject,
+          new Error(
+            `Codex ${request.method} failed: ${message.error.message ?? JSON.stringify(message.error)}`
+          )
+        );
+        return;
+      }
+      finish(resolve, message.result ?? {});
+    }
+
+    function writeJsonRpc(message) {
+      appServer.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+
+    function finish(callback, value) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      if (!appServer.killed) {
+        appServer.kill();
+      }
+      callback(value);
+    }
+  });
+}

package/npm/lib/codex-runtime.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { writeCodexMarketplace } from "./codex.js";
+import { codexMarketplaceFile } from "./codex-plugin.js";
+import { aegisPaths } from "./config.js";
+
+export function detectCodexHome() {
+  if (process.env.AEGIS_CODEX_HOME?.trim()) {
+    return process.env.AEGIS_CODEX_HOME.trim();
+  }
+
+  const result = spawnSync(
+    "snap",
+    ["run", "--shell", "codex", "-c", "printf '%s' \"$HOME\""],
+    {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }
+  );
+  if (result.status !== 0) {
+    return null;
+  }
+  const home = result.stdout.trim();
+  return home === "" ? null : home;
+}
+
+export async function prepareCodexPluginInstallTarget({
+  codexHome = detectCodexHome(),
+  userPaths
+}) {
+  if (codexHome === null || samePath(codexHome, userPaths.homeDir)) {
+    await writeCodexMarketplace({
+      binaryPath: userPaths.binaryFile,
+      marketplaceDir: userPaths.codexMarketplaceDir
+    });
+    return {
+      binaryFile: userPaths.binaryFile,
+      codexHome: userPaths.homeDir,
+      marketplaceFile: codexMarketplaceFile(userPaths),
+      mirrored: false
+    };
+  }
+
+  const codexPaths = aegisPaths(codexHome);
+  await copyExecutable(userPaths.binaryFile, codexPaths.binaryFile);
+  await copyPrivateFile(userPaths.configFile, codexPaths.configFile);
+  await copyPrivateFile(userPaths.credentialsFile, codexPaths.credentialsFile);
+  await writeCodexMarketplace({
+    binaryPath: codexPaths.binaryFile,
+    marketplaceDir: codexPaths.codexMarketplaceDir
+  });
+
+  return {
+    binaryFile: codexPaths.binaryFile,
+    codexHome,
+    marketplaceFile: codexMarketplaceFile(codexPaths),
+    mirrored: true
+  };
+}
+
+function samePath(left, right) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+async function copyExecutable(source, destination) {
+  await copyFile(source, destination);
+  const sourceMode = (await fs.stat(source)).mode & 0o777;
+  await fs.chmod(destination, sourceMode || 0o755);
+}
+
+async function copyPrivateFile(source, destination) {
+  await copyFile(source, destination);
+  await fs.chmod(destination, 0o600);
+}
+
+async function copyFile(source, destination) {
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.copyFile(source, destination);
+}

package/npm/lib/codex.js

@@ -0,0 +1,110 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const HOOK_EVENTS = [
+  ["SessionStart", "startup|resume|clear"],
+  ["UserPromptSubmit", null],
+  ["PreToolUse", "*"],
+  ["PostToolUse", "*"],
+  ["Stop", null]
+];
+
+export function buildCodexMarketplace({ binaryPath }) {
+  const marketplace = {
+    interface: {
+      developerName: "Aegis Agentics",
+      displayName: "Aegis ControlTower",
+      shortDescription: "Governed telemetry for Codex agent sessions.",
+      websiteURL: "https://aegisagentics.com"
+    },
+    name: "aegis",
+    plugins: [
+      {
+        category: "Security",
+        name: "aegis",
+        policy: {
+          authentication: "ON_INSTALL",
+          installation: "AVAILABLE"
+        },
+        source: {
+          path: "./plugins/aegis",
+          source: "local"
+        }
+      }
+    ]
+  };
+
+  const plugin = {
+    author: {
+      name: "Aegis Agentics",
+      url: "https://aegisagentics.com"
+    },
+    description: "Aegis ControlTower monitoring for Codex sessions, turns, and tools.",
+    displayName: "Aegis ControlTower",
+    homepage: "https://aegisagentics.com",
+    hooks: "./hooks/hooks.json",
+    interface: {
+      capabilities: ["Read"],
+      category: "Security",
+      developerName: "Aegis Agentics",
+      displayName: "Aegis ControlTower",
+      shortDescription: "Monitor Codex agent activity in Aegis ControlTower"
+    },
+    keywords: ["aegis", "controltower", "governance", "telemetry", "codex"],
+    license: "UNLICENSED",
+    name: "aegis",
+    repository: "https://github.com/aegisagentics/controltower",
+    version: "0.1.0"
+  };
+
+  const hooks = buildCodexHooks({ binaryPath });
+
+  return { hooks, marketplace, plugin };
+}
+
+export function buildCodexHooks({ binaryPath }) {
+  return {
+    hooks: Object.fromEntries(
+      HOOK_EVENTS.map(([event, matcher]) => {
+        const group = {
+          hooks: [
+            {
+              command: `${binaryPath} hook --vendor=codex --event=${event}`,
+              timeout: event === "Stop" ? 30 : 10,
+              type: "command"
+            }
+          ]
+        };
+        if (matcher !== null) {
+          group.matcher = matcher;
+        }
+        return [event, [group]];
+      })
+    )
+  };
+}
+
+export async function writeCodexMarketplace({ binaryPath, marketplaceDir }) {
+  const { hooks, marketplace, plugin } = buildCodexMarketplace({ binaryPath });
+  const marketplaceFile = path.join(marketplaceDir, ".agents", "plugins", "marketplace.json");
+  const pluginFile = path.join(marketplaceDir, "plugins", "aegis", ".codex-plugin", "plugin.json");
+  const hooksFile = path.join(marketplaceDir, "plugins", "aegis", "hooks", "hooks.json");
+
+  await fs.mkdir(path.dirname(marketplaceFile), { recursive: true });
+  await fs.mkdir(path.dirname(pluginFile), { recursive: true });
+  await fs.mkdir(path.dirname(hooksFile), { recursive: true });
+
+  await writeJson(marketplaceFile, marketplace);
+  await writeJson(pluginFile, plugin);
+  await writeJson(hooksFile, hooks);
+
+  return {
+    hooksFile,
+    marketplaceFile,
+    pluginFile
+  };
+}
+
+async function writeJson(filePath, payload) {
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}

package/npm/lib/config.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+
+const VENDOR_ALIASES = new Map([
+  ["cc", "claude-code"],
+  ["claude", "claude-code"],
+  ["claude-code", "claude-code"],
+  ["claudecode", "claude-code"],
+  ["codex", "codex"],
+  ["cursor", "cursor"],
+  ["goose", "goose"]
+]);
+
+const VENDOR_ORDER = ["codex", "claude-code", "cursor", "goose"];
+
+export function normalizeVendorList(value) {
+  const raw = Array.isArray(value) ? value : String(value ?? "").split(",");
+  const seen = new Set();
+
+  for (const item of raw) {
+    const key = String(item).trim().toLowerCase();
+    if (key === "" || key === "all") {
+      if (key === "all") {
+        for (const vendor of VENDOR_ORDER) {
+          seen.add(vendor);
+        }
+      }
+      continue;
+    }
+    const normalized = VENDOR_ALIASES.get(key);
+    if (normalized === undefined) {
+      throw new Error(`Unknown Aegis agent vendor: ${item}`);
+    }
+    seen.add(normalized);
+  }
+
+  return VENDOR_ORDER.filter((vendor) => seen.has(vendor));
+}
+
+export function aegisPaths(homeDir = process.env.HOME) {
+  if (!homeDir) {
+    throw new Error("Unable to resolve home directory for Aegis agent install.");
+  }
+  const configDir = path.join(homeDir, ".config", "aegis-agent");
+  const dataDir = path.join(homeDir, ".local", "share", "aegis-agent");
+  const binaryDir = path.join(dataDir, "bin");
+
+  return {
+    binaryDir,
+    binaryFile: path.join(binaryDir, "aegis-agent"),
+    codexMarketplaceDir: path.join(dataDir, "codex-marketplace"),
+    configDir,
+    configFile: path.join(configDir, "config.json"),
+    credentialsFile: path.join(configDir, "credentials.json"),
+    dataDir,
+    homeDir,
+    queueDir: path.join(dataDir, "queue")
+  };
+}
+
+export function buildLocalConfig({
+  agentId,
+  apiBaseUrl,
+  capturePolicy,
+  installationId,
+  activityLogEndpoint,
+  otlpHttpBaseUrl,
+  otlpTracesEndpoint,
+  organizationId,
+  workspaceId,
+  workspaceKind
+}) {
+  const normalizedApiBaseUrl = String(apiBaseUrl).replace(/\/+$/, "");
+  const normalizedOtlpHttpBaseUrl =
+    otlpHttpBaseUrl === undefined || otlpHttpBaseUrl === null || String(otlpHttpBaseUrl).trim() === ""
+      ? undefined
+      : String(otlpHttpBaseUrl).trim().replace(/\/+$/, "");
+  const normalizedOtlpTracesEndpoint =
+    otlpTracesEndpoint === undefined || otlpTracesEndpoint === null || String(otlpTracesEndpoint).trim() === ""
+      ? normalizedOtlpHttpBaseUrl === undefined
+        ? undefined
+        : `${normalizedOtlpHttpBaseUrl}/v1/traces`
+      : String(otlpTracesEndpoint).trim().replace(/\/+$/, "");
+  if (normalizedOtlpTracesEndpoint === undefined) {
+    throw new Error(
+      "OTLP HTTP base URL is required; pass otlpHttpBaseUrl or otlpTracesEndpoint"
+    );
+  }
+  const normalizedActivityLogEndpoint =
+    activityLogEndpoint === undefined || activityLogEndpoint === null || String(activityLogEndpoint).trim() === ""
+      ? `${normalizedApiBaseUrl}/v1/agent-activity/logs`
+      : String(activityLogEndpoint).trim().replace(/\/+$/, "");
+  return {
+    schemaVersion: "aegis.agent_config.v1",
+    agentId,
+    apiBaseUrl: normalizedApiBaseUrl,
+    activityLogEndpoint: normalizedActivityLogEndpoint,
+    captureEndpoint: `${normalizedApiBaseUrl}/v1/capture/artifacts`,
+    capturePolicy,
+    installationId,
+    organizationId,
+    otlpHttpBaseUrl: normalizedOtlpHttpBaseUrl,
+    otlpTracesEndpoint: normalizedOtlpTracesEndpoint,
+    workspaceId,
+    workspaceKind
+  };
+}