athena-agent-launcher 0.3.2 → 0.3.4

package/bin/launcher.mjs

@@ -15,6 +15,7 @@ import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import readline from "node:readline";
 import { startWebChat } from "../lib/webchat.mjs";
+import { startHostedGateway } from "../lib/hosted-gateway.mjs";
 
 const DEFAULT_BASE_URL = "https://athena-v2-pi.vercel.app";
 
@@ -472,8 +473,13 @@ async function main() {
     const hermesHome = join(homedir(), ".athena", "hermes", agentId);
     mkdirSync(hermesHome, { recursive: true });
 
+    // Tell the config route which launch mode this is. Web chat (ACP) is an
+    // attended/interactive session, so it identifies itself differently from an
+    // unattended TUI/headless loop — this lets Cortex's protection layer treat
+    // human-driven web-chat tool calls distinctly. See hermes-config.ts.
+    const launchMode = manifest.web_chat?.enabled ? "web_chat" : "cli";
     const cfgRes = await fetch(
-      `${baseUrl}/api/agents/${agentId}/hermes-config`,
+      `${baseUrl}/api/agents/${agentId}/hermes-config?mode=${encodeURIComponent(launchMode)}`,
       { headers: { authorization: `Bearer ${apiKey}` } },
     );
     if (!cfgRes.ok) {
@@ -539,6 +545,37 @@ async function main() {
       ANTHROPIC_TOKEN: "",
     };
 
+    // Hosted gateway (DAE-6): unattended container mode. Run Hermes headless in
+    // ACP mode behind an internet-facing HTTP API (/health, /message) that the
+    // Athena Teams turn route calls — NOT the interactive TUI (which exits with
+    // "Input is not a terminal (fd=0)" in a container and crash-loops).
+    // Selected by manifest.hosted_gateway.enabled, or by the container setting
+    // ATHENA_HOSTED_GATEWAY_ENABLED=1 (so the ACA can opt in via env even before
+    // the manifest route carries the flag). Takes precedence over web chat.
+    const hostedGatewayEnabled =
+      manifest.hosted_gateway?.enabled === true ||
+      /^(1|true|yes)$/i.test(env.ATHENA_HOSTED_GATEWAY_ENABLED || "");
+    if (hostedGatewayEnabled) {
+      const gw = await startHostedGateway({
+        hermesBin: cmd,
+        env,
+        hermesHome,
+        hostedGateway: manifest.hosted_gateway || {},
+      });
+      process.stderr.write(
+        `\n[athena-agent] 🛰  Hosted gateway listening on ${gw.url}\n` +
+          `[athena-agent] Hermes is running headless (ACP). POST /message to drive turns.\n` +
+          `[athena-agent] Press Ctrl+C to stop.\n\n`,
+      );
+      const shutdown = () => {
+        gw.close();
+        process.exit(0);
+      };
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+      return;
+    }
+
     // 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.

package/lib/acp-client.mjs

@@ -0,0 +1,235 @@
+// Shared ACP client for Hermes runtimes.
+//
+// Speaks the Agent Client Protocol (newline-delimited JSON-RPC 2.0) to a
+// `hermes acp --accept-hooks` child over stdio. Extracted verbatim from
+// webchat.mjs (DAE-6) so both the attended web-chat bridge and the unattended
+// hosted gateway share one battle-tested transport.
+//
+//   client ──ACP JSON-RPC/stdio──► hermes acp
+//
+// Two usage shapes are supported:
+//   1. Single-session (web chat): `await acp.init(cwd)` then `acp.prompt(text)`.
+//      Backwards-compatible with the original webchat.mjs API.
+//   2. Multi-session (hosted gateway): `await acp.initialize()` once, then
+//      `acp.newSession(cwd)` per logical session and `acp.prompt(text, sid)`.
+//
+// Every emitted event carries `sessionId` so a multi-session caller can route
+// chunks to the right turn. Single-session callers can ignore it.
+
+import { spawn } from "node:child_process";
+
+export 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;              // single-session convenience slot
+    this.buf = "";
+    // Event sink set by the server: (event) => void. Events include sessionId.
+    this.onEvent = () => {};
+    // Permission policy: "auto" | "ask". Unattended hosts MUST use "auto" —
+    // there is no human at the ACP layer to answer a permission prompt; the
+    // consent gate lives upstream (Teams turn route + hosted-start gate).
+    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, msg.params?.sessionId);
+    }
+  }
+
+  _onUpdate(u, sessionId) {
+    if (!u) return;
+    switch (u.sessionUpdate) {
+      case "agent_message_chunk":
+        if (u.content?.text)
+          this.onEvent({ type: "assistant_chunk", text: u.content.text, sessionId });
+        break;
+      case "tool_call":
+        this.onEvent({
+          type: "tool",
+          id: u.toolCallId,
+          title: u.title || u.toolCallId,
+          status: u.status || "pending",
+          sessionId,
+        });
+        break;
+      case "tool_call_update": {
+        const { isError, detail } = extractToolOutcome(u);
+        // A blocked/failed MCP call often arrives as status "completed" carrying
+        // an error *result* (e.g. the Cortex protection layer returns a JSON
+        // error body, not an ACP failure). Forward the extracted error so the
+        // UI doesn't render a blocked push as a green checkmark.
+        this.onEvent({
+          type: "tool_update",
+          id: u.toolCallId,
+          status: u.status || (isError ? "failed" : "completed"),
+          isError,
+          detail: isError ? detail : "",
+          sessionId,
+        });
+        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, sessionId: msg.params?.sessionId });
+      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: `client does not implement ${msg.method}` },
+    });
+  }
+
+  resolvePermission(requestId, optionId) {
+    const w = this.permissionWaiters.get(requestId);
+    if (w) {
+      this.permissionWaiters.delete(requestId);
+      w(optionId || null);
+    }
+  }
+
+  /** Send the ACP `initialize` handshake. Call once per child. */
+  async initialize() {
+    await this._request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "athena-acp-client", title: "Athena ACP Client", version: "0.1.0" },
+    });
+  }
+
+  /** Create a new ACP session; returns its sessionId. */
+  async newSession(cwd) {
+    const ns = await this._request("session/new", { cwd, mcpServers: [] });
+    return ns?.sessionId;
+  }
+
+  /** Single-session convenience: initialize + one session, stored on this.sessionId. */
+  async init(cwd) {
+    await this.initialize();
+    this.sessionId = await this.newSession(cwd);
+    return this.sessionId;
+  }
+
+  /** Drive a turn. `sessionId` defaults to the single-session slot. Resolves
+   *  with the ACP session/prompt result ({ stopReason }) when the turn ends. */
+  async prompt(text, sessionId) {
+    return this._request("session/prompt", {
+      sessionId: sessionId ?? this.sessionId,
+      prompt: [{ type: "text", text }],
+    });
+  }
+
+  kill() {
+    try { this.child.kill("SIGTERM"); } catch {}
+  }
+}
+
+// Pull human-readable output and an error flag out of an ACP tool_call_update.
+// ACP reports genuine failures as status "failed", but MCP tools that return an
+// error *result* (isError, or a JSON {error|success:false} body) are reported
+// "completed" — sniff those so blocked calls surface as failures.
+export function extractToolOutcome(u) {
+  let text = "";
+  for (const part of Array.isArray(u.content) ? u.content : []) {
+    const c = part?.content || part;
+    if (c?.type === "text" && typeof c.text === "string") text += c.text;
+  }
+  let isError = u.status === "failed";
+  const raw = u.rawOutput;
+  if (raw && typeof raw === "object") {
+    if (raw.isError === true) isError = true;
+    if (!text && Array.isArray(raw.content)) {
+      for (const c of raw.content) if (c?.type === "text" && c.text) text += c.text;
+    }
+    if (!text && typeof raw.error === "string") text = raw.error;
+  }
+  if (!isError && text) {
+    try {
+      const j = JSON.parse(text);
+      if (j && (j.error || j.success === false)) isError = true;
+    } catch {
+      /* not JSON — treat as a normal text result */
+    }
+  }
+  return { isError, detail: text.slice(0, 2000) };
+}

