athena-agent-launcher 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# athena-agent-launcher
+
+Runs an agent configured on the Athena control plane locally on the user's machine.
+
+```
+# One-time setup (saves credentials to ~/.athena/credentials.json)
+npx athena-agent-launcher setup
+
+# Run an agent
+npx athena-agent-launcher run <agent-id>
+```
+
+For `hermes` runtime agents, the launcher will auto-install the Hermes binary
+silently on first run (via `curl ... | bash -s -- --skip-setup`), skipping Nous
+Research's setup wizard. The agent uses Athena's pre-configured YAML, an
+isolated `HOME` at `~/.athena/hermes/<agent-id>/`, and the Athena
+Anthropic-compatible proxy for inference.
+
+## Auth
+
+Per-agent API key (`ak_...`) issued via the Athena agents table. Supplied via one of:
+
+- `--api-key ak_...`
+- `ATHENA_API_KEY` env var
+- `~/.athena/credentials.json` → `{"api_key": "ak_...", "base_url": "..."}`
+
+## Flow
+
+1. Fetch `GET {base_url}/api/agents/{agentId}/launcher-manifest` with `Authorization: Bearer ak_...`.
+2. Manifest declares `runtime.kind` (`anthropic_sdk` | `openclaw` | `hermes`) and `runtime.version`.
+3. Launcher spawns `npx -y <entrypoint>` with manifest env injected. The spawned runtime resolves Anthropic / Cortex credentials via `ATHENA_GATEWAY_URL`; raw secrets never touch the launcher or the local filesystem.

