athena-agent-launcher 0.1.0 → 0.3.0

package/README.md

@@ -3,11 +3,11 @@
 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
+# Run an agent — first run auto-prompts for credentials if missing
 npx athena-agent-launcher run <agent-id>
+
+# Optional: re-run setup later to change credentials
+npx athena-agent-launcher setup
 ```
 
 For `hermes` runtime agents, the launcher will auto-install the Hermes binary

package/bin/launcher.mjs

@@ -14,6 +14,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync } from "n
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import readline from "node:readline";
+import { startWebChat } from "../lib/webchat.mjs";
 
 const DEFAULT_BASE_URL = "https://athena-v2-pi.vercel.app";
 
@@ -180,6 +181,83 @@ async function ensureHermesInstalled() {
   return await locateHermes();
 }
 
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// Open a URL in the user's default browser (best-effort, cross-platform).
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const cmdArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, cmdArgs, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* best-effort; the URL is also printed */
+  }
+}
+
+// SSO device pairing: open the browser to authorize, poll until a key bound to
+// the verified identity is issued. Returns the ak_ key.
+async function pairAndGetKey(baseUrl, agentId) {
+  const startRes = await fetch(`${baseUrl}/api/launcher/pair/start`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ agent_id: agentId }),
+  });
+  if (!startRes.ok) {
+    throw new Error(`pair/start failed (${startRes.status}): ${await startRes.text()}`);
+  }
+  const { device_code, user_code, verification_url } = await startRes.json();
+  process.stderr.write(
+    `\n[athena-agent] Sign in with your Sonance account to authorize this device:\n` +
+      `\n    ${verification_url}\n\n` +
+      `  (opening your browser… code: ${user_code})\n\n`,
+  );
+  openBrowser(verification_url);
+
+  const deadline = Date.now() + 10 * 60 * 1000;
+  let notified = false;
+  while (Date.now() < deadline) {
+    await sleep(3000);
+    let j;
+    try {
+      const pollRes = await fetch(`${baseUrl}/api/launcher/pair/poll`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ device_code }),
+      });
+      j = await pollRes.json();
+    } catch {
+      continue; // transient network blip — keep polling
+    }
+    if (j.status === "approved" && j.api_key) {
+      process.stderr.write("[athena-agent] ✓ authorized.\n");
+      return j.api_key;
+    }
+    if (j.status === "denied") throw new Error(`Authorization denied: ${j.error || "no access"}`);
+    if (j.status === "expired") throw new Error("Pairing expired — run the command again.");
+    if (!notified && j.status === "pending") {
+      process.stderr.write("[athena-agent] waiting for you to approve in the browser…\n");
+      notified = true;
+    }
+  }
+  throw new Error("Pairing timed out — run the command again.");
+}
+
+// Persist a per-agent key (new format) without clobbering other agents' keys
+// or the legacy flat `api_key`.
+function saveAgentKey(agentId, apiKey, baseUrl) {
+  const credsPath = join(homedir(), ".athena", "credentials.json");
+  const creds = loadCredsFile();
+  if (!creds.base_url) creds.base_url = baseUrl;
+  creds.agent_keys = creds.agent_keys || {};
+  creds.agent_keys[agentId] = apiKey;
+  mkdirSync(dirname(credsPath), { recursive: true });
+  writeFileSync(credsPath, JSON.stringify(creds, null, 2), "utf8");
+  chmodSync(credsPath, 0o600);
+}
+
 async function fetchManifest({ baseUrl, agentId, apiKey }) {
   const res = await fetch(`${baseUrl}/api/agents/${agentId}/launcher-manifest`, {
     headers: { authorization: `Bearer ${apiKey}` },
@@ -234,12 +312,33 @@ async function main() {
   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;
+  // Key precedence: explicit flag/env > per-agent saved key > legacy flat key.
+  let apiKey =
+    args.apiKey ||
+    process.env.ATHENA_API_KEY ||
+    creds.agent_keys?.[agentId] ||
+    creds.api_key;
+
+  // No saved key for this agent → authorize this device via Sonance SSO. The
+  // browser flow verifies the user's Okta identity and (if they hold an access
+  // grant) hands back a key bound to their account, which we cache per-agent.
+  if (!apiKey && !args.apiKey) {
+    process.stderr.write(
+      `[athena-agent] no saved key for ${agentId} — starting SSO authorization.\n`,
+    );
+    try {
+      apiKey = await pairAndGetKey(baseUrl, agentId);
+    } catch (err) {
+      process.stderr.write(`[athena-agent] ${err.message}\n`);
+      process.exit(1);
+    }
+    saveAgentKey(agentId, apiKey, baseUrl);
+  }
 
   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",
+        "or run without flags to authorize via Sonance SSO.\n",
     );
     process.exit(2);
   }
@@ -248,8 +347,33 @@ async function main() {
   try {
     manifest = await fetchManifest({ baseUrl, agentId, apiKey });
   } catch (err) {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
+    // A saved key that's been revoked server-side returns 401 — re-authorize
+    // via SSO once and retry, unless the key was supplied explicitly.
+    if (/\(401\)/.test(err.message) && !args.apiKey && !process.env.ATHENA_API_KEY) {
+      process.stderr.write(
+        "[athena-agent] saved key was rejected (revoked?) — re-authorizing via SSO.\n",
+      );
+      try {
+        apiKey = await pairAndGetKey(baseUrl, agentId);
+        saveAgentKey(agentId, apiKey, baseUrl);
+        manifest = await fetchManifest({ baseUrl, agentId, apiKey });
+      } catch (err2) {
+        process.stderr.write(`[athena-agent] ${err2.message}\n`);
+        process.exit(1);
+      }
+    } else {
+      // `fetch failed` from undici is opaque on its own — the real cause
+      // (ENOTFOUND, ECONNREFUSED, TLS, etc.) lives on err.cause.
+      const cause = err?.cause
+        ? ` (${err.cause.code || err.cause.message || err.cause})`
+        : "";
+      process.stderr.write(
+        `[athena-agent] ${err.message}${cause}\n` +
+          `  base URL: ${baseUrl}\n` +
+          `  agent:    ${agentId}\n`,
+      );
+      process.exit(1);
+    }
   }
 
   if (args.manifestOnly) {
@@ -312,12 +436,77 @@ async function main() {
 
     const anthropicBase =
       manifest.env?.ATHENA_ANTHROPIC_URL || manifest.gateway_url;
+
+    // Hermes credential precedence: HERMES_HOME/auth.json > ~/.hermes/auth.json
+    // > env vars. We write an agent-scoped auth.json with the ak_ key at
+    // priority 100 so it beats any global OAuth credential (Claude Code's
+    // sk-ant-oat01 token lives in ~/.hermes/auth.json at priority 0 and would
+    // otherwise silently override everything we set in .env or the environment).
+    const authJson = {
+      version: 1,
+      providers: {},
+      active_provider: null,
+      updated_at: new Date().toISOString(),
+      credential_pool: {
+        anthropic: [
+          {
+            id: "athena-agent",
+            label: "athena_ak",
+            auth_type: "api_key",
+            priority: 100,
+            source: "athena",
+            api_key: apiKey,
+            base_url: anthropicBase,
+          },
+        ],
+      },
+    };
+    const authPath = join(hermesHome, "auth.json");
+    writeFileSync(authPath, JSON.stringify(authJson, null, 2), "utf8");
+    chmodSync(authPath, 0o600);
+
+    // Also write .env for belt-and-suspenders (some Hermes versions read this
+    // before auth.json for base URL; others do not — cover both).
+    const dotenvPath = join(hermesHome, ".env");
+    writeFileSync(
+      dotenvPath,
+      `ANTHROPIC_API_KEY=${apiKey}\nANTHROPIC_BASE_URL=${anthropicBase}\nANTHROPIC_TOKEN=\n`,
+      "utf8",
+    );
+    chmodSync(dotenvPath, 0o600);
+    process.stderr.write(`[athena-agent] wrote auth to ${hermesHome}/{auth.json,.env}\n`);
+
     env = {
       ...env,
       HERMES_HOME: hermesHome,
       ANTHROPIC_BASE_URL: anthropicBase,
       ANTHROPIC_API_KEY: apiKey,
+      ANTHROPIC_TOKEN: "",
     };
+
+    // Web Chat gateway: run Hermes headless in ACP mode behind a local browser
+    // chat instead of the interactive terminal TUI. startWebChat owns the
+    // hermes child + local server and keeps the process alive.
+    if (manifest.web_chat?.enabled) {
+      const webchat = await startWebChat({
+        hermesBin: cmd,
+        env,
+        hermesHome,
+        webChat: manifest.web_chat,
+      });
+      process.stderr.write(
+        `\n[athena-agent] 💬 Web chat ready → ${webchat.url}\n` +
+          `[athena-agent] Hermes is running headless (ACP). Chat in your browser.\n` +
+          `[athena-agent] Press Ctrl+C to stop.\n\n`,
+      );
+      const shutdown = () => {
+        webchat.close();
+        process.exit(0);
+      };
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+      return;
+    }
   }
 
   process.stderr.write(

package/lib/webchat-ui.html

@@ -0,0 +1,211 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>__TITLE__</title>
+<style>
+  :root {
+    --bg: #0b0d12; --bg2: #12151c; --bg3: #1a1f2a; --border: #232a36;
+    --fg: #e6e9ef; --fg2: #aab2c0; --fg3: #6b7385;
+    --accent: #6ea8fe; --accent-fg: #0b0d12;
+    --user: #1f2a3d; --tool: #15202e; --err: #ff6b6b;
+  }
+  :root[data-theme="light"] {
+    --bg: #f6f7f9; --bg2: #ffffff; --bg3: #eef1f5; --border: #dce1e8;
+    --fg: #1a1f2a; --fg2: #495060; --fg3: #8a91a0;
+    --accent: #2f6fed; --accent-fg: #ffffff;
+    --user: #e6eefc; --tool: #eef1f5; --err: #d23b3b;
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    background: var(--bg); color: var(--fg);
+    font: 14px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    display: flex; flex-direction: column;
+  }
+  header {
+    display: flex; align-items: center; gap: 10px;
+    padding: 12px 18px; border-bottom: 1px solid var(--border); background: var(--bg2);
+  }
+  header .dot { width: 9px; height: 9px; border-radius: 50%; background: var(--fg3); flex: none; }
+  header .dot.on { background: #36d399; box-shadow: 0 0 8px #36d39988; }
+  header h1 { font-size: 14px; font-weight: 600; margin: 0; }
+  header .status { margin-left: auto; font-size: 12px; color: var(--fg3); }
+  #log { flex: 1; overflow-y: auto; padding: 22px 0; }
+  .wrap { max-width: 820px; margin: 0 auto; padding: 0 18px; }
+  .msg { margin: 14px 0; display: flex; gap: 12px; }
+  .msg .who { font-size: 11px; text-transform: uppercase; letter-spacing: .04em; color: var(--fg3); width: 64px; flex: none; padding-top: 3px; }
+  .msg .body { flex: 1; min-width: 0; white-space: pre-wrap; word-wrap: break-word; }
+  .msg.user .body { background: var(--user); border-radius: 10px; padding: 8px 12px; }
+  .tool { background: var(--tool); border: 1px solid var(--border); border-radius: 8px; padding: 8px 12px; margin: 8px 0; font-size: 13px; color: var(--fg2); }
+  .tool .t-title { font-weight: 600; color: var(--fg); }
+  .tool .t-status { font-size: 11px; color: var(--fg3); }
+  .perm { background: var(--bg3); border: 1px solid var(--accent); border-radius: 8px; padding: 12px; margin: 8px 0; }
+  .perm .q { margin-bottom: 8px; }
+  .perm button { margin-right: 8px; }
+  .err { color: var(--err); }
+  footer { border-top: 1px solid var(--border); background: var(--bg2); padding: 14px 18px; }
+  .composer { max-width: 820px; margin: 0 auto; display: flex; gap: 10px; }
+  textarea {
+    flex: 1; resize: none; background: var(--bg3); color: var(--fg);
+    border: 1px solid var(--border); border-radius: 10px; padding: 10px 12px;
+    font: inherit; max-height: 160px; outline: none;
+  }
+  textarea:focus { border-color: var(--accent); }
+  button {
+    background: var(--accent); color: var(--accent-fg); border: 0; border-radius: 10px;
+    padding: 0 18px; font: inherit; font-weight: 600; cursor: pointer;
+  }
+  button:disabled { opacity: .5; cursor: default; }
+  button.ghost { background: var(--bg3); color: var(--fg); border: 1px solid var(--border); }
+  .blink::after { content: "▋"; animation: blink 1s step-start infinite; color: var(--fg3); }
+  @keyframes blink { 50% { opacity: 0; } }
+</style>
+</head>
+<body>
+<header>
+  <span class="dot" id="dot"></span>
+  <h1 id="title">__TITLE__</h1>
+  <span class="status" id="status">connecting…</span>
+</header>
+<div id="log"><div class="wrap" id="logwrap"></div></div>
+<footer>
+  <div class="composer">
+    <textarea id="input" rows="1" placeholder="Message your agent…" autofocus></textarea>
+    <button id="send" disabled>Send</button>
+  </div>
+</footer>
+<script>
+const CONFIG = __CONFIG__;
+const log = document.getElementById("logwrap");
+const input = document.getElementById("input");
+const sendBtn = document.getElementById("send");
+const dot = document.getElementById("dot");
+const statusEl = document.getElementById("status");
+const titleEl = document.getElementById("title");
+
+titleEl.textContent = CONFIG.title || "Hermes Agent";
+document.title = CONFIG.title || "Hermes Agent";
+if (CONFIG.theme === "light" || CONFIG.theme === "dark") {
+  document.documentElement.setAttribute("data-theme", CONFIG.theme);
+} else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches) {
+  document.documentElement.setAttribute("data-theme", "light");
+}
+
+let turnActive = false;
+let curAssistant = null;        // current streaming assistant .body element
+const toolEls = new Map();      // toolCallId -> element
+
+function scroll() { const l = document.getElementById("log"); l.scrollTop = l.scrollHeight; }
+
+function addMsg(who, cls) {
+  const m = document.createElement("div");
+  m.className = "msg " + (cls || "");
+  const w = document.createElement("div"); w.className = "who"; w.textContent = who;
+  const b = document.createElement("div"); b.className = "body";
+  m.append(w, b); log.append(m); scroll();
+  return b;
+}
+
+function setBusy(b) {
+  turnActive = b;
+  sendBtn.disabled = b || !input.value.trim();
+  input.disabled = b;
+  statusEl.textContent = b ? "thinking…" : "ready";
+}
+
+if (CONFIG.welcome_message) addMsg("Agent", "").textContent = CONFIG.welcome_message;
+
+// ---- streaming connection -------------------------------------------------
+const es = new EventSource("/chat/stream");
+es.onopen = () => { dot.classList.add("on"); statusEl.textContent = "ready"; sendBtn.disabled = !input.value.trim(); };
+es.onerror = () => { dot.classList.remove("on"); statusEl.textContent = "disconnected"; };
+es.onmessage = (e) => {
+  let ev; try { ev = JSON.parse(e.data); } catch { return; }
+  handle(ev);
+};
+
+function handle(ev) {
+  switch (ev.type) {
+    case "ready":
+      statusEl.textContent = "ready"; break;
+    case "assistant_chunk":
+      if (!curAssistant) { curAssistant = addMsg("Agent", ""); curAssistant.classList.add("blink"); }
+      curAssistant.textContent += ev.text; scroll(); break;
+    case "tool": {
+      const el = document.createElement("div");
+      el.className = "tool";
+      el.innerHTML = '<span class="t-title"></span> <span class="t-status"></span>';
+      el.querySelector(".t-title").textContent = ev.title || ev.id;
+      el.querySelector(".t-status").textContent = "· " + (ev.status || "pending");
+      log.append(el); toolEls.set(ev.id, el); scroll(); break;
+    }
+    case "tool_update": {
+      const el = toolEls.get(ev.id);
+      if (el) el.querySelector(".t-status").textContent = "· " + ev.status; break;
+    }
+    case "permission":
+      renderPermission(ev); break;
+    case "turn_done":
+      if (curAssistant) curAssistant.classList.remove("blink");
+      curAssistant = null; setBusy(false); input.focus(); break;
+    case "error": {
+      const b = addMsg("Error", ""); b.classList.add("err"); b.textContent = ev.message || "unknown error";
+      if (curAssistant) curAssistant.classList.remove("blink");
+      curAssistant = null; setBusy(false); break;
+    }
+  }
+}
+
+function renderPermission(ev) {
+  const el = document.createElement("div");
+  el.className = "perm";
+  const q = document.createElement("div"); q.className = "q";
+  q.textContent = "Allow tool: " + (ev.title || "tool") + "?";
+  el.append(q);
+  (ev.options || []).forEach((o) => {
+    const btn = document.createElement("button");
+    if (/reject|deny|no/i.test(o.kind || o.name || "")) btn.className = "ghost";
+    btn.textContent = o.name || o.optionId;
+    btn.onclick = () => {
+      fetch("/chat/permission", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ requestId: ev.requestId, optionId: o.optionId }),
+      });
+      el.querySelectorAll("button").forEach((b) => (b.disabled = true));
+      q.textContent = "→ " + (o.name || o.optionId);
+    };
+    el.append(btn);
+  });
+  log.append(el); scroll();
+}
+
+// ---- composer -------------------------------------------------------------
+function send() {
+  const text = input.value.trim();
+  if (!text || turnActive) return;
+  addMsg("You", "user").textContent = text;
+  input.value = ""; autosize();
+  setBusy(true);
+  fetch("/chat/send", {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ text }),
+  }).catch((err) => {
+    const b = addMsg("Error", ""); b.classList.add("err"); b.textContent = String(err);
+    setBusy(false);
+  });
+}
+
+function autosize() {
+  input.style.height = "auto";
+  input.style.height = Math.min(input.scrollHeight, 160) + "px";
+}
+input.addEventListener("input", () => { autosize(); if (!turnActive) sendBtn.disabled = !input.value.trim(); });
+input.addEventListener("keydown", (e) => {
+  if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); send(); }
+});
+sendBtn.addEventListener("click", send);
+</script>
+</body>
+</html>

package/lib/webchat.mjs

@@ -0,0 +1,291 @@
+// Web Chat bridge for Hermes agents.
+//
+// Spawns `hermes acp` (headless ACP stdio server), opens a localhost HTTP
+// server that serves the chat UI and bridges browser ⇄ Hermes over the Agent
+// Client Protocol, and opens the user's browser to it. Everything is local —
+// there is no tunnel back to Athena.
+//
+//   browser ──HTTP/SSE──► local server ──ACP JSON-RPC/stdio──► hermes acp
+//
+// Proven viable by services/launcher/scripts/acp-poc.mjs.
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const UI_HTML = readFileSync(join(__dirname, "webchat-ui.html"), "utf8");
+
+// ---- ACP client over a hermes acp child -----------------------------------
+class AcpClient {
+  constructor(hermesBin, env) {
+    this.child = spawn(hermesBin, ["acp", "--accept-hooks"], {
+      stdio: ["pipe", "pipe", "inherit"],
+      env,
+    });
+    this.nextId = 1;
+    this.pending = new Map();          // jsonrpc id -> {resolve, reject}
+    this.permissionWaiters = new Map(); // requestId -> resolve(optionId|null)
+    this.sessionId = null;
+    this.buf = "";
+    // Event sink set by the server: (event) => void
+    this.onEvent = () => {};
+    // Permission policy: "auto" | "ask"
+    this.toolApproval = "auto";
+
+    this.child.stdout.on("data", (c) => this._onData(c));
+    this.child.on("exit", (code) =>
+      this.onEvent({ type: "error", message: `Hermes exited (code ${code})` }),
+    );
+  }
+
+  _send(obj) {
+    this.child.stdin.write(JSON.stringify(obj) + "\n");
+  }
+
+  _request(method, params) {
+    const id = this.nextId++;
+    this._send({ jsonrpc: "2.0", id, method, params });
+    return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+  }
+
+  _onData(chunk) {
+    this.buf += chunk.toString("utf8");
+    let nl;
+    while ((nl = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, nl).trim();
+      this.buf = this.buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // non-JSON banner line on stdout — ignore
+      }
+      this._handle(msg);
+    }
+  }
+
+  _handle(msg) {
+    // Response to one of our requests.
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const p = this.pending.get(msg.id);
+      if (p) {
+        this.pending.delete(msg.id);
+        if (msg.error) p.reject(new Error(JSON.stringify(msg.error)));
+        else p.resolve(msg.result);
+      }
+      return;
+    }
+    // Request from the agent that we must answer.
+    if (msg.id !== undefined && msg.method) {
+      this._onAgentRequest(msg);
+      return;
+    }
+    // Notification.
+    if (msg.method === "session/update") this._onUpdate(msg.params?.update);
+  }
+
+  _onUpdate(u) {
+    if (!u) return;
+    switch (u.sessionUpdate) {
+      case "agent_message_chunk":
+        if (u.content?.text) this.onEvent({ type: "assistant_chunk", text: u.content.text });
+        break;
+      case "tool_call":
+        this.onEvent({
+          type: "tool",
+          id: u.toolCallId,
+          title: u.title || u.toolCallId,
+          status: u.status || "pending",
+        });
+        break;
+      case "tool_call_update":
+        if (u.status)
+          this.onEvent({ type: "tool_update", id: u.toolCallId, status: u.status });
+        break;
+      default:
+        break; // agent_thought_chunk, plan, etc. — ignored for now
+    }
+  }
+
+  async _onAgentRequest(msg) {
+    if (msg.method === "session/request_permission") {
+      const opts = msg.params?.options || [];
+      const title = msg.params?.toolCall?.title || msg.params?.toolCall?.toolCallId || "tool";
+      if (this.toolApproval === "auto") {
+        const allow = opts.find((o) => /allow/i.test(o.kind || o.optionId || "")) || opts[0];
+        this._send({
+          jsonrpc: "2.0",
+          id: msg.id,
+          result: { outcome: allow ? { outcome: "selected", optionId: allow.optionId } : { outcome: "cancelled" } },
+        });
+        return;
+      }
+      // ask: surface to the browser and wait for a decision.
+      const requestId = String(msg.id);
+      this.onEvent({ type: "permission", requestId, title, options: opts });
+      const optionId = await new Promise((resolve) => this.permissionWaiters.set(requestId, resolve));
+      this._send({
+        jsonrpc: "2.0",
+        id: msg.id,
+        result: { outcome: optionId ? { outcome: "selected", optionId } : { outcome: "cancelled" } },
+      });
+      return;
+    }
+    // fs/* and terminal/* — we declared no such capabilities; decline cleanly.
+    this._send({
+      jsonrpc: "2.0",
+      id: msg.id,
+      error: { code: -32601, message: `web chat does not implement ${msg.method}` },
+    });
+  }
+
+  resolvePermission(requestId, optionId) {
+    const w = this.permissionWaiters.get(requestId);
+    if (w) {
+      this.permissionWaiters.delete(requestId);
+      w(optionId || null);
+    }
+  }
+
+  async init(cwd) {
+    await this._request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "athena-web-chat", title: "Athena Web Chat", version: "0.1.0" },
+    });
+    const ns = await this._request("session/new", { cwd, mcpServers: [] });
+    this.sessionId = ns?.sessionId;
+    return this.sessionId;
+  }
+
+  async prompt(text) {
+    return this._request("session/prompt", {
+      sessionId: this.sessionId,
+      prompt: [{ type: "text", text }],
+    });
+  }
+
+  kill() {
+    try { this.child.kill("SIGTERM"); } catch {}
+  }
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin" ? "open" :
+    process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (c) => (data += c));
+    req.on("end", () => {
+      try { resolve(JSON.parse(data || "{}")); } catch { resolve({}); }
+    });
+  });
+}
+
+/**
+ * Start the web chat. Resolves once the server is listening.
+ * @returns {Promise<{url: string, close: () => void}>}
+ */
+export async function startWebChat({ hermesBin, env, hermesHome, webChat }) {
+  const acp = new AcpClient(hermesBin, env);
+  acp.toolApproval = webChat.tool_approval === "ask" ? "ask" : "auto";
+
+  process.stderr.write("[athena-agent] starting Hermes in ACP mode for web chat…\n");
+  await acp.init(hermesHome);
+  process.stderr.write(`[athena-agent] ACP session ready (${acp.sessionId})\n`);
+
+  const sseClients = new Set();
+  let turnActive = false;
+  acp.onEvent = (event) => {
+    const line = `data: ${JSON.stringify(event)}\n\n`;
+    for (const res of sseClients) res.write(line);
+  };
+
+  const page = UI_HTML
+    .replaceAll("__TITLE__", (webChat.title || "Hermes Agent").replace(/[<>]/g, ""))
+    .replace("__CONFIG__", JSON.stringify({
+      title: webChat.title || "Hermes Agent",
+      welcome_message: webChat.welcome_message || "",
+      theme: webChat.theme || "auto",
+      tool_approval: acp.toolApproval,
+    }));
+
+  const server = createServer(async (req, res) => {
+    const url = (req.url || "/").split("?")[0];
+
+    if (req.method === "GET" && url === "/") {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(page);
+      return;
+    }
+
+    if (req.method === "GET" && url === "/chat/stream") {
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+      });
+      res.write(`data: ${JSON.stringify({ type: "ready" })}\n\n`);
+      sseClients.add(res);
+      req.on("close", () => sseClients.delete(res));
+      return;
+    }
+
+    if (req.method === "POST" && url === "/chat/send") {
+      const body = await readBody(req);
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) { res.writeHead(400).end('{"error":"text required"}'); return; }
+      if (turnActive) { res.writeHead(409).end('{"error":"a turn is already in progress"}'); return; }
+      turnActive = true;
+      res.writeHead(202, { "content-type": "application/json" });
+      res.end('{"ok":true}');
+      acp.prompt(text)
+        .then((r) => acp.onEvent({ type: "turn_done", stopReason: r?.stopReason || "end_turn" }))
+        .catch((err) => acp.onEvent({ type: "error", message: err.message }))
+        .finally(() => { turnActive = false; });
+      return;
+    }
+
+    if (req.method === "POST" && url === "/chat/permission") {
+      const body = await readBody(req);
+      acp.resolvePermission(String(body.requestId), body.optionId);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end('{"ok":true}');
+      return;
+    }
+
+    res.writeHead(404).end("not found");
+  });
+
+  const preferred = webChat.preferred_port;
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(Number.isFinite(preferred) && preferred ? preferred : 0, "127.0.0.1", resolve);
+  });
+
+  const port = server.address().port;
+  const chatUrl = `http://127.0.0.1:${port}`;
+
+  function close() {
+    acp.kill();
+    server.close();
+  }
+  acp.child.on("exit", () => server.close());
+
+  if (webChat.auto_open_browser !== false) openBrowser(chatUrl);
+  return { url: chatUrl, close };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "athena-agent-launcher",
-  "version": "0.1.0",
+  "version": "0.3.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": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin",
+    "lib",
     "README.md"
   ],
   "engines": {