package/lib/hosted-gateway.mjs

@@ -0,0 +1,370 @@
+// Hosted gateway for Hermes agents (DAE-6).
+//
+// Unattended counterpart to webchat.mjs. Where web chat runs Hermes behind a
+// LOCAL browser UI for an attended user, the hosted gateway runs Hermes inside
+// a container (Azure Container App `agent003`) and exposes a small internet-
+// facing HTTP API that the Athena control plane's Teams turn route calls.
+//
+//   Athena /api/gateway/teams/turn ──HTTP /message──► hosted-gateway ──ACP──► hermes acp
+//
+// It does NOT spawn the interactive Hermes TUI (which exits with
+// "Input is not a terminal (fd=0)" in a container and crash-loops). It drives
+// `hermes acp --accept-hooks` via the shared AcpClient instead.
+//
+// Endpoints (see docs/design/teams-hermes-bridge.md for the full contract):
+//   GET  /health                       → 200 {"ok":true}  (no auth, no agent logic)
+//   POST /message {session_id, text}   → 200 {"text": "..."}
+//
+// Auth on /message — the locked DAE-6 / THE-5 contract (D1):
+//   Authorization: Bearer $HERMES_GATEWAY_SECRET      (timing-safe — M1)
+//   X-Hermes-Timestamp: <unix-ms>                     (≤60s skew — M2)
+//   X-Hermes-Signature: HMAC-SHA256(`${ts}.${rawBody}`, secret) hex   (M2)
+//   X-Request-Id: <uuid>   (Prometheus-minted; echoed in our logs — M7)
+// Plus a nonce/replay cache (M2), a token-bucket rate limit and a hard
+// max-concurrency (M6, default 1 for the pilot). If the secret env var is UNSET
+// the endpoint refuses to bring up agent logic (M1). All error bodies are
+// generic (no secret/body/upstream detail — M7). /health is unauthenticated by
+// design (Azure liveness/readiness probes) and runs no agent logic.
+
+import { createServer } from "node:http";
+import { timingSafeEqual, createHmac, randomUUID } from "node:crypto";
+import { AcpClient } from "./acp-client.mjs";
+
+const DEFAULT_PORT = 8080;
+const SESSION_IDLE_MS = 30 * 60 * 1000;     // evict ACP sessions idle > 30 min
+const SESSION_SWEEP_MS = 5 * 60 * 1000;      // sweep cadence
+const TURN_TIMEOUT_MS = 120_000;             // hard cap on a single turn
+const SKEW_MS = 60_000;                       // M2: max clock skew for the HMAC timestamp
+const REPLAY_TTL_MS = 120_000;                // M2: nonce cache window (> skew)
+const DEFAULT_RATE_PER_MIN = 30;              // M6: token-bucket refill
+const DEFAULT_MAX_CONCURRENCY = 1;            // M6: in-flight cap (pilot = 1) — load-bearing for arm custody, do NOT raise
+const BUSY_RETRY_AFTER_MS = 2000;             // DAE-16: hint the poller waits before retrying a busy container
+
+function sendJson(res, status, obj, headers) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...(headers || {}) });
+  res.end(body);
+}
+
+/** Read the raw request body as a string (needed verbatim for HMAC). */
+function readRawBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (c) => (data += c));
+    req.on("end", () => resolve(data));
+  });
+}
+
+/** Structured one-line log with the correlation id (M7). Never logs secrets,
+ *  signatures, the Authorization header, or request bodies. */
+function logEvent(o) {
+  try { process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), ...o }) + "\n"); } catch {}
+}
+
+/** Constant-time bearer check (M1). Unset secret → false (fail closed). */
+function bearerOk(req, secret) {
+  if (!secret) return false;
+  const auth = req.headers["authorization"] || "";
+  const token = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : "";
+  const a = Buffer.from(token);
+  const b = Buffer.from(secret);
+  if (a.length !== b.length) return false;
+  try { return timingSafeEqual(a, b); } catch { return false; }
+}
+
+/** Verify the HMAC request signature (M2): signature == HMAC-SHA256 over
+ *  `${X-Hermes-Timestamp}.${rawBody}`, within ±SKEW_MS. Timing-safe compare.
+ *  Returns { ok, reason?, sig? }. `sig` is the verified signature (used as the
+ *  replay nonce). */
+function hmacOk(req, rawBody, secret) {
+  const ts = req.headers["x-hermes-timestamp"];
+  const sig = req.headers["x-hermes-signature"];
+  if (!ts || !sig || typeof ts !== "string" || typeof sig !== "string") {
+    return { ok: false, reason: "missing_signature" };
+  }
+  const tsNum = Number(ts);
+  if (!Number.isFinite(tsNum)) return { ok: false, reason: "bad_timestamp" };
+  if (Math.abs(Date.now() - tsNum) > SKEW_MS) return { ok: false, reason: "timestamp_skew" };
+  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
+  const a = Buffer.from(sig);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return { ok: false, reason: "bad_signature" };
+  try {
+    if (!timingSafeEqual(a, b)) return { ok: false, reason: "bad_signature" };
+  } catch {
+    return { ok: false, reason: "bad_signature" };
+  }
+  return { ok: true, sig };
+}
+
+/**
+ * Start the hosted gateway. Resolves once the HTTP server is listening.
+ *
+ * @param {object} o
+ * @param {string} o.hermesBin   absolute path to the hermes binary
+ * @param {object} o.env         environment for the hermes child (HERMES_HOME etc.)
+ * @param {string} o.hermesHome  ACP session cwd
+ * @param {object} [o.hostedGateway]   manifest.hosted_gateway block (optional)
+ * @returns {Promise<{url:string, port:number, close:()=>void}>}
+ */
+export async function startHostedGateway({ hermesBin, env, hermesHome, hostedGateway = {} }) {
+  const secret = env.HERMES_GATEWAY_SECRET || process.env.HERMES_GATEWAY_SECRET || "";
+  const port = Number(env.PORT || process.env.PORT || hostedGateway.port || DEFAULT_PORT);
+
+  // M1 (THE-5): boot-refuse-if-unset. Without the secret we must NOT bring up
+  // any agent logic — no `hermes acp` child is spawned. /health stays up (so
+  // liveness probes don't crash-loop the container) but runs no agent logic;
+  // /message fails closed (503). The endpoint is internet-facing once ingress
+  // is on, so a misconfigured deploy must never reach Hermes.
+  if (!secret) {
+    process.stderr.write(
+      "[athena-agent] ⚠ HERMES_GATEWAY_SECRET is unset — refusing to start agent logic. " +
+        "/health up, /message FAILS CLOSED (503).\n",
+    );
+    const healthOnly = createServer((req, res) => {
+      const url = (req.url || "/").split("?")[0];
+      if (req.method === "GET" && url === "/health") return sendJson(res, 200, { ok: true });
+      if (req.method === "POST" && url === "/message")
+        return sendJson(res, 503, { error: "hosted gateway not configured (secret unset) — failing closed" });
+      return sendJson(res, 404, { error: "not found" });
+    });
+    await new Promise((resolve, reject) => {
+      healthOnly.once("error", reject);
+      healthOnly.listen(port, "0.0.0.0", resolve);
+    });
+    const p = healthOnly.address().port;
+    return { url: `http://0.0.0.0:${p}`, port: p, close: () => healthOnly.close() };
+  }
+
+  // One hermes acp child, many ACP sessions. ACP supports multiple sessions per
+  // connection (session/new returns a sessionId; session/prompt takes one), so
+  // a single child serves every Teams conversation that maps to this agent.
+  const acp = new AcpClient(hermesBin, env);
+  acp.toolApproval = "auto"; // unattended — no human at the ACP layer to approve
+
+  // Route assistant chunks to the in-flight turn for their session.
+  // turnState: acpSessionId -> { buf: string }
+  const turnState = new Map();
+  acp.onEvent = (event) => {
+    if (event.type === "assistant_chunk" && event.sessionId) {
+      const st = turnState.get(event.sessionId);
+      if (st) st.buf += event.text;
+    }
+    if (event.type === "error") {
+      process.stderr.write(`[athena-agent] hosted-gateway ACP error: ${event.message}\n`);
+    }
+  };
+
+  process.stderr.write("[athena-agent] starting Hermes in ACP mode for hosted gateway…\n");
+  await acp.initialize();
+  process.stderr.write("[athena-agent] ACP initialized.\n");
+
+  // session_id (from Athena) -> { acpSessionId, lastUsed, chain }
+  // `chain` serializes turns within a session: ACP allows one prompt per
+  // session at a time, so concurrent /message calls for the same session_id
+  // queue behind each other rather than interleaving on the same ACP session.
+  const sessions = new Map();
+
+  async function ensureSession(externalId) {
+    let s = sessions.get(externalId);
+    if (!s) {
+      const acpSessionId = await acp.newSession(hermesHome);
+      if (!acpSessionId) throw new Error("session/new returned no sessionId");
+      s = { acpSessionId, lastUsed: Date.now(), chain: Promise.resolve() };
+      sessions.set(externalId, s);
+      process.stderr.write(
+        `[athena-agent] new ACP session ${acpSessionId} for ${externalId}\n`,
+      );
+    }
+    s.lastUsed = Date.now();
+    return s;
+  }
+
+  /** Drive one turn on an ACP session, accumulating chunks until the prompt
+   *  resolves (turn end) or the timeout fires. Returns the reply text. */
+  async function driveTurn(acpSessionId, text) {
+    turnState.set(acpSessionId, { buf: "" });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error("turn timed out")), TURN_TIMEOUT_MS);
+    });
+    try {
+      await Promise.race([acp.prompt(text, acpSessionId), timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+    const out = turnState.get(acpSessionId)?.buf || "";
+    turnState.delete(acpSessionId);
+    return out;
+  }
+
+  async function handleMessage(externalId, text) {
+    const s = await ensureSession(externalId);
+    // Serialize on the session's chain so same-session turns don't overlap.
+    const run = s.chain.then(() => driveTurn(s.acpSessionId, text));
+    // Keep the chain alive even if this turn throws.
+    s.chain = run.then(() => {}, () => {});
+    return run;
+  }
+
+  // ── M2 replay cache + M6 rate limiter / concurrency cap ──────────────
+  // ⚠ CONCURRENCY = 1 IS LOAD-BEARING, not just blast-radius control.
+  // Iris's per-turn consent custody (IRIS-7) arms the MCP-gateway credential by
+  // *user* for the duration of a turn; with exactly one turn in flight that
+  // arm-by-user lookup is unambiguous. Raising max_concurrency > 1 would let two
+  // armed turns overlap and a tool call could resolve to the wrong user's
+  // credential — a consent escape. Do NOT raise this above 1 until the custody
+  // layer is re-keyed to a per-turn token (not per-user). Hard cap, fail-closed.
+  const maxConcurrency = Number(hostedGateway.max_concurrency ?? DEFAULT_MAX_CONCURRENCY);
+  const ratePerMin = Number(hostedGateway.rate_limit_per_min ?? DEFAULT_RATE_PER_MIN);
+  // The limiter is in-process (no external store), so it cannot be "down" — a
+  // failure to obtain a token can only mean the bucket is empty ⇒ 429. There is
+  // no code path where the limiter is unavailable and we fail open.
+  const replayCache = new Map(); // signature -> expiry epoch ms
+  const bucket = { tokens: ratePerMin, last: Date.now() }; // token bucket (global; single-employee container)
+  let inFlight = 0;
+
+  function seenBefore(sig) {
+    if (replayCache.has(sig)) return true;
+    replayCache.set(sig, Date.now() + REPLAY_TTL_MS);
+    return false;
+  }
+  function takeToken() {
+    const now = Date.now();
+    bucket.tokens = Math.min(ratePerMin, bucket.tokens + ((now - bucket.last) * ratePerMin) / 60_000);
+    bucket.last = now;
+    if (bucket.tokens >= 1) { bucket.tokens -= 1; return true; }
+    return false;
+  }
+
+  // Periodic idle eviction + replay-cache pruning.
+  const sweeper = setInterval(() => {
+    const now = Date.now();
+    for (const [id, s] of sessions) {
+      if (now - s.lastUsed > SESSION_IDLE_MS) {
+        sessions.delete(id);
+        turnState.delete(s.acpSessionId);
+        process.stderr.write(`[athena-agent] evicted idle session ${id}\n`);
+      }
+    }
+    for (const [sig, exp] of replayCache) if (exp <= now) replayCache.delete(sig);
+  }, SESSION_SWEEP_MS);
+  if (sweeper.unref) sweeper.unref();
+
+  const server = createServer(async (req, res) => {
+    const url = (req.url || "/").split("?")[0];
+
+    if (req.method === "GET" && url === "/health") {
+      sendJson(res, 200, { ok: true });
+      return;
+    }
+
+    if (req.method === "POST" && url === "/message") {
+      const requestId =
+        (typeof req.headers["x-request-id"] === "string" && req.headers["x-request-id"]) ||
+        randomUUID();
+      // Read the raw body first — the HMAC (M2) is computed over it verbatim.
+      const rawBody = await readRawBody(req);
+
+      if (!secret) {
+        logEvent({ event: "message", request_id: requestId, status: 503, reason: "secret_unset" });
+        sendJson(res, 503, { error: "service unavailable" });
+        return;
+      }
+      // M1 — bearer first (cheapest, no body needed).
+      if (!bearerOk(req, secret)) {
+        logEvent({ event: "auth_fail", request_id: requestId, status: 401, reason: "bearer" });
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+      }
+      // M2 — HMAC signature over `${ts}.${rawBody}`, ±60s skew.
+      const sig = hmacOk(req, rawBody, secret);
+      if (!sig.ok) {
+        logEvent({ event: "auth_fail", request_id: requestId, status: 401, reason: sig.reason });
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+      }
+      // M2 — replay/nonce: a given signature is single-use within its TTL.
+      if (seenBefore(sig.sig)) {
+        logEvent({ event: "auth_fail", request_id: requestId, status: 401, reason: "replay" });
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+      }
+      // M6 — rate limit, then hard concurrency cap. Fail closed (429), never open.
+      if (!takeToken()) {
+        logEvent({ event: "rate_limited", request_id: requestId, status: 429 });
+        sendJson(
+          res,
+          429,
+          { status: "rate_limited", reason: "rate_limited", message: "Too many requests — try again shortly.", retry_after_ms: BUSY_RETRY_AFTER_MS },
+          { "retry-after": String(Math.ceil(BUSY_RETRY_AFTER_MS / 1000)) },
+        );
+        return;
+      }
+      if (inFlight >= maxConcurrency) {
+        // DAE-16 (D3 container half): a turn is already in flight. max_concurrency
+        // stays 1 (load-bearing for arm custody — never raised), so instead of
+        // blocking or a bare 429 we return an IMMEDIATE, TYPED busy signal the
+        // poller (IRIS-24) relays. Contract: HTTP 429 + Retry-After, body
+        // { status:"busy", reason:"turn_in_flight", message, retry_after_ms }.
+        logEvent({ event: "busy", request_id: requestId, status: 429, reason: "turn_in_flight", in_flight: inFlight });
+        sendJson(
+          res,
+          429,
+          {
+            status: "busy",
+            reason: "turn_in_flight",
+            message: "The agent is still processing a previous message — try again shortly.",
+            retry_after_ms: BUSY_RETRY_AFTER_MS,
+          },
+          { "retry-after": String(Math.ceil(BUSY_RETRY_AFTER_MS / 1000)) },
+        );
+        return;
+      }
+
+      let body;
+      try { body = JSON.parse(rawBody || "{}"); } catch { body = {}; }
+      const sessionId = typeof body.session_id === "string" ? body.session_id.trim() : "";
+      const text = typeof body.text === "string" ? body.text : "";
+      // M3 — identity is NEVER taken from the body; only session_id + text are read.
+      if (!sessionId || !text.trim()) {
+        logEvent({ event: "message", request_id: requestId, status: 400, reason: "bad_request" });
+        sendJson(res, 400, { error: "session_id and text are required" });
+        return;
+      }
+
+      inFlight++;
+      const startedAt = Date.now();
+      try {
+        const reply = await handleMessage(sessionId, text);
+        logEvent({ event: "turn", request_id: requestId, session_id: sessionId, status: 200, ms: Date.now() - startedAt });
+        sendJson(res, 200, { text: reply });
+      } catch (err) {
+        // M7 — generic error body; the detail stays in our own logs only.
+        logEvent({ event: "turn", request_id: requestId, session_id: sessionId, status: 502, error: String(err?.message || err) });
+        sendJson(res, 502, { error: "turn_failed" });
+      } finally {
+        inFlight--;
+      }
+      return;
+    }
+
+    sendJson(res, 404, { error: "not found" });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    // 0.0.0.0 — the container's ingress fronts this; bind to all interfaces.
+    server.listen(port, "0.0.0.0", resolve);
+  });
+
+  const boundPort = server.address().port;
+  function close() {
+    clearInterval(sweeper);
+    acp.kill();
+    server.close();
+  }
+  acp.child.on("exit", () => { clearInterval(sweeper); server.close(); });
+
+  return { url: `http://0.0.0.0:${boundPort}`, port: boundPort, close };
+}

package/lib/webchat-ui.html

@@ -41,6 +41,9 @@
   .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); }