package/bin/launcher.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// athena-agent-launcher
+//
+// Usage:
+//   npx athena-agent-launcher run <agent-id> [--base-url URL] [--api-key ak_...]
+//
+// Reads runtime config from Athena's control plane and spawns the
+// configured runtime (anthropic_sdk | openclaw | hermes). Secrets are
+// resolved at runtime by the spawned process via ATHENA_GATEWAY_URL — the
+// launcher itself never sees raw Anthropic or Cortex credentials.
+
+import { spawn } from "node:child_process";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import readline from "node:readline";
+
+const DEFAULT_BASE_URL = "https://athena-v2-pi.vercel.app";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--base-url") args.baseUrl = argv[++i];
+    else if (a === "--api-key") args.apiKey = argv[++i];
+    else if (a === "--runtime-cmd") args.runtimeCmd = argv[++i];
+    else if (a === "--manifest-only") args.manifestOnly = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function loadCredsFile() {
+  const p = join(homedir(), ".athena", "credentials.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function usage() {
+  process.stderr.write(
+    [
+      "Athena Agent Launcher — Sonance",
+      "",
+      "Usage:",
+      "  athena-agent setup                       One-time setup (prompts for creds)",
+      "  athena-agent run <agent-id> [options]    Run an agent locally",
+      "",
+      "Options for `run`:",
+      "  --base-url URL    Athena control-plane base URL",
+      `                    (default: ${DEFAULT_BASE_URL} or $ATHENA_BASE_URL)`,
+      "  --api-key ak_...  Per-agent API key",
+      "                    (default: $ATHENA_API_KEY or ~/.athena/credentials.json)",
+      "  --manifest-only   Print the launcher manifest and exit (no spawn)",
+      "  --runtime-cmd     Override the runtime command (smoke testing)",
+      "",
+    ].join("\n"),
+  );
+}
+
+function prompt(question, { mask = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    if (mask) {
+      // Hide typed input for secrets.
+      const onData = (char) => {
+        const s = char.toString();
+        if (s === "\n" || s === "\r" || s === "\r\n") {
+          process.stdin.removeListener("data", onData);
+        } else {
+          process.stdout.write("\x1b[2K\r" + question + "*".repeat(rl.line.length));
+        }
+      };
+      process.stdin.on("data", onData);
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      if (mask) process.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function runSetup() {
+  process.stdout.write(
+    [
+      "",
+      "╭──────────────────────────────────────────────╮",
+      "│   Athena Agent Launcher — Sonance Setup     │",
+      "╰──────────────────────────────────────────────╯",
+      "",
+      "This will save your Athena credentials to ~/.athena/credentials.json",
+      "so you can run agents without passing flags every time.",
+      "",
+    ].join("\n"),
+  );
+  const existing = loadCredsFile();
+  const baseUrl =
+    (await prompt(`Athena base URL [${existing.base_url || DEFAULT_BASE_URL}]: `)) ||
+    existing.base_url ||
+    DEFAULT_BASE_URL;
+  const email =
+    (await prompt(`Your Sonance email${existing.email ? ` [${existing.email}]` : ""}: `)) ||
+    existing.email ||
+    "";
+  if (!email) {
+    process.stderr.write("Email is required.\n");
+    process.exit(2);
+  }
+  process.stdout.write(
+    "\nPaste a per-agent API key (ak_...) issued from the agent's Permissions tab.\n" +
+      "You can have multiple keys; this one will be the default for `athena-agent run`.\n",
+  );
+  const apiKey =
+    (await prompt("API key (ak_...): ", { mask: true })) || existing.api_key || "";
+  if (!apiKey || !apiKey.startsWith("ak_")) {
+    process.stderr.write("Invalid API key. Must start with ak_.\n");
+    process.exit(2);
+  }
+
+  const credsPath = join(homedir(), ".athena", "credentials.json");
+  mkdirSync(dirname(credsPath), { recursive: true });
+  writeFileSync(
+    credsPath,
+    JSON.stringify({ base_url: baseUrl, email, api_key: apiKey }, null, 2),
+    "utf8",
+  );
+  chmodSync(credsPath, 0o600);
+  process.stdout.write(`\n✓ Saved to ${credsPath}\n`);
+  process.stdout.write("  Run an agent with: athena-agent run <agent-id>\n\n");
+}
+
+// Return the absolute path to `hermes` if it's findable on PATH, in
+// ~/.local/bin, or in a few other common locations. Returns null if not found.
+async function locateHermes() {
+  const userLocalBin = join(homedir(), ".local", "bin", "hermes");
+  const candidates = [userLocalBin, "/usr/local/bin/hermes", "/opt/homebrew/bin/hermes"];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  const which = await new Promise((resolve) => {
+    const c = spawn("which", ["hermes"], { stdio: ["ignore", "pipe", "ignore"] });
+    let out = "";
+    c.stdout.on("data", (d) => (out += d.toString()));
+    c.on("exit", () => resolve(out.trim()));
+  });
+  return which || null;
+}
+
+async function ensureHermesInstalled() {
+  const found = await locateHermes();
+  if (found) return found;
+
+  process.stderr.write(
+    "[athena-agent] Hermes is not installed. Installing silently (this is a one-time setup)…\n",
+  );
+  // `bash -s -- --skip-setup` passes the flag to the install script and
+  // suppresses its post-install wizard, so the user only ever sees Athena's UX.
+  const code = await new Promise((resolve) => {
+    const c = spawn(
+      "bash",
+      ["-c", "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup"],
+      { stdio: "inherit" },
+    );
+    c.on("exit", (code) => resolve(code ?? 1));
+  });
+  if (code !== 0) {
+    process.stderr.write("[athena-agent] Hermes install failed. See output above.\n");
+    return null;
+  }
+  process.stderr.write("[athena-agent] Hermes installed.\n");
+  return await locateHermes();
+}
+
+async function fetchManifest({ baseUrl, agentId, apiKey }) {
+  const res = await fetch(`${baseUrl}/api/agents/${agentId}/launcher-manifest`, {
+    headers: { authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Manifest fetch failed (${res.status}): ${body}`);
+  }
+  return res.json();
+}
+
+function resolveCommand(manifest, override) {
+  // Local override: `--runtime-cmd "node /path/to/run.mjs"` or
+  // $ATHENA_RUNTIME_CMD. Used for smoke-testing before the runtime
+  // packages are published to npm.
+  const ov = override || process.env.ATHENA_RUNTIME_CMD;
+  if (ov) {
+    const [cmd, ...args] = ov.split(/\s+/).filter(Boolean);
+    return { cmd, args };
+  }
+  const { kind, entrypoint } = manifest.runtime;
+  switch (kind) {
+    case "anthropic_sdk":
+    case "openclaw":
+      // npm-distributed runtimes — spawn via npx.
+      return { cmd: "npx", args: ["-y", entrypoint] };
+    case "hermes":
+      // Hermes Agent (Nous Research) is distributed via
+      // `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`,
+      // not npm. The entrypoint is just the binary name on $PATH (`hermes`
+      // by default). If the user customized entrypoint to a path, honor that.
+      return { cmd: entrypoint || "hermes", args: [] };
+    default:
+      throw new Error(`Unsupported runtime kind: ${kind}`);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args._[0] === "setup") {
+    await runSetup();
+    return;
+  }
+
+  if (args.help || args._[0] !== "run" || !args._[1]) {
+    usage();
+    process.exit(args.help ? 0 : 2);
+  }
+
+  const agentId = args._[1];
+  const creds = loadCredsFile();
+  const baseUrl =
+    args.baseUrl || process.env.ATHENA_BASE_URL || creds.base_url || DEFAULT_BASE_URL;
+  const apiKey = args.apiKey || process.env.ATHENA_API_KEY || creds.api_key;
+
+  if (!apiKey) {
+    process.stderr.write(
+      "Error: no API key. Pass --api-key ak_..., set $ATHENA_API_KEY, " +
+        "or write {\"api_key\": \"ak_...\"} to ~/.athena/credentials.json\n",
+    );
+    process.exit(2);
+  }
+
+  let manifest;
+  try {
+    manifest = await fetchManifest({ baseUrl, agentId, apiKey });
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (args.manifestOnly) {
+    process.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+    process.exit(0);
+  }
+
+  let { cmd, args: cmdArgs } = resolveCommand(manifest, args.runtimeCmd);
+  // Prepend ~/.local/bin to PATH so newly-installed Hermes (and other tools
+  // that drop binaries there) are findable in the spawned child without
+  // requiring the user to reload their shell.
+  const userLocalBin = join(homedir(), ".local", "bin");
+  const augmentedPath = `${userLocalBin}:${process.env.PATH || ""}`;
+  let env = {
+    ...process.env,
+    ...manifest.env,
+    PATH: augmentedPath,
+    ATHENA_API_KEY: apiKey,
+  };
+
+  // Hermes-specific preflight + pre-configuration:
+  //   1. Verify `hermes` is on PATH (give a clear install hint if not).
+  //   2. Fetch the rendered cli-config.yaml from Athena and write it to a
+  //      per-agent state dir.
+  //   3. Override HOME to that state dir so Hermes reads our config instead
+  //      of any pre-existing user config — and skills/memory persist there.
+  //   4. Set ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY to the Athena proxy +
+  //      the per-agent ak_ key. Hermes's anthropic provider picks these up.
+  if (manifest.runtime.kind === "hermes" && cmd === "hermes") {
+    const hermesPath = await ensureHermesInstalled();
+    if (!hermesPath) process.exit(127);
+    // Use the absolute path we resolved so spawn() doesn't fail with ENOENT
+    // when ~/.local/bin isn't on the parent's PATH yet.
+    cmd = hermesPath;
+
+    // Hermes data directory — respects $HERMES_HOME, defaults to ~/.hermes.
+    // We give each Athena agent its own HERMES_HOME so configs, skills, and
+    // memory stay isolated. The python code path (~/.hermes/hermes-agent) is
+    // resolved by the launcher script at install time, so HERMES_HOME only
+    // affects where Hermes looks for runtime data — not its own code.
+    const hermesHome = join(homedir(), ".athena", "hermes", agentId);
+    mkdirSync(hermesHome, { recursive: true });
+
+    const cfgRes = await fetch(
+      `${baseUrl}/api/agents/${agentId}/hermes-config`,
+      { headers: { authorization: `Bearer ${apiKey}` } },
+    );
+    if (!cfgRes.ok) {
+      process.stderr.write(
+        `[athena-agent] failed to fetch hermes config (${cfgRes.status}): ${await cfgRes.text()}\n`,
+      );
+      process.exit(1);
+    }
+    const yaml = await cfgRes.text();
+    // Hermes reads config from $HERMES_HOME/config.yaml at runtime.
+    // The .example file in the repo is named cli-config.yaml.example but gets
+    // installed as config.yaml — we have to match that.
+    writeFileSync(join(hermesHome, "config.yaml"), yaml, "utf8");
+    process.stderr.write(`[athena-agent] wrote hermes config to ${hermesHome}/config.yaml\n`);
+
+    const anthropicBase =
+      manifest.env?.ATHENA_ANTHROPIC_URL || manifest.gateway_url;
+    env = {
+      ...env,
+      HERMES_HOME: hermesHome,
+      ANTHROPIC_BASE_URL: anthropicBase,
+      ANTHROPIC_API_KEY: apiKey,
+    };
+  }
+
+  process.stderr.write(
+    `[athena-agent] spawning ${manifest.runtime.kind}@${manifest.runtime.version} ` +
+      `for agent ${agentId}\n`,
+  );
+
+  const child = spawn(cmd, cmdArgs, { stdio: "inherit", env });
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err.stack || err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "athena-agent-launcher",
+  "version": "0.1.0",
+  "description": "Run an Athena-configured agent locally. Resolves runtime + bindings from the Athena control plane and spawns the correct agent binary (Anthropic SDK, OpenClaw, or Hermes).",
+  "type": "module",
+  "bin": {
+    "athena-agent": "bin/launcher.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonance-tech/prometheus.git"
+  },
+  "keywords": [
+    "athena",
+    "sonance",
+    "ai-agent",
+    "anthropic",
+    "hermes"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}