@volter/supercode-orchestrator 0.4.4

package/adapters/api-server.mjs

@@ -0,0 +1,615 @@
+// The `api_server`-compatible HTTP surface (ORC-9): Hermes's own client API,
+// served by this loop, behind the same three-method adapter trait
+// (`connect(emit)` / `send(target, content)` / `close()`).
+//
+// EVERY route below quotes the Hermes handler it was matched against, from
+// `~/.hermes/hermes-agent/gateway/platforms/api_server.py` and its
+// `api_server_runs.py` sibling at the pinned 0.21.0 tree. Where Hermes's JSON
+// carries a field the IR has no source for, the field is returned EMPTY and
+// named in README.md § "The api_server surface"; nothing is invented.
+//
+// WHERE IT LISTENS. Its own `node:http` server on
+// `platforms.api_server.extra.host|port` — exactly Hermes's keys
+// (`api_server.py:1515-1519`: `extra.get("host", …)` / `extra.get("port")`).
+// It is NOT mounted on the loop's webhook listener: that one binds
+// `gateway.webhook_port`, a different Hermes key with a different meaning, and
+// hosting both on one socket would make one port answer for two configured
+// addresses. `webhook.mjs` is untouched.
+//
+// AUTH. `Authorization: Bearer <key>` against `platforms.api_server.extra.key`
+// — Hermes's `_check_auth` (`api_server.py:1916-1968`), whose expected key is
+// `extra.get("key", API_SERVER_KEY)` (`:1520`). `X-Hermes-Session-Key` is NOT
+// an auth credential in Hermes: `_parse_session_key_header` (`:2403-2440`)
+// reads it as the caller-declared CONVERSATION scope and requires the API key
+// to be configured before honouring it. It is read with that meaning here.
+//
+// NO PRIVATE PATH (§3). Everything this surface makes the loop do enters as an
+// `inbound` event: a chat is an inbound, a run is an inbound on a fresh
+// binding, a steer is an inbound queued behind the running turn (§4.1 step 5),
+// a stop is the `/reset` chat command (§2.7), and an approval is the numeric
+// reply §4.2's permission prompt asks for. The surface reads runtime state
+// (§2.8) to build its event stream; it never writes it.
+
+import { surfaceKeyString } from '../ir.mjs';
+import { leaseId } from '../reducer.mjs';
+
+/** Hermes's own defaults (`api_server.py` DEFAULT_HOST / DEFAULT_PORT). */
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 8090;
+
+const MAX_BODY = 1024 * 1024;
+
+/** `POST /api/sessions` mints `api_<epoch>_<hex>` when the body names no id (`api_server.py:4443`). */
+function mintSessionId(at, n) {
+  return `api_${Math.floor(Date.parse(at) / 1000)}_${n.toString(16).padStart(8, '0')}`;
+}
+
+/** Hermes's OpenAI-shaped error envelope (`_openai_error`). */
+function errorBody(message, code = null, type = 'invalid_request_error') {
+  const error = { message, type };
+  if (code) error.code = code;
+  return { error };
+}
+
+export class ApiServerAdapter {
+  /**
+   * @param {object} o
+   * @param {string} [o.platform]   always `api_server`: the block name IS the platform (§2.4)
+   * @param {string} [o.profile]    the profile that owns the block
+   * @param {object} [o.channel]    the loaded `ChannelConfig`; `extra.key` is a `{dotenv}` ref
+   * @param {Map<string,string>} [o.vault]  resolved at `connect`, never earlier
+   * @param {object} o.state        the OrchestratorState: read for §2.8 runtime and for bindings
+   * @param {() => string} [o.clock]
+   * @param {(level: string, message: string) => void} [o.log]
+   */
+  constructor({ platform = 'api_server', profile = 'default', channel = null, vault = new Map(), state = null, clock = null, log = () => {} }) {
+    this.platform = platform;
+    this.profile = profile;
+    this.channel = channel;
+    this.vault = vault;
+    this.state = state;
+    this.clock = clock ?? (() => new Date().toISOString());
+    this.log = log;
+    this.emit = null;
+    this.server = null;
+    this.port = null;
+    this.key = null;
+    this.counter = 0;
+    /** session id -> the Hermes-shaped session row this surface owns. */
+    this.sessions = new Map();
+    /** run id -> the pollable run status (`hermes.run`). */
+    this.runs = new Map();
+    /** keyString -> [resolve] for the `/chat` calls waiting on this turn's answer. */
+    this.waiting = new Map();
+    /** run id -> Set<ServerResponse> subscribed to the SSE stream. */
+    this.streams = new Map();
+    /** run id -> what the stream has already reported, so a poll never repeats itself. */
+    this.watermarks = new Map();
+    this.poll = null;
+    this.version = '0';
+    /** `node:crypto`'s constant-time compare, resolved at `connect` (this module imports no node module eagerly). */
+    this.timingSafeEqual = (a, b) => a.equals(b);
+  }
+
+  extra(name, fallback = undefined) {
+    const e = this.channel?.extra ?? {};
+    return e[`extra.${name}`] ?? e[name] ?? fallback;
+  }
+
+  /** `extra.key`, a `${NAME}` reference, resolved from the vault (`.env`), then the environment, as Hermes does. */
+  resolveKey() {
+    const ref = this.channel?.credentials?.['extra.key'] ?? this.channel?.credentials?.key ?? null;
+    if (!ref) return null;
+    const name = ref.dotenv ?? ref.env;
+    return this.vault.get(name) ?? process.env[name] ?? null;
+  }
+
+  /** The user id every request from this surface speaks as; the profile's access (Hermes's own stores) gates it like any other sender. */
+  get sender() {
+    return String(this.extra('user_id', 'api'));
+  }
+
+  // ------------------------------------------------------------ the trait
+
+  async connect(emit) {
+    this.emit = emit;
+    this.key = this.resolveKey();
+    const { createServer } = await import('node:http');
+    const { readFileSync } = await import('node:fs');
+    const { fileURLToPath } = await import('node:url');
+    ({ timingSafeEqual: this.timingSafeEqual } = await import('node:crypto'));
+    // `/v1/health` reports this package's real version, never a literal that
+    // goes stale the next time it is published.
+    try { this.version = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version; } catch { this.version = '0'; }
+    const host = String(this.extra('host', DEFAULT_HOST));
+    const port = Number(this.extra('port', DEFAULT_PORT));
+    // a request the router cannot handle (a malformed URL, bad percent-encoding,
+    // a close mid-request) is that request's 500, never the daemon's exit
+    this.server = createServer((req, res) => {
+      this.route(req, res).catch((error) => {
+        this.log?.('warn', `api-server: ${req.method} ${req.url}: ${error?.message ?? error}`);
+        if (!res.headersSent) { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: { message: 'internal error' } })); }
+        else res.end();
+      });
+    });
+    await new Promise((resolve, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(port, host, () => { this.server.removeListener('error', reject); resolve(); });
+    });
+    this.server.unref?.();
+    this.port = this.server.address().port;
+    const every = Number(this.extra('stream_poll_ms', 10));
+    this.poll = setInterval(() => this.pump(), every);
+    this.poll.unref?.();
+    this.log('info', `api_server listening on http://${host}:${this.port}`);
+    return { state: 'up' };
+  }
+
+  /**
+   * `Deliver(obligation)` (§5) for this platform: the loop's answer for a
+   * surface this server owns. It resolves whatever `/chat` call is waiting on
+   * that key, appends the assistant message to the session's transcript, and
+   * finishes the run when the key is a run's. Returns the handle the loop
+   * records as `Obligation.posted.message_id` (§2.6).
+   */
+  async send(target, content) {
+    const text = content.text ?? '';
+    const keyString = surfaceKeyString(target);
+    const id = `apisrv-${++this.counter}`;
+    const at = content.at ?? this.clock();
+    const session = this.sessions.get(String(target.chat_id ?? ''));
+    if (session) session.messages.push({ id, session_id: session.id, role: 'assistant', content: text, timestamp: at });
+    const waiters = this.waiting.get(keyString);
+    if (waiters?.length) {
+      this.waiting.delete(keyString);
+      for (const resolve of waiters) resolve({ id, text, at });
+    }
+    // A run finishes on the turn's FINAL, not on any message the loop sends.
+    // §4.2 deletes `runtime.turns[lease]` before it queues the final's reply
+    // and keeps it while a permission prompt goes out mid-turn, so an empty
+    // turn slot is what tells the two apart — no new state, no new flag.
+    const lid = this.leaseFor(keyString);
+    const midTurn = Boolean(lid && this.state?.runtime?.turns?.[lid]);
+    const run = this.runs.get(String(target.chat_id ?? ''));
+    if (run && !midTurn && !['completed', 'failed', 'cancelled', 'stopping'].includes(run.status)) {
+      run.status = 'completed';
+      run.updated_at = Date.parse(at) / 1000;
+      run.last_event = 'run.completed';
+      run.output = text;
+      delete run.approval;
+      this.frame(run.run_id, { event: 'run.completed', run_id: run.run_id, timestamp: run.updated_at, output: text, usage: {} });
+      this.closeStream(run.run_id);
+    }
+    return { ok: true, message_id: id };
+  }
+
+  async close() {
+    this.emit = null;
+    if (this.poll) { clearInterval(this.poll); this.poll = null; }
+    for (const id of [...this.streams.keys()]) this.closeStream(id);
+    for (const waiters of this.waiting.values()) for (const resolve of waiters) resolve(null);
+    this.waiting.clear();
+    if (this.server) { const s = this.server; this.server = null; await new Promise((r) => s.close(() => r())); }
+  }
+
+  // ------------------------------------------------------------ the loop side
+
+  /** The surface key for one of this platform's conversations (§2.3). */
+  keyFor(chatId) {
+    return { platform: this.platform, kind: 'dm', chat_id: String(chatId) };
+  }
+
+  /** The one door into the loop: an `inbound` event, same callback loopback gets. */
+  inbound(chatId, text, { message_id = null } = {}) {
+    if (!this.emit) throw new Error('api_server adapter is not connected');
+    return this.emit({
+      profile: this.profile,
+      key: this.keyFor(chatId),
+      sender: this.sender,
+      sender_name: null,
+      text,
+      message_id,
+      is_me: false,
+      is_bot: false,
+      mention: false,
+    });
+  }
+
+  /** Wait for the loop's reply on this key; `timeout_ms` from the block, else 120 s. */
+  answer(chatId) {
+    const keyString = surfaceKeyString(this.keyFor(chatId));
+    return new Promise((resolve) => {
+      const list = this.waiting.get(keyString) ?? [];
+      list.push(resolve);
+      this.waiting.set(keyString, list);
+      const ms = Number(this.extra('timeout_ms', 120_000));
+      const t = setTimeout(() => {
+        const held = this.waiting.get(keyString) ?? [];
+        const at = held.indexOf(resolve);
+        if (at >= 0) held.splice(at, 1);
+        resolve(null);
+      }, ms);
+      t.unref?.();
+    });
+  }
+
+  /** The profile whose runtime is serving this key — routes may move it (§2.3). */
+  leaseFor(keyString) {
+    const rt = this.state?.runtime ?? {};
+    for (const name of Object.keys(this.state?.profiles ?? {})) {
+      const lid = leaseId(name, keyString);
+      if (rt.turns?.[lid] || rt.leases?.[lid]) return lid;
+    }
+    return null;
+  }
+
+  /** The pending permission request on this key, if the worker raised one (§2.8). */
+  pendingRequest(keyString) {
+    const pending = this.state?.runtime?.pending_requests ?? {};
+    for (const [id, p] of Object.entries(pending)) if (p.keyString === keyString) return { id, ...p };
+    return null;
+  }
+
+  /**
+   * The run event stream, derived from §2.8 runtime state on a timer. The loop
+   * publishes no event bus and ORC-9 may not add one, so the stream watches
+   * the three things the runtime already holds for a live turn — the turn's
+   * accumulating text buffer, the pending permission requests, and (through
+   * `send`) the obligation the turn's `final` produces.
+   */
+  pump() {
+    const stamp = Date.parse(this.clock()) / 1000;
+    for (const [runId, run] of this.runs) {
+      if (run.status === 'completed' || run.status === 'failed' || run.status === 'cancelled') continue;
+      const keyString = surfaceKeyString(this.keyFor(runId));
+      const mark = this.watermarks.get(runId) ?? { delta: 0, request: null };
+      const lid = this.leaseFor(keyString);
+      const buffer = lid ? this.state?.runtime?.turns?.[lid]?.buffer ?? '' : '';
+      if (buffer.length > mark.delta) {
+        this.frame(runId, { event: 'message.delta', run_id: runId, timestamp: stamp, delta: buffer.slice(mark.delta) });
+        mark.delta = buffer.length;
+      }
+      const pending = this.pendingRequest(keyString);
+      if (pending && pending.id !== mark.request) {
+        mark.request = pending.id;
+        run.status = 'waiting_for_approval';
+        run.last_event = 'approval.request';
+        // `_approval_event_choices` shape (api_server_runs.py:760-767): the
+        // choices this loop can actually answer are the worker's own options.
+        run.updated_at = stamp;
+        run.approval = { event: 'approval.request', run_id: runId, request_id: pending.id, choices: (pending.options ?? []).map((o) => o.name ?? o.kind ?? '') };
+        this.frame(runId, { ...run.approval, timestamp: stamp });
+      }
+      this.watermarks.set(runId, mark);
+    }
+  }
+
+  // ------------------------------------------------------------ SSE
+
+  frame(runId, payload) {
+    const body = `data: ${JSON.stringify(payload)}\n\n`;
+    for (const res of this.streams.get(runId) ?? []) { try { res.write(body); } catch { /* client gone */ } }
+  }
+
+  closeStream(runId) {
+    for (const res of this.streams.get(runId) ?? []) { try { res.write(': stream closed\n\n'); res.end(); } catch { /* already gone */ } }
+    this.streams.delete(runId);
+  }
+
+  // ------------------------------------------------------------ routing
+
+  /**
+   * Hermes compares the bearer token with `hmac.compare_digest`
+   * (`api_server.py:1957`) — a constant-time compare, so a wrong key leaks no
+   * prefix through timing. `webhook.mjs`'s signature check does the same; this
+   * is that, for the same reason.
+   */
+  authorized(req) {
+    if (!this.key) return true; // no key configured: Hermes's own no-key branch (`_check_auth`, api_server.py:1922-1926)
+    const header = String(req.headers.authorization ?? '');
+    if (!header.startsWith('Bearer ')) return false;
+    const given = Buffer.from(header.slice(7).trim());
+    const expected = Buffer.from(this.key);
+    return given.length === expected.length && this.timingSafeEqual(given, expected);
+  }
+
+  async route(req, res) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+    const method = (req.method ?? 'GET').toUpperCase();
+    const send = (status, body, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', ...headers });
+      res.end(JSON.stringify(body));
+    };
+
+    // GET /v1/health — `api_server.py:3277-3281`, the ONE route with no
+    // `_check_auth`. `{"status","platform","version"}`; `platform` names the
+    // server that answers, so it is this one, not "hermes-agent".
+    if (method === 'GET' && (path === '/v1/health' || path === '/health')) {
+      return send(200, { status: 'ok', platform: 'supercode-orchestrator', version: this.version });
+    }
+
+    if (!this.authorized(req)) {
+      // `_check_auth`'s own body (`api_server.py:1966-1968`).
+      return send(401, { error: { message: 'Invalid gateway API key (API_SERVER_KEY)', type: 'gateway_auth_error', code: 'gateway_auth_failed' } });
+    }
+
+    // GET /v1/capabilities — `api_server.py:3427-3475`. Every flag is this
+    // loop's own answer; a surface it does not serve reads `false`, never a
+    // copy of Hermes's `true`.
+    if (method === 'GET' && path === '/v1/capabilities') {
+      return send(200, {
+        object: 'hermes.api_server.capabilities',
+        platform: 'supercode-orchestrator',
+        model: '',
+        auth: { type: 'bearer', required: Boolean(this.key) },
+        runtime: {
+          mode: 'server_agent',
+          tool_execution: 'server',
+          split_runtime: false,
+          description: 'The orchestrator opens a binding on this surface and drives the profile\'s worker through its own door (docs/ORCHESTRATOR-IR.md §4.1).',
+        },
+        features: {
+          chat_completions: false,
+          chat_completions_streaming: false,
+          responses_api: false,
+          responses_streaming: false,
+          run_submission: true,
+          runs_idempotency: { supported: false, durable: false, retention_seconds: 0 },
+          run_status: true,
+          run_events_sse: true,
+          run_stop: true,
+          run_steer: true,
+          run_approval_response: true,
+          session_create: true,
+          session_chat: true,
+          session_chat_stream: false,
+          session_messages: true,
+        },
+        session_key_header: 'X-Hermes-Session-Key',
+      });
+    }
+
+    // POST /api/sessions — `api_server.py:4422-4541`. Body `{id|session_id,
+    // title, source, system_prompt, model}`; 409 on an id that exists; 201
+    // `{"object":"hermes.session","session":{…}}` shaped by `_session_response`
+    // (`:4283-4302`).
+    if (method === 'POST' && path === '/api/sessions') {
+      const body = await this.readJson(req);
+      if (body === null) return send(400, errorBody('Invalid JSON in request body'));
+      const at = this.clock();
+      const raw = body.id ?? body.session_id;
+      const id = raw ? String(raw).trim() : mintSessionId(at, ++this.counter);
+      if (!id || /[\r\n\0]/.test(id)) return send(400, errorBody('Invalid session ID', 'invalid_session_id'));
+      if (this.sessions.has(id)) return send(409, errorBody(`Session already exists: ${id}`, 'session_exists'));
+      this.sessions.set(id, {
+        id, source: String(body.source ?? 'api_server'), title: body.title ?? null,
+        started_at: Date.parse(at) / 1000, messages: [], system_prompt: body.system_prompt ?? null,
+      });
+      return send(201, { object: 'hermes.session', session: this.sessionResponse(id) });
+    }
+
+    const chat = /^\/api\/sessions\/([^/]+)\/chat$/.exec(path);
+    // POST /api/sessions/{id}/chat — `api_server.py:4720-4833`. Body's user
+    // turn is `message` ∥ `input` (`_session_chat_user_message`, `:931-943`);
+    // the reply is `{"object":"hermes.session.chat.completion","session_id",
+    // "message":{"role":"assistant","content"},"usage","runtime"}` with the
+    // `X-Hermes-Session-Id` header (`:4804-4833`).
+    if (method === 'POST' && chat) {
+      const id = decodeURIComponent(chat[1]);
+      if (!this.sessions.has(id)) return send(404, errorBody(`Session not found: ${id}`, 'session_not_found'));
+      const body = await this.readJson(req);
+      if (body === null) return send(400, errorBody('Invalid JSON in request body'));
+      const text = body.message ?? body.input;
+      if (typeof text !== 'string' || !text.trim()) return send(400, errorBody("Missing 'message' field", 'missing_message'));
+      const session = this.sessions.get(id);
+      const at = this.clock();
+      session.messages.push({ id: `apisrv-in-${++this.counter}`, session_id: id, role: 'user', content: text, timestamp: at });
+      const waiter = this.answer(id);
+      await this.inbound(id, text);
+      const answer = await waiter;
+      const headers = { 'X-Hermes-Session-Id': id };
+      const declared = String(req.headers['x-hermes-session-key'] ?? '').trim();
+      if (declared) headers['X-Hermes-Session-Key'] = declared;
+      return send(200, {
+        object: 'hermes.session.chat.completion',
+        session_id: id,
+        message: { role: 'assistant', content: answer?.text ?? '' },
+        usage: {},    // EMPTY: the IR records no token accounting (README)
+        runtime: {},  // EMPTY: the IR records no provider/model routing (README)
+      }, headers);
+    }
+
+    const messages = /^\/api\/sessions\/([^/]+)\/messages$/.exec(path);
+    // GET /api/sessions/{id}/messages — `api_server.py:4613-4670`.
+    // `{"object":"list","session_id","data":[…],"pagination":{limit,offset,
+    // order,returned}}`; rows shaped by `_message_response` (`:4305-4312`).
+    if (method === 'GET' && messages) {
+      const id = decodeURIComponent(messages[1]);
+      const session = this.sessions.get(id);
+      if (!session) return send(404, errorBody(`Session not found: ${id}`, 'session_not_found'));
+      const rawLimit = url.searchParams.get('limit');
+      const rawOffset = url.searchParams.get('offset') ?? '0';
+      const order = url.searchParams.get('order');
+      if (order !== null && order !== 'oldest' && order !== 'latest') return send(400, errorBody('order must be one of: oldest, latest', 'invalid_pagination'));
+      const offset = Number(rawOffset);
+      const requested = rawLimit === null ? null : Number(rawLimit);
+      if (!Number.isInteger(offset) || offset < 0 || (requested !== null && (!Number.isInteger(requested) || requested < 0))) {
+        return send(400, errorBody('limit and offset must be non-negative integers', 'invalid_pagination'));
+      }
+      const limit = requested === null ? 500 : Math.min(requested, 500);
+      const rows = session.messages.slice(offset, offset + limit);
+      return send(200, {
+        object: 'list',
+        session_id: id,
+        data: rows.map((m) => ({
+          id: m.id, session_id: m.session_id, role: m.role, content: m.content,
+          // EMPTY, all four: the IR keeps no per-message tool or token record
+          tool_call_id: null, tool_calls: null, tool_name: null, token_count: null,
+          timestamp: m.timestamp, finish_reason: null, reasoning: null,
+        })),
+        pagination: { limit, offset, order: order ?? (requested === null ? 'latest' : 'oldest'), returned: rows.length },
+      });
+    }
+
+    // POST /v1/runs — `api_server_runs.py:405-1038`. `input` is required
+    // (`:483-485`); a fresh run answers 202 `{"run_id","status":"started",
+    // "replayed":false}` (`:1034-1038`).
+    if (method === 'POST' && path === '/v1/runs') {
+      const body = await this.readJson(req);
+      if (body === null) return send(400, errorBody('Invalid JSON'));
+      const raw = body.input;
+      const text = typeof raw === 'string' ? raw : Array.isArray(raw) ? String(raw[raw.length - 1]?.content ?? '') : '';
+      if (!text) return send(400, errorBody("Missing 'input' field"));
+      const at = this.clock();
+      const runId = `run_${Date.parse(at)}_${(++this.counter).toString(36)}`;
+      this.runs.set(runId, {
+        object: 'hermes.run', run_id: runId, status: 'running',
+        created_at: Date.parse(at) / 1000, updated_at: Date.parse(at) / 1000,
+        session_id: runId, // the run IS its binding: one job-less turn on a fresh surface
+        model: '',         // EMPTY: the IR does not name the provider model here
+        last_event: 'run.started', output: null, error: null,
+      });
+      this.frame(runId, { event: 'run.started', run_id: runId, timestamp: Date.parse(at) / 1000 });
+      void this.inbound(runId, text);
+      return send(202, { run_id: runId, status: 'started', replayed: false });
+    }
+
+    const run = /^\/v1\/runs\/([^/]+)(\/(events|approval|steer|stop))?$/.exec(path);
+    if (run) {
+      const runId = decodeURIComponent(run[1]);
+      const record = this.runs.get(runId);
+      if (!record) return send(404, errorBody(`Run not found: ${runId}`, 'run_not_found'));
+      const tail = run[3] ?? null;
+
+      // GET /v1/runs/{run_id} — `api_server_runs.py:1074-1105`: the pollable
+      // status object `_set_run_status` builds (`:116-137`).
+      if (method === 'GET' && tail === null) return send(200, record);
+
+      // GET /v1/runs/{run_id}/events — `api_server_runs.py:1108-1170`:
+      // `text/event-stream`, `data: <json>` frames, `: stream closed` at the end.
+      if (method === 'GET' && tail === 'events') {
+        res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' });
+        const set = this.streams.get(runId) ?? new Set();
+        set.add(res);
+        this.streams.set(runId, set);
+        // A late subscriber is caught up on the lifecycle it missed: the run's
+        // start, the approval it is blocked on, and its terminal event. Text
+        // deltas are live-only — the loop keeps no transcript to replay.
+        res.write(`data: ${JSON.stringify({ event: 'run.started', run_id: runId, timestamp: record.created_at })}\n\n`);
+        if (record.approval) res.write(`data: ${JSON.stringify({ ...record.approval, timestamp: record.updated_at })}\n\n`);
+        if (record.status === 'completed') { res.write(`data: ${JSON.stringify({ event: 'run.completed', run_id: runId, timestamp: record.updated_at, output: record.output ?? '', usage: {} })}\n\n`); this.closeStream(runId); }
+        req.on('close', () => { this.streams.get(runId)?.delete(res); });
+        return undefined;
+      }
+
+      // POST /v1/runs/{run_id}/approval — `api_server_runs.py:1174-1295`.
+      // Choices `once|session|always|deny` with `approve|approved|allow`
+      // aliasing to `once` (`:1201-1203`); 409 `approval_not_active` when no
+      // approval session is open (`:1250-1258`) and `approval_not_pending`
+      // when nothing is waiting (`:1276-1284`); the body is
+      // `{"object":"hermes.run.approval_response","run_id","choice","resolved"}`.
+      if (method === 'POST' && tail === 'approval') {
+        const body = await this.readJson(req);
+        if (body === null) return send(400, errorBody('Invalid JSON'));
+        const alias = { approve: 'once', approved: 'once', allow: 'once' };
+        const asked = String(body.choice ?? '').trim().toLowerCase();
+        const choice = alias[asked] ?? asked;
+        if (!['once', 'session', 'always', 'deny'].includes(choice)) {
+          return send(400, errorBody('Invalid approval choice; expected one of: always, deny, once, session', 'invalid_approval_choice'));
+        }
+        const keyString = surfaceKeyString(this.keyFor(runId));
+        const pending = this.pendingRequest(keyString);
+        if (!pending) return send(409, errorBody(`Run has no pending approval: ${runId}`, 'approval_not_pending'));
+        // §4.2's relay asks the surface for a NUMBER; that numeric reply is the
+        // only door into `pending_requests`, so the Hermes choice is resolved
+        // to the worker's own option and answered as that number.
+        const options = pending.options ?? [];
+        const want = choice === 'deny'
+          ? options.findIndex((o) => /reject|deny/i.test(o.kind ?? '') || /deny|reject/i.test(o.name ?? ''))
+          : options.findIndex((o) => /allow/i.test(o.kind ?? '') || /allow/i.test(o.name ?? ''));
+        const index = want >= 0 ? want : 0;
+        await this.inbound(runId, String(index + 1));
+        record.status = 'running';
+        record.last_event = 'approval.responded';
+        delete record.approval;
+        this.frame(runId, { event: 'approval.responded', run_id: runId, timestamp: Date.parse(this.clock()) / 1000, choice, resolved: 1 });
+        return send(200, { object: 'hermes.run.approval_response', run_id: runId, choice, resolved: 1 });
+      }
+
+      // POST /v1/runs/{run_id}/steer — `api_server_runs.py:1312-1386`. Text is
+      // `input` ∥ `message` ∥ `text` (`:1354`); only a `running` run accepts it
+      // (`:1341-1350`); body `{"object":"hermes.run.steer","run_id","accepted"}`.
+      if (method === 'POST' && tail === 'steer') {
+        const body = await this.readJson(req);
+        if (body === null) return send(400, errorBody('Invalid JSON'));
+        const text = String(body.input ?? body.message ?? body.text ?? '').trim();
+        if (!text) return send(400, errorBody("Missing non-empty steer text; expected 'input', 'message', or 'text'.", 'invalid_steer_input'));
+        if (record.status !== 'running') return send(409, errorBody(`Run is not currently accepting steer input: ${runId}`, 'run_not_accepting_steer'));
+        // §4.1 step 5: an inbound arriving during a running turn is queued
+        // behind it and sent when it ends — the IR's own steer.
+        await this.inbound(runId, text);
+        record.last_event = 'run.steered';
+        this.frame(runId, { event: 'run.steered', run_id: runId, timestamp: Date.parse(this.clock()) / 1000, accepted: true });
+        return send(200, { object: 'hermes.run.steer', run_id: runId, accepted: true });
+      }
+
+      // POST /v1/runs/{run_id}/stop — `api_server_runs.py:1390-1455`. A run
+      // already in a terminal state answers with its status (`:1425-1432`);
+      // otherwise `{"run_id","status":"stopping"}` (`:1455`).
+      if (method === 'POST' && tail === 'stop') {
+        if (['completed', 'failed', 'cancelled', 'interrupted'].includes(record.status)) return send(200, record);
+        record.status = 'stopping';
+        record.last_event = 'run.stopping';
+        record.updated_at = Date.parse(this.clock()) / 1000;
+        // §2.7's `/reset` is the loop's own "abandon this conversation": it
+        // ends the binding, which emits `runtime_close` for its worker (§4.5).
+        // Once that lands the run is terminal — Hermes's own `run.cancelled`
+        // (`api_server_runs.py:723`), not a `stopping` that never resolves.
+        await this.inbound(runId, '/reset');
+        record.status = 'cancelled';
+        record.last_event = 'run.cancelled';
+        record.updated_at = Date.parse(this.clock()) / 1000;
+        this.frame(runId, { event: 'run.cancelled', run_id: runId, timestamp: record.updated_at });
+        this.closeStream(runId);
+        return send(200, { run_id: runId, status: 'stopping' });
+      }
+    }
+
+    return send(404, errorBody(`Unknown route: ${method} ${path}`, 'not_found'));
+  }
+
+  /** `_session_response`'s client-safe projection (`api_server.py:4283-4302`). */
+  sessionResponse(id) {
+    const s = this.sessions.get(id);
+    return {
+      id: s.id, source: s.source, title: s.title, started_at: s.started_at,
+      ended_at: null, end_reason: null,
+      message_count: s.messages.length,
+      // EMPTY, all of them: the IR keeps no token or cost accounting (README)
+      user_id: null, model: null, tool_call_count: null, input_tokens: null, output_tokens: null,
+      parent_session_id: null,
+      has_system_prompt: Boolean(s.system_prompt),
+      has_model_config: false,
+    };
+  }
+
+  readJson(req) {
+    return new Promise((resolve) => {
+      const chunks = [];
+      let size = 0;
+      req.on('data', (c) => {
+        size += c.length;
+        if (size > MAX_BODY) { req.destroy(); resolve(null); return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (!body.trim()) { resolve({}); return; }
+        try { const parsed = JSON.parse(body); resolve(parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null); }
+        catch { resolve(null); }
+      });
+      req.on('error', () => resolve(null));
+    });
+  }
+}