+  .tool.err { border-color: var(--err); }
+  .tool.err .t-status { color: var(--err); }
+  .tool .t-detail { margin-top: 6px; font-size: 12px; color: var(--err); white-space: pre-wrap; word-wrap: break-word; }
   .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; }
@@ -143,7 +146,18 @@ function handle(ev) {
     }
     case "tool_update": {
       const el = toolEls.get(ev.id);
-      if (el) el.querySelector(".t-status").textContent = "· " + ev.status; break;
+      if (el) {
+        el.querySelector(".t-status").textContent = "· " + (ev.isError ? "failed" : ev.status);
+        if (ev.isError) {
+          el.classList.add("err");
+          if (ev.detail) {
+            let d = el.querySelector(".t-detail");
+            if (!d) { d = document.createElement("div"); d.className = "t-detail"; el.append(d); }
+            d.textContent = ev.detail;
+          }
+        }
+      }
+      break;
     }
     case "permission":
       renderPermission(ev); break;

package/lib/webchat.mjs

@@ -14,165 +14,14 @@ import { createServer } from "node:http";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { AcpClient } from "./acp-client.mjs";
 
 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 {}
-  }
-}
+// The ACP client (newline-delimited JSON-RPC over a `hermes acp` child) now
+// lives in ./acp-client.mjs so the hosted gateway (DAE-6) shares the exact
+// same transport. webchat uses it in single-session mode (init + prompt).
 
 function openBrowser(url) {
   const cmd =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "athena-agent-launcher",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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": {