agent-shim 8.2.0 → 8.3.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   CONNECT_INTERCEPT_HOST: () => CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS: () => CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS: () => CONNECT_LIMITS,
+  CONTROL_PATH_PREFIX: () => CONTROL_PATH_PREFIX,
   CategoryClassificationOverlaySchema: () => CategoryClassificationOverlaySchema,
   CategoryClassificationSchema: () => CategoryClassificationSchema,
   CategoryMapSchema: () => CategoryMapSchema,
@@ -72,6 +73,8 @@ __export(index_exports, {
   ProviderKindMismatchError: () => ProviderKindMismatchError,
   ProviderNotFoundError: () => ProviderNotFoundError,
   ProviderSchema: () => ProviderSchema,
+  RC_IDLE_EXPIRY_MS: () => RC_IDLE_EXPIRY_MS,
+  RC_SESSIONS_PATH_PREFIX: () => RC_SESSIONS_PATH_PREFIX,
   ROUTED_PATH_PREFIX: () => ROUTED_PATH_PREFIX,
   UsageError: () => UsageError,
   UsageSnapshotError: () => UsageSnapshotError,
@@ -83,6 +86,8 @@ __export(index_exports, {
   addProvider: () => addProvider,
   buildEntryFacts: () => buildEntryFacts,
   buildLayoutPaths: () => buildLayoutPaths,
+  buildRcEventWriteBody: () => buildRcEventWriteBody,
+  buildRcUserMessagePayload: () => buildRcUserMessagePayload,
   carryOver: () => carryOver,
   checkReportHasWarnings: () => checkReportHasWarnings,
   checkReportToJson: () => checkReportToJson,
@@ -90,6 +95,8 @@ __export(index_exports, {
   collectDoctorReport: () => collectDoctorReport,
   createLeafCache: () => createLeafCache,
   createProfile: () => createProfile,
+  createRcControlHandler: () => createRcControlHandler,
+  createRcSessionTracker: () => createRcSessionTracker,
   describeProviderEndpoint: () => describeProviderEndpoint,
   detectAmbientCredential: () => detectAmbientCredential,
   ensureCa: () => ensureCa,
@@ -100,8 +107,10 @@ __export(index_exports, {
   formatCheckReport: () => formatCheckReport,
   formatDoctorReport: () => formatDoctorReport,
   forwardableHeaders: () => forwardableHeaders,
+  frontDoorRcControl: () => frontDoorRcControl,
   generateCa: () => generateCa,
   identityExists: () => identityExists,
+  injectRcUserMessage: () => injectRcUserMessage,
   isIdentityDirectoryName: () => isIdentityDirectoryName,
   isInterceptedHost: () => isInterceptedHost,
   listDirectoryRules: () => listDirectoryRules,
@@ -110,11 +119,14 @@ __export(index_exports, {
   listProviders: () => listProviders,
   listUsageSnapshots: () => listUsageSnapshots,
   mintLeaf: () => mintLeaf,
+  observingRoutedRoute: () => observingRoutedRoute,
   parseConnectTarget: () => parseConnectTarget,
   prepareClaudeLaunch: () => prepareClaudeLaunch,
   prepareLaunch: () => prepareLaunch,
   profileExists: () => profileExists,
   providerExists: () => providerExists,
+  rcInjectResultFromAnswer: () => rcInjectResultFromAnswer,
+  rcObserverAsPassthrough: () => rcObserverAsPassthrough,
   readActiveIdentity: () => readActiveIdentity,
   readDirectoryRules: () => readDirectoryRules,
   readFarmManifest: () => readFarmManifest,
@@ -126,6 +138,8 @@ __export(index_exports, {
   readUsageSnapshot: () => readUsageSnapshot,
   realConnectCertStore: () => realConnectCertStore,
   realConnectEffects: () => realConnectEffects,
+  realRcControlTransport: () => realRcControlTransport,
+  realRcEventDial: () => realRcEventDial,
   recoverFarm: () => recoverFarm,
   recoveryDiagnostics: () => recoveryDiagnostics,
   removeDirectoryRule: () => removeDirectoryRule,
@@ -2289,7 +2303,7 @@ function recoveryDiagnostics(recovery, identity) {
 }
 
 // src/frontdoor/connect.ts
-var import_node_crypto4 = require("node:crypto");
+var import_node_crypto5 = require("node:crypto");
 var fs2 = __toESM(require("node:fs"), 1);
 
 // src/frontdoor/x509.ts
@@ -2615,6 +2629,7 @@ function pumpTapSession(secure, openUpstream, tap, prefix = Buffer.alloc(0)) {
 }
 
 // src/frontdoor/capability.ts
+var import_node_crypto4 = require("node:crypto");
 var CONNECT_PROXY_USER = "agent-shim";
 var CONNECT_PROXY_REALM = "agent-shim front door";
 var BASIC_SCHEME = "basic";
@@ -2635,6 +2650,18 @@ function capabilityFromProxyAuthorization(value) {
   const password = userPass.slice(colon + 1);
   return password === "" ? void 0 : password;
 }
+function digest(token) {
+  return (0, import_node_crypto4.createHash)("sha256").update(token, "utf8").digest();
+}
+function isLiveCapability(presented, live) {
+  const presentedDigest = digest(presented);
+  let matched = false;
+  for (const token of live) {
+    const equal = (0, import_node_crypto4.timingSafeEqual)(presentedDigest, digest(token));
+    matched = equal || matched;
+  }
+  return matched;
+}
 
 // src/frontdoor/route.ts
 var IDENTITY_HEADER = "x-agent-shim-identity";
@@ -2935,8 +2962,8 @@ function ensureCa(store, generate) {
 }
 function caParses(ca) {
   try {
-    new import_node_crypto4.X509Certificate(ca.certPem);
-    (0, import_node_crypto4.createPrivateKey)(ca.keyPem);
+    new import_node_crypto5.X509Certificate(ca.certPem);
+    (0, import_node_crypto5.createPrivateKey)(ca.keyPem);
     return true;
   } catch {
     return false;
@@ -2945,14 +2972,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"));
@@ -2965,16 +2992,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) => {
@@ -3016,7 +3043,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;
@@ -3029,7 +3056,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();
         }
@@ -3271,6 +3298,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();
@@ -3376,8 +3437,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 {
@@ -3416,14 +3477,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
       };
@@ -3458,15 +3519,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);
       });
@@ -3474,11 +3535,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
+var https2 = __toESM(require("node:https"), 1);
+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
-var import_node_crypto6 = require("node:crypto");
+var import_node_crypto7 = require("node:crypto");
 
 // src/headroom/state.ts
-var import_node_crypto5 = require("node:crypto");
+var import_node_crypto6 = require("node:crypto");
 var import_node_path8 = __toESM(require("node:path"), 1);
 var import_zod4 = require("zod");
 var HEADROOM_ANTHROPIC_UPSTREAM = "https://api.anthropic.com";
@@ -3539,7 +4077,7 @@ function headroomUpstreams(providers, frontDoorOrigin2) {
   return upstreams;
 }
 function hashAllowlist(allowlist) {
-  return (0, import_node_crypto5.createHash)("sha256").update(allowlist.join("\n")).digest("hex");
+  return (0, import_node_crypto6.createHash)("sha256").update(allowlist.join("\n")).digest("hex");
 }
 function readAllProviders(fs12, providersDir) {
   const result = [];
@@ -3638,7 +4176,7 @@ function ensureFrontDoor(params) {
           continue;
         }
         if (verdict.ok) {
-          const token = (0, import_node_crypto6.randomUUID)();
+          const token = (0, import_node_crypto7.randomUUID)();
           writeFrontDoorSession(ports.fs, paths.frontdoorSessionsDir, { pid: params.launcherPid, startedAt: ports.now(), token });
           return { port: state.port, connectPort: state.connectPort, token };
         }
@@ -4037,7 +4575,7 @@ function ensureHeadroom(params) {
 }
 
 // src/headroom/settings.ts
-var import_node_crypto7 = require("node:crypto");
+var import_node_crypto8 = require("node:crypto");
 function settingsOf(config) {
   return {
     ...config.mode === void 0 ? {} : { mode: config.mode },
@@ -4062,7 +4600,7 @@ function settingsEnv(settings) {
   return settings.rolloutChannel === void 0 ? {} : { HEADROOM_ROLLOUT_CHANNEL: settings.rolloutChannel };
 }
 function hashSettings(settings) {
-  return (0, import_node_crypto7.createHash)("sha256").update(JSON.stringify([...settingsArgs(settings), JSON.stringify(settingsEnv(settings))])).digest("hex");
+  return (0, import_node_crypto8.createHash)("sha256").update(JSON.stringify([...settingsArgs(settings), JSON.stringify(settingsEnv(settings))])).digest("hex");
 }
 
 // src/headroom/socket.ts
@@ -4493,6 +5031,7 @@ function buildLayoutPaths(root) {
     frontdoorCaBundlesDir: import_node_path12.default.join(root, "frontdoor", "ca", "bundles"),
     frontdoorStateFile: import_node_path12.default.join(root, "frontdoor", "state.json"),
     frontdoorLockFile: import_node_path12.default.join(root, "frontdoor", "start.lock"),
+    frontdoorControlTokenFile: import_node_path12.default.join(root, "frontdoor", "control-token"),
     frontdoorSessionsDir: import_node_path12.default.join(root, "frontdoor", "sessions"),
     frontdoorLogPath: import_node_path12.default.join(root, "logs", "frontdoor.log"),
     usageDir: import_node_path12.default.join(root, "usage"),
@@ -5987,7 +6526,7 @@ function collectPoolPick(params) {
 
 // src/realPorts.ts
 var import_node_child_process = require("node:child_process");
-var import_node_crypto8 = require("node:crypto");
+var import_node_crypto9 = require("node:crypto");
 var import_node_fs6 = __toESM(require("node:fs"), 1);
 var import_node_os3 = __toESM(require("node:os"), 1);
 var import_node_path21 = __toESM(require("node:path"), 1);
@@ -6182,7 +6721,7 @@ var realFarmFs = {
   },
   hashFile(filePath) {
     try {
-      return (0, import_node_crypto8.createHash)("sha256").update(import_node_fs6.default.readFileSync(filePath)).digest("hex");
+      return (0, import_node_crypto9.createHash)("sha256").update(import_node_fs6.default.readFileSync(filePath)).digest("hex");
     } catch (error) {
       if (isEnoent3(error) || isErrorWithCode(error, "EISDIR")) {
         return void 0;
@@ -7375,7 +7914,7 @@ function collectDoctorReport(params) {
 }
 
 // src/launcher.ts
-var import_node_crypto9 = require("node:crypto");
+var import_node_crypto10 = require("node:crypto");
 var import_node_path26 = __toESM(require("node:path"), 1);
 
 // src/launcher/argv.ts
@@ -8017,7 +8556,7 @@ function prepareLaunch(params) {
     ...identityCredential === void 0 ? {} : { identityCredential },
     ...frontDoor === void 0 ? {} : { frontdoor: frontDoor },
     ...headroom === void 0 ? {} : { headroom },
-    sessionId: (0, import_node_crypto9.randomUUID)()
+    sessionId: (0, import_node_crypto10.randomUUID)()
   });
   const releases = [...headroom === void 0 || headroomPort === void 0 ? [] : [headroomPort.release], ...frontDoorRelease === void 0 ? [] : [frontDoorRelease]];
   const release = () => {
@@ -8030,7 +8569,7 @@ function prepareLaunch(params) {
 
 // src/launchWiring.ts
 var import_node_os5 = __toESM(require("node:os"), 1);
-var import_node_crypto11 = require("node:crypto");
+var import_node_crypto12 = require("node:crypto");
 
 // src/realCredentialCache.ts
 var import_node_child_process2 = require("node:child_process");
@@ -8178,7 +8717,7 @@ function probeFrontDoorSync(port, caPem) {
 }
 
 // src/frontdoor/trust.ts
-var import_node_crypto10 = require("node:crypto");
+var import_node_crypto11 = require("node:crypto");
 var import_node_path28 = __toESM(require("node:path"), 1);
 var BUNDLE_NAME_HEX_DIGITS = 16;
 function resolveTrustBundle(params) {
@@ -8201,7 +8740,7 @@ function resolveTrustBundle(params) {
   }
   const combined = `${inheritedPem.trimEnd()}
 ${caPem}`;
-  const bundle = import_node_path28.default.join(bundlesDir, `${(0, import_node_crypto10.createHash)("sha256").update(combined).digest("hex").slice(0, BUNDLE_NAME_HEX_DIGITS)}.pem`);
+  const bundle = import_node_path28.default.join(bundlesDir, `${(0, import_node_crypto11.createHash)("sha256").update(combined).digest("hex").slice(0, BUNDLE_NAME_HEX_DIGITS)}.pem`);
   if (!fs12.exists(bundle)) {
     fs12.mkdirp(bundlesDir);
     fs12.writeFileAtomic(bundle, combined);
@@ -8280,7 +8819,7 @@ function buildFarmRuntime(paths, cwd) {
         ...cliOverride === void 0 ? {} : { cliOverride }
       }).input,
       now: () => Date.now(),
-      uniqueSuffix: `${String(process.pid)}.${(0, import_node_crypto11.randomUUID)()}`,
+      uniqueSuffix: `${String(process.pid)}.${(0, import_node_crypto12.randomUUID)()}`,
       // Zombie-aware on purpose: a previous launcher that crashed out of a resync without releasing the lock may sit unreaped, still answering signal 0 as alive, and must read as a dead holder so this launch takes the lock over instead of timing out.
       lock: { pid: process.pid, isRunning: realIsProcessRunning, sleep: realSleepSync }
     },
@@ -8345,6 +8884,7 @@ function prepareClaudeLaunch(options) {
   CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS,
+  CONTROL_PATH_PREFIX,
   CategoryClassificationOverlaySchema,
   CategoryClassificationSchema,
   CategoryMapSchema,
@@ -8383,6 +8923,8 @@ function prepareClaudeLaunch(options) {
   ProviderKindMismatchError,
   ProviderNotFoundError,
   ProviderSchema,
+  RC_IDLE_EXPIRY_MS,
+  RC_SESSIONS_PATH_PREFIX,
   ROUTED_PATH_PREFIX,
   UsageError,
   UsageSnapshotError,
@@ -8394,6 +8936,8 @@ function prepareClaudeLaunch(options) {
   addProvider,
   buildEntryFacts,
   buildLayoutPaths,
+  buildRcEventWriteBody,
+  buildRcUserMessagePayload,
   carryOver,
   checkReportHasWarnings,
   checkReportToJson,
@@ -8401,6 +8945,8 @@ function prepareClaudeLaunch(options) {
   collectDoctorReport,
   createLeafCache,
   createProfile,
+  createRcControlHandler,
+  createRcSessionTracker,
   describeProviderEndpoint,
   detectAmbientCredential,
   ensureCa,
@@ -8411,8 +8957,10 @@ function prepareClaudeLaunch(options) {
   formatCheckReport,
   formatDoctorReport,
   forwardableHeaders,
+  frontDoorRcControl,
   generateCa,
   identityExists,
+  injectRcUserMessage,
   isIdentityDirectoryName,
   isInterceptedHost,
   listDirectoryRules,
@@ -8421,11 +8969,14 @@ function prepareClaudeLaunch(options) {
   listProviders,
   listUsageSnapshots,
   mintLeaf,
+  observingRoutedRoute,
   parseConnectTarget,
   prepareClaudeLaunch,
   prepareLaunch,
   profileExists,
   providerExists,
+  rcInjectResultFromAnswer,
+  rcObserverAsPassthrough,
   readActiveIdentity,
   readDirectoryRules,
   readFarmManifest,
@@ -8437,6 +8988,8 @@ function prepareClaudeLaunch(options) {
   readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
+  realRcControlTransport,
+  realRcEventDial,
   recoverFarm,
   recoveryDiagnostics,
   removeDirectoryRule,