agent-shim 8.2.0 → 8.3.0

package/dist/index.mjs

@@ -2449,6 +2449,7 @@ function pumpTapSession(secure, openUpstream, tap, prefix = Buffer.alloc(0)) {
 }
 
 // src/frontdoor/capability.ts
+import { createHash as createHash2, timingSafeEqual } from "node:crypto";
 var CONNECT_PROXY_USER = "agent-shim";
 var CONNECT_PROXY_REALM = "agent-shim front door";
 var BASIC_SCHEME = "basic";
@@ -2469,6 +2470,18 @@ function capabilityFromProxyAuthorization(value) {
   const password = userPass.slice(colon + 1);
   return password === "" ? void 0 : password;
 }
+function digest(token) {
+  return createHash2("sha256").update(token, "utf8").digest();
+}
+function isLiveCapability(presented, live) {
+  const presentedDigest = digest(presented);
+  let matched = false;
+  for (const token of live) {
+    const equal = timingSafeEqual(presentedDigest, digest(token));
+    matched = equal || matched;
+  }
+  return matched;
+}
 
 // src/frontdoor/route.ts
 var IDENTITY_HEADER = "x-agent-shim-identity";
@@ -2779,14 +2792,14 @@ function caParses(ca) {
 var TAP_ALPN_PROTOCOLS = ["h2", "http/1.1"];
 async function startConnectServer(config, effects, preferredPort) {
   const tunnelTokens = /* @__PURE__ */ new WeakMap();
-  const onUpgrade = (host) => (request3, socket, head) => {
-    config.capture?.upgrade(request3);
+  const onUpgrade = (host) => (request4, socket, head) => {
+    config.capture?.upgrade(request4);
     if (head.length > 0) {
       socket.pause();
       socket.unshift(head);
     }
-    const headText = `${request3.method ?? "GET"} ${request3.url ?? "/"} HTTP/1.1\r
-${request3.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `${accumulated}${value}: ` : `${accumulated}${value}\r
+    const headText = `${request4.method ?? "GET"} ${request4.url ?? "/"} HTTP/1.1\r
+${request4.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `${accumulated}${value}: ` : `${accumulated}${value}\r
 `, "")}\r
 `;
     pumpTapSession(socket, async (clientAlpn) => await effects.connectTlsUpstream(host, HTTPS_PORT, clientAlpn), config.capture?.tapStream?.(host), Buffer.from(headText, "utf8"));
@@ -2799,16 +2812,16 @@ ${request3.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
       const tlsAcceptor2 = effects.createTlsAcceptor(config.leafFor(host), serveSecure2, TAP_ALPN_PROTOCOLS);
       return { host, serveSecure: serveSecure2, tlsAcceptor: tlsAcceptor2 };
     }
-    const handler = (request3, response) => {
-      if (host === config.routedHost && servedByPipeline(request3.url)) {
-        const tunnelToken = tunnelTokens.get(request3.socket);
-        if (tunnelToken !== void 0 && request3.headers[AUTH_HEADER] === void 0) {
-          request3.headers[AUTH_HEADER] = tunnelToken;
+    const handler = (request4, response) => {
+      if (host === config.routedHost && servedByPipeline(request4.url)) {
+        const tunnelToken = tunnelTokens.get(request4.socket);
+        if (tunnelToken !== void 0 && request4.headers[AUTH_HEADER] === void 0) {
+          request4.headers[AUTH_HEADER] = tunnelToken;
         }
-        config.serveRouted(request3, response);
+        config.serveRouted(request4, response);
         return;
       }
-      effects.forwardHttp(config.upstreamFor(host), request3, response, config.capture?.observePassthrough(request3));
+      effects.forwardHttp(config.upstreamFor(host), request4, response, config.capture?.observePassthrough(request4));
     };
     const httpSession = effects.createHttpSession(handler, onUpgrade(host));
     const serveSecure = (secure, capability) => {
@@ -2850,7 +2863,7 @@ ${request3.rawHeaders.reduce((accumulated, value, index) => index % 2 === 0 ? `$
     }
   };
 }
-function createConnectionLedger(limits, isLiveCapability) {
+function createConnectionLedger(limits, isLiveCapability2) {
   const pending = /* @__PURE__ */ new Map();
   const authenticated = /* @__PURE__ */ new Map();
   let tunnels = 0;
@@ -2863,7 +2876,7 @@ function createConnectionLedger(limits, isLiveCapability) {
   };
   const revalidation = setInterval(() => {
     for (const [capability, sockets] of authenticated) {
-      if (!isLiveCapability(capability)) {
+      if (!isLiveCapability2(capability)) {
         for (const socket of sockets) {
           socket.destroy();
         }
@@ -3105,6 +3118,40 @@ var ExemptTlsAgent = class extends https.Agent {
     return tls.connect(tlsOptions);
   }
 };
+function realRcEventDial(target = { host: CONNECT_INTERCEPT_HOST, port: HTTPS_PORT }) {
+  const agent = new ExemptTlsAgent();
+  return {
+    writeEvents: async (sessionId, headers, body) => await new Promise((resolve, reject) => {
+      const options = {
+        host: target.host,
+        port: target.port,
+        method: "POST",
+        path: `/v1/code/sessions/${encodeURIComponent(sessionId)}/events`,
+        // The Host header names the host whose API this is, not the address dialled: a redirected test dials a loopback stand-in while still speaking to the API host by name, exactly as the forwarded paths present their SNI.
+        headers: { ...headers, host: target.servername ?? target.host, "content-length": String(Buffer.byteLength(body, "utf8")) },
+        agent
+      };
+      options.servername = target.servername ?? target.host;
+      if (target.ca !== void 0) {
+        options.ca = [...target.ca];
+      }
+      if (target.rejectUnauthorized !== void 0) {
+        options.rejectUnauthorized = target.rejectUnauthorized;
+      }
+      const request4 = https.request(options, (response) => {
+        const chunks = [];
+        response.on("data", (chunk) => {
+          chunks.push(chunk);
+        });
+        response.on("end", () => {
+          resolve({ status: response.statusCode ?? HTTP_BAD_GATEWAY, body: Buffer.concat(chunks).toString("utf8") });
+        });
+      });
+      request4.once("error", reject);
+      request4.end(body);
+    })
+  };
+}
 function realConnectEffects() {
   const plainAgent = new ExemptHttpAgent();
   const tlsAgent = new ExemptTlsAgent();
@@ -3210,8 +3257,8 @@ function realConnectEffects() {
         socket.destroy();
       });
       if (onUpgrade !== void 0) {
-        server.on("upgrade", (request3, socket, head) => {
-          onUpgrade(request3, socket, head);
+        server.on("upgrade", (request4, socket, head) => {
+          onUpgrade(request4, socket, head);
         });
       }
       return {
@@ -3250,14 +3297,14 @@ function realConnectEffects() {
       });
       socket.once("error", reject);
     }),
-    forwardHttp: (target, request3, response, observer) => {
-      const headers = forwardableHeaders(request3.headers);
+    forwardHttp: (target, request4, response, observer) => {
+      const headers = forwardableHeaders(request4.headers);
       const options = {
         host: target.host,
         port: target.port,
         lookup: realAddressLookup,
-        method: request3.method,
-        path: request3.url,
+        method: request4.method,
+        path: request4.url,
         headers,
         agent: target.tls ? tlsAgent : plainAgent
       };
@@ -3292,15 +3339,15 @@ function realConnectEffects() {
         response.end(body);
       });
       if (observer !== void 0) {
-        request3.on("data", (chunk) => {
+        request4.on("data", (chunk) => {
           observer.onRequestChunk(chunk);
         });
         response.on("close", () => {
           observer.onEnd();
         });
       }
-      request3.pipe(upstream);
-      request3.socket.setNoDelay(true);
+      request4.pipe(upstream);
+      request4.socket.setNoDelay(true);
       upstream.on("socket", (socket) => {
         socket.setNoDelay(true);
       });
@@ -3308,11 +3355,488 @@ function realConnectEffects() {
   };
 }
 
+// src/codex/http.ts
+var HTTP_STATUS = {
+  ok: 200,
+  badRequest: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  notFound: 404,
+  methodNotAllowed: 405,
+  payloadTooLarge: 413,
+  tooManyRequests: 429,
+  /** Not sent to anyone: the client is gone. Recorded for a response abandoned because the client disconnected, following the convention nginx uses for the same case. */
+  clientClosedRequest: 499,
+  internalServerError: 500,
+  badGateway: 502
+};
+
+// src/frontdoor/rcSessions.ts
+var RC_SESSIONS_PATH_PREFIX = "/v1/code/sessions";
+var RC_SESSION_ID_PREFIX = "cse_";
+var RC_IDLE_EXPIRY_MS = 45e3;
+var RC_CREATE_RESPONSE_CAP_BYTES = 8192;
+var CONFLICT_REASON_HEADER = "x-ccr-conflict-reason";
+var SUCCESS_STATUS_MAX_EXCLUSIVE = 300;
+function isSuccessful(status) {
+  return status >= HTTP_STATUS.ok && status < SUCCESS_STATUS_MAX_EXCLUSIVE;
+}
+function singleHeader(headers, name) {
+  const value = headers[name];
+  return typeof value === "string" ? value : void 0;
+}
+function sessionCreateId(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("session" in parsed)) {
+    return void 0;
+  }
+  const session = parsed.session;
+  if (typeof session !== "object" || session === null || !("id" in session)) {
+    return void 0;
+  }
+  const id = session.id;
+  return typeof id === "string" && id.startsWith(RC_SESSION_ID_PREFIX) ? id : void 0;
+}
+function createRcSessionTracker(deps) {
+  const entries = /* @__PURE__ */ new Map();
+  const expire = (id) => {
+    entries.delete(id);
+  };
+  const sweep = () => {
+    for (const [id, entry] of entries) {
+      if (deps.now() - entry.lastSeenAt >= deps.idleMs) {
+        expire(id);
+      }
+    }
+  };
+  const timer = setInterval(sweep, deps.idleMs);
+  timer.unref();
+  const observeExchange = (request4) => {
+    const method = (request4.method ?? "").toUpperCase();
+    const path29 = new URL(request4.url ?? "/", "http://127.0.0.1").pathname;
+    if (!path29.startsWith(RC_SESSIONS_PATH_PREFIX)) {
+      return void 0;
+    }
+    const tail = path29.slice(RC_SESSIONS_PATH_PREFIX.length);
+    const facts = {
+      authorization: singleHeader(request4.headers, "authorization"),
+      anthropicVersion: singleHeader(request4.headers, "anthropic-version"),
+      anthropicClientPlatform: singleHeader(request4.headers, "anthropic-client-platform")
+    };
+    if (tail === "") {
+      if (method !== "POST") {
+        return void 0;
+      }
+      let accepted = false;
+      let buffered = 0;
+      let body = "";
+      return {
+        onResponse: (status) => {
+          accepted = isSuccessful(status);
+        },
+        onBodyChunk: (chunk) => {
+          if (!accepted || buffered >= RC_CREATE_RESPONSE_CAP_BYTES) {
+            return;
+          }
+          const text = Buffer.from(chunk).toString("utf8");
+          body = body + text.slice(0, RC_CREATE_RESPONSE_CAP_BYTES - buffered);
+          buffered = body.length;
+        },
+        onEnd: () => {
+          if (!accepted) {
+            return;
+          }
+          const id2 = sessionCreateId(body);
+          if (id2 === void 0) {
+            return;
+          }
+          entries.set(id2, { id: id2, createdAt: deps.now(), lastSeenAt: deps.now(), ...facts });
+        }
+      };
+    }
+    const rest = tail.slice(1);
+    const [id] = rest.split("/");
+    if (id?.startsWith(RC_SESSION_ID_PREFIX) !== true) {
+      return void 0;
+    }
+    const entry = entries.get(id);
+    if (entry === void 0) {
+      entries.set(id, { id, createdAt: deps.now(), lastSeenAt: deps.now(), ...facts });
+    } else {
+      entry.lastSeenAt = deps.now();
+      entry.authorization = facts.authorization ?? entry.authorization;
+      entry.anthropicVersion = facts.anthropicVersion ?? entry.anthropicVersion;
+      entry.anthropicClientPlatform = facts.anthropicClientPlatform ?? entry.anthropicClientPlatform;
+    }
+    const archiving = method === "POST" && rest === `${id}/archive`;
+    return {
+      onResponse: (status, headers) => {
+        if (singleHeader(headers, CONFLICT_REASON_HEADER) !== void 0 || archiving && isSuccessful(status)) {
+          expire(id);
+        }
+      },
+      onBodyChunk: () => {
+      },
+      onEnd: () => {
+      }
+    };
+  };
+  return {
+    observeExchange,
+    list: () => {
+      sweep();
+      return [...entries.values()].sort((left, right) => left.createdAt - right.createdAt || (left.id < right.id ? -1 : 1)).map(({ id, createdAt, lastSeenAt }) => ({ id, createdAt, lastSeenAt }));
+    },
+    credentialOf: (sessionId) => {
+      const entry = entries.get(sessionId);
+      return entry === void 0 ? void 0 : { authorization: entry.authorization, anthropicVersion: entry.anthropicVersion, anthropicClientPlatform: entry.anthropicClientPlatform };
+    },
+    close: () => {
+      clearInterval(timer);
+    }
+  };
+}
+function observingRoutedRoute(route, tracker) {
+  return {
+    ...route,
+    serve: async (request4, response) => {
+      const observed = tracker.observeExchange({ method: request4.method, url: request4.url, headers: request4.headers });
+      await route.serve(request4, observed === void 0 ? response : teeRoutedResponse(response, observed));
+    }
+  };
+}
+function teeRoutedResponse(response, observer) {
+  return {
+    get headersSent() {
+      return response.headersSent;
+    },
+    start: (status, headers) => {
+      observer.onResponse(status, headers);
+      response.start(status, headers);
+    },
+    flush: () => {
+      response.flush();
+    },
+    write: async (chunk) => {
+      observer.onBodyChunk(typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk);
+      await response.write(chunk);
+    },
+    end: () => {
+      response.end();
+      observer.onEnd();
+    },
+    destroy: () => {
+      response.destroy();
+      observer.onEnd();
+    }
+  };
+}
+function rcObserverAsPassthrough(observer) {
+  return {
+    // The request body carries nothing the tracker reads: the credential and the session id are in the request's headers and path, already handed over with the request.
+    onRequestChunk: () => {
+      return;
+    },
+    onResponse: (status, headers) => {
+      observer.onResponse(status, headers);
+    },
+    onResponseChunk: (chunk) => {
+      observer.onBodyChunk(chunk);
+    },
+    onEnd: () => {
+      observer.onEnd();
+    }
+  };
+}
+function buildRcUserMessagePayload(uuid, sessionId, text) {
+  return {
+    type: "user",
+    uuid,
+    session_id: sessionId,
+    parent_tool_use_id: null,
+    message: { role: "user", content: text }
+  };
+}
+function buildRcEventWriteBody(payload) {
+  return { events: [{ payload }] };
+}
+function sequenceNumsOf(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("results" in parsed) || !Array.isArray(parsed.results)) {
+    return void 0;
+  }
+  const sequenceNums = [];
+  const results = parsed.results;
+  for (const result of results) {
+    if (typeof result !== "object" || result === null || !("sequence_num" in result)) {
+      return void 0;
+    }
+    const sequenceNum = result.sequence_num;
+    if (typeof sequenceNum !== "number") {
+      return void 0;
+    }
+    sequenceNums.push(sequenceNum);
+  }
+  return sequenceNums.length === 0 ? void 0 : sequenceNums;
+}
+function rcInjectResultFromAnswer(answer) {
+  if (!isSuccessful(answer.status)) {
+    if (answer.status === HTTP_STATUS.unauthorized) {
+      return { ok: false, message: `the API refused the observed Authorization bearer for this session (HTTP 401): the bearer went stale after the door last saw the session's traffic. The session's own client refreshes it on its next call, which the door will observe, so retry once Remote Control has been active again. API answer: ${answer.body}` };
+    }
+    return { ok: false, message: `the API answered HTTP ${String(answer.status)} to the injected event: ${answer.body}` };
+  }
+  const sequenceNums = sequenceNumsOf(answer.body);
+  if (sequenceNums === void 0) {
+    return { ok: false, message: `the API accepted the injected event but its answer named no results[].sequence_num, so delivery cannot be confirmed: ${answer.body}` };
+  }
+  return { ok: true, sequenceNums };
+}
+async function injectRcUserMessage(deps, sessionId, text) {
+  const credential = deps.credentialOf(sessionId);
+  if (credential === void 0) {
+    return { ok: false, message: `the front door has not observed Remote Control session ${sessionId}: it may never have passed through this door, or it ended or expired (an entry lives only a bounded idle period past its last observed traffic)` };
+  }
+  const headers = { "content-type": "application/json" };
+  if (credential.authorization !== void 0) {
+    headers.authorization = credential.authorization;
+  }
+  if (credential.anthropicVersion !== void 0) {
+    headers["anthropic-version"] = credential.anthropicVersion;
+  }
+  if (credential.anthropicClientPlatform !== void 0) {
+    headers["anthropic-client-platform"] = credential.anthropicClientPlatform;
+  }
+  const body = JSON.stringify(buildRcEventWriteBody(buildRcUserMessagePayload(deps.newUuid(), sessionId, text)));
+  let answer;
+  try {
+    answer = await deps.dial.writeEvents(sessionId, headers, body);
+  } catch (error) {
+    return { ok: false, message: `the door could not reach the API host to inject into session ${sessionId}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  return rcInjectResultFromAnswer(answer);
+}
+
+// src/frontdoor/rcControl.ts
+import * as https2 from "node:https";
+var CONTROL_PATH_PREFIX = "/__agent-shim/rc";
+var CONTROL_BODY_CAP_BYTES = 10485760;
+function answerJson(response, status, body) {
+  const text = JSON.stringify(body);
+  response.writeHead(status, { "content-type": "application/json", "content-length": String(Buffer.byteLength(text, "utf8")) });
+  response.end(text);
+}
+async function readBody(request4) {
+  return await new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    request4.on("data", (chunk) => {
+      total += chunk.length;
+      if (total > CONTROL_BODY_CAP_BYTES) {
+        request4.destroy();
+        reject(new Error("too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request4.on("end", () => {
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    request4.on("error", () => {
+      reject(new Error("the request body ended early"));
+    });
+  });
+}
+function createRcControlHandler(deps) {
+  const sessionsPath = `${CONTROL_PATH_PREFIX}/sessions`;
+  const injectPath = `${CONTROL_PATH_PREFIX}/inject`;
+  return (request4, response) => {
+    const presented = request4.headers.authorization;
+    const bearerPrefix = "bearer ".length;
+    const token = typeof presented === "string" && presented.slice(0, bearerPrefix).toLowerCase() === "bearer " ? presented.slice(bearerPrefix) : void 0;
+    if (token === void 0 || !isLiveCapability(token, [deps.expectedToken])) {
+      answerJson(response, HTTP_STATUS.unauthorized, { error: "the front door's control routes demand this generation's control token as a Bearer credential" });
+      return;
+    }
+    const url = request4.url ?? "/";
+    const handle = async () => {
+      if (url === sessionsPath) {
+        if (request4.method !== "GET") {
+          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: "the session list is a GET" });
+          return;
+        }
+        answerJson(response, HTTP_STATUS.ok, { sessions: deps.list() });
+        return;
+      }
+      if (url === injectPath) {
+        if (request4.method !== "POST") {
+          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: "the inject operation is a POST" });
+          return;
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(await readBody(request4));
+        } catch {
+          answerJson(response, HTTP_STATUS.badRequest, { error: "the inject body is not readable JSON within the control body cap" });
+          return;
+        }
+        if (typeof parsed !== "object" || parsed === null || !("session" in parsed) || !("text" in parsed) || typeof parsed.session !== "string" || typeof parsed.text !== "string" || parsed.session === "" || parsed.text === "") {
+          answerJson(response, HTTP_STATUS.badRequest, { error: "the inject body must be JSON naming a non-empty session id and text" });
+          return;
+        }
+        const result = await deps.inject(parsed.session, parsed.text);
+        if (result.ok) {
+          answerJson(response, HTTP_STATUS.ok, { session: parsed.session, sequenceNums: result.sequenceNums });
+          return;
+        }
+        answerJson(response, HTTP_STATUS.badGateway, { error: result.message });
+        return;
+      }
+      answerJson(response, HTTP_STATUS.notFound, { error: `no such control route: ${url}` });
+    };
+    handle().catch((error) => {
+      answerJson(response, HTTP_STATUS.internalServerError, { error: `the control route failed: ${error instanceof Error ? error.message : String(error)}` });
+    });
+  };
+}
+function realRcControlTransport(port, ca) {
+  return {
+    request: async (options) => await new Promise((resolve, reject) => {
+      const request4 = https2.request(
+        {
+          host: "127.0.0.1",
+          port,
+          method: options.method,
+          path: options.path,
+          headers: options.body === void 0 ? options.headers : { ...options.headers, "content-length": String(Buffer.byteLength(options.body, "utf8")) },
+          agent: false,
+          ca: [ca]
+        },
+        (response) => {
+          const chunks = [];
+          response.on("data", (chunk) => {
+            chunks.push(chunk);
+          });
+          response.on("end", () => {
+            resolve({ status: response.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") });
+          });
+        }
+      );
+      request4.once("error", reject);
+      if (options.body === void 0) {
+        request4.end();
+      } else {
+        request4.end(options.body);
+      }
+    })
+  };
+}
+function controlErrorOf(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed === "object" && parsed !== null && "error" in parsed && typeof parsed.error === "string") {
+      return parsed.error;
+    }
+  } catch {
+    return body;
+  }
+  return void 0;
+}
+function isRcSessionSummary(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if (!("id" in value) || !("createdAt" in value) || !("lastSeenAt" in value)) {
+    return false;
+  }
+  return typeof value.id === "string" && typeof value.createdAt === "number" && typeof value.lastSeenAt === "number";
+}
+function sequenceNumsOfBody(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("sequenceNums" in parsed) || !Array.isArray(parsed.sequenceNums)) {
+    return void 0;
+  }
+  const sequenceNums = [];
+  const values = parsed.sequenceNums;
+  for (const value of values) {
+    if (typeof value !== "number") {
+      return void 0;
+    }
+    sequenceNums.push(value);
+  }
+  return sequenceNums;
+}
+function frontDoorRcControl(transport, token) {
+  const headers = { authorization: `Bearer ${token}` };
+  const sessionsOf = (answer, what) => {
+    if (answer.status !== HTTP_STATUS.ok) {
+      throw new Error(`${what} failed (HTTP ${String(answer.status)}): ${controlErrorOf(answer.body) ?? answer.body}`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(answer.body);
+    } catch {
+      throw new Error(`${what}: the door's answer was not JSON: ${answer.body}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || !("sessions" in parsed) || !Array.isArray(parsed.sessions)) {
+      throw new Error(`${what}: the door's answer named no sessions list: ${answer.body}`);
+    }
+    const candidates = parsed.sessions;
+    const sessions = [];
+    for (const value of candidates) {
+      if (!isRcSessionSummary(value)) {
+        throw new Error(`${what}: the door's answer named no sessions list: ${answer.body}`);
+      }
+      sessions.push(value);
+    }
+    return sessions;
+  };
+  return {
+    listSessions: async () => sessionsOf(await transport.request({ method: "GET", path: `${CONTROL_PATH_PREFIX}/sessions`, headers }), "listing the door's Remote Control sessions"),
+    sendPrompt: async (sessionId, text) => {
+      let answer;
+      try {
+        answer = await transport.request({
+          method: "POST",
+          path: `${CONTROL_PATH_PREFIX}/inject`,
+          headers: { ...headers, "content-type": "application/json" },
+          body: JSON.stringify({ session: sessionId, text })
+        });
+      } catch (error) {
+        return { ok: false, message: `could not reach the front door's control listener: ${error instanceof Error ? error.message : String(error)}` };
+      }
+      if (answer.status === HTTP_STATUS.ok) {
+        const sequenceNums = sequenceNumsOfBody(answer.body);
+        if (sequenceNums === void 0) {
+          return { ok: false, message: `the door accepted the event but its answer named no sequence numbers: ${answer.body}` };
+        }
+        return { ok: true, sequenceNums };
+      }
+      return { ok: false, message: `injecting into ${sessionId} failed (HTTP ${String(answer.status)}): ${controlErrorOf(answer.body) ?? answer.body}` };
+    }
+  };
+}
+
 // src/frontdoor/ensure.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 
 // src/headroom/state.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import path8 from "node:path";
 import { z as z4 } from "zod";
 var HEADROOM_ANTHROPIC_UPSTREAM = "https://api.anthropic.com";
@@ -3373,7 +3897,7 @@ function headroomUpstreams(providers, frontDoorOrigin2) {
   return upstreams;
 }
 function hashAllowlist(allowlist) {
-  return createHash2("sha256").update(allowlist.join("\n")).digest("hex");
+  return createHash3("sha256").update(allowlist.join("\n")).digest("hex");
 }
 function readAllProviders(fs12, providersDir) {
   const result = [];
@@ -3871,7 +4395,7 @@ function ensureHeadroom(params) {
 }
 
 // src/headroom/settings.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 function settingsOf(config) {
   return {
     ...config.mode === void 0 ? {} : { mode: config.mode },
@@ -3896,7 +4420,7 @@ function settingsEnv(settings) {
   return settings.rolloutChannel === void 0 ? {} : { HEADROOM_ROLLOUT_CHANNEL: settings.rolloutChannel };
 }
 function hashSettings(settings) {
-  return createHash3("sha256").update(JSON.stringify([...settingsArgs(settings), JSON.stringify(settingsEnv(settings))])).digest("hex");
+  return createHash4("sha256").update(JSON.stringify([...settingsArgs(settings), JSON.stringify(settingsEnv(settings))])).digest("hex");
 }
 
 // src/headroom/socket.ts
@@ -4327,6 +4851,7 @@ function buildLayoutPaths(root) {
     frontdoorCaBundlesDir: path12.join(root, "frontdoor", "ca", "bundles"),
     frontdoorStateFile: path12.join(root, "frontdoor", "state.json"),
     frontdoorLockFile: path12.join(root, "frontdoor", "start.lock"),
+    frontdoorControlTokenFile: path12.join(root, "frontdoor", "control-token"),
     frontdoorSessionsDir: path12.join(root, "frontdoor", "sessions"),
     frontdoorLogPath: path12.join(root, "logs", "frontdoor.log"),
     usageDir: path12.join(root, "usage"),
@@ -5821,7 +6346,7 @@ function collectPoolPick(params) {
 
 // src/realPorts.ts
 import { spawn, spawnSync } from "node:child_process";
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 import fs7 from "node:fs";
 import os3 from "node:os";
 import path21 from "node:path";
@@ -6016,7 +6541,7 @@ var realFarmFs = {
   },
   hashFile(filePath) {
     try {
-      return createHash4("sha256").update(fs7.readFileSync(filePath)).digest("hex");
+      return createHash5("sha256").update(fs7.readFileSync(filePath)).digest("hex");
     } catch (error) {
       if (isEnoent3(error) || isErrorWithCode(error, "EISDIR")) {
         return void 0;
@@ -8012,7 +8537,7 @@ function probeFrontDoorSync(port, caPem) {
 }
 
 // src/frontdoor/trust.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 import path28 from "node:path";
 var BUNDLE_NAME_HEX_DIGITS = 16;
 function resolveTrustBundle(params) {
@@ -8035,7 +8560,7 @@ function resolveTrustBundle(params) {
   }
   const combined = `${inheritedPem.trimEnd()}
 ${caPem}`;
-  const bundle = path28.join(bundlesDir, `${createHash5("sha256").update(combined).digest("hex").slice(0, BUNDLE_NAME_HEX_DIGITS)}.pem`);
+  const bundle = path28.join(bundlesDir, `${createHash6("sha256").update(combined).digest("hex").slice(0, BUNDLE_NAME_HEX_DIGITS)}.pem`);
   if (!fs12.exists(bundle)) {
     fs12.mkdirp(bundlesDir);
     fs12.writeFileAtomic(bundle, combined);
@@ -8178,6 +8703,7 @@ export {
   CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS,
+  CONTROL_PATH_PREFIX,
   CategoryClassificationOverlaySchema,
   CategoryClassificationSchema,
   CategoryMapSchema,
@@ -8216,6 +8742,8 @@ export {
   ProviderKindMismatchError,
   ProviderNotFoundError,
   ProviderSchema,
+  RC_IDLE_EXPIRY_MS,
+  RC_SESSIONS_PATH_PREFIX,
   ROUTED_PATH_PREFIX,
   UsageError,
   UsageSnapshotError,
@@ -8227,6 +8755,8 @@ export {
   addProvider,
   buildEntryFacts,
   buildLayoutPaths,
+  buildRcEventWriteBody,
+  buildRcUserMessagePayload,
   carryOver,
   checkReportHasWarnings,
   checkReportToJson,
@@ -8234,6 +8764,8 @@ export {
   collectDoctorReport,
   createLeafCache,
   createProfile,
+  createRcControlHandler,
+  createRcSessionTracker,
   describeProviderEndpoint,
   detectAmbientCredential,
   ensureCa,
@@ -8244,8 +8776,10 @@ export {
   formatCheckReport,
   formatDoctorReport,
   forwardableHeaders,
+  frontDoorRcControl,
   generateCa,
   identityExists,
+  injectRcUserMessage,
   isIdentityDirectoryName,
   isInterceptedHost,
   listDirectoryRules,
@@ -8254,11 +8788,14 @@ export {
   listProviders,
   listUsageSnapshots,
   mintLeaf,
+  observingRoutedRoute,
   parseConnectTarget,
   prepareClaudeLaunch,
   prepareLaunch,
   profileExists,
   providerExists,
+  rcInjectResultFromAnswer,
+  rcObserverAsPassthrough,
   readActiveIdentity,
   readDirectoryRules,
   readFarmManifest,
@@ -8270,6 +8807,8 @@ export {
   readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
+  realRcControlTransport,
+  realRcEventDial,
   recoverFarm,
   recoveryDiagnostics,
   removeDirectoryRule,