agent-shim 8.23.0 → 8.25.0

package/dist/index.mjs

@@ -3207,9 +3207,6 @@ var HTTP_STATUS = {
   badGateway: 502
 };
 
-// src/frontdoor/rcControl.ts
-import * as https from "node:https";
-
 // src/frontdoor/rcSessions.ts
 var RC_SESSIONS_PATH_PREFIX = "/v1/code/sessions";
 var RC_SESSION_ID_PREFIX = "cse_";
@@ -3630,6 +3627,8 @@ function rcObserverAsPassthrough(observer) {
     }
   };
 }
+
+// src/frontdoor/rcWrites.ts
 function buildRcUserMessagePayload(uuid, sessionId, text) {
   return {
     type: "user",
@@ -3730,14 +3729,55 @@ var RC_PERMISSION_MODES = ["default", "acceptEdits", "bypassPermissions", "plan"
 function isRcPermissionMode(value) {
   return RC_PERMISSION_MODES.some((mode) => mode === value);
 }
+function buildRcControlRequestPayload(requestId, request4) {
+  return { type: "control_request", request_id: requestId, request: request4 };
+}
 function buildRcInterruptPayload(requestId) {
-  return { type: "control_request", request_id: requestId, request: { subtype: "interrupt" } };
+  return buildRcControlRequestPayload(requestId, { subtype: "interrupt" });
 }
 function buildRcSetModelPayload(requestId, model) {
-  return { type: "control_request", request_id: requestId, request: { subtype: "set_model", model } };
+  return buildRcControlRequestPayload(requestId, { subtype: "set_model", model });
 }
 function buildRcSetPermissionModePayload(requestId, mode) {
-  return { type: "control_request", request_id: requestId, request: { subtype: "set_permission_mode", mode } };
+  return buildRcControlRequestPayload(requestId, { subtype: "set_permission_mode", mode });
+}
+function buildRcEndSessionPayload(requestId, reason) {
+  return buildRcControlRequestPayload(requestId, { subtype: "end_session", ...reason === void 0 ? {} : { reason } });
+}
+function buildRcGetUsagePayload(requestId, skipBehaviors) {
+  return buildRcControlRequestPayload(requestId, { subtype: "get_usage", ...skipBehaviors === true ? { skip_behaviors: true } : {} });
+}
+var RC_CONTEXT_USAGE_DETAILS = ["summary", "full"];
+function isRcContextUsageDetail(value) {
+  return RC_CONTEXT_USAGE_DETAILS.some((detail) => detail === value);
+}
+function buildRcGetContextUsagePayload(requestId, detail) {
+  return buildRcControlRequestPayload(requestId, { subtype: "get_context_usage", ...detail === void 0 ? {} : { detail } });
+}
+var RC_READ_FILE_ENCODINGS = ["utf-8", "base64"];
+function isRcReadFileEncoding(value) {
+  return RC_READ_FILE_ENCODINGS.some((encoding) => encoding === value);
+}
+function buildRcReadFilePayload(requestId, path32, options) {
+  return buildRcControlRequestPayload(requestId, { subtype: "read_file", path: path32, ...options?.maxBytes === void 0 ? {} : { max_bytes: options.maxBytes }, ...options?.encoding === void 0 ? {} : { encoding: options.encoding } });
+}
+function buildRcFileSuggestionsPayload(requestId, query) {
+  return buildRcControlRequestPayload(requestId, { subtype: "file_suggestions", query });
+}
+function buildRcMcpStatusPayload(requestId) {
+  return buildRcControlRequestPayload(requestId, { subtype: "mcp_status" });
+}
+function buildRcMcpReconnectPayload(requestId, serverName) {
+  return buildRcControlRequestPayload(requestId, { subtype: "mcp_reconnect", serverName });
+}
+function buildRcMcpAuthenticatePayload(requestId, serverName, redirectUri) {
+  return buildRcControlRequestPayload(requestId, { subtype: "mcp_authenticate", serverName, redirectUri });
+}
+function buildRcMcpOAuthCallbackUrlPayload(requestId, serverName, callbackUrl) {
+  return buildRcControlRequestPayload(requestId, { subtype: "mcp_oauth_callback_url", serverName, callbackUrl });
+}
+function buildRcKeepAlivePayload() {
+  return { type: "keep_alive" };
 }
 async function answerRcControlRequest(deps, sessionId, requestId, decision) {
   const credential = deps.credentialOf(sessionId);
@@ -3764,7 +3804,7 @@ async function answerRcControlRequest(deps, sessionId, requestId, decision) {
   }
   return result;
 }
-async function interruptRcSession(deps, sessionId) {
+async function deliverRcClientPayload(deps, sessionId, payload, action, to = "events") {
   const credential = deps.credentialOf(sessionId);
   if (credential === void 0) {
     return { ok: false, message: rcSessionNotObservedMessage(sessionId) };
@@ -3772,12 +3812,12 @@ async function interruptRcSession(deps, sessionId) {
   if (credential.authorization === void 0) {
     return noOAuthCredentialResult(sessionId);
   }
-  const body = JSON.stringify(buildRcEventWriteBody(buildRcInterruptPayload(deps.newUuid())));
+  const body = JSON.stringify(buildRcEventWriteBody(payload));
   let answer;
   try {
-    answer = await deps.dial.writeEvents(sessionId, rcWriteHeaders(credential), body);
+    answer = await (to === "teleport-events" ? deps.dial.writeTeleportEvents(sessionId, rcWriteHeaders(credential), body) : deps.dial.writeEvents(sessionId, rcWriteHeaders(credential), body));
   } catch (error) {
-    return { ok: false, message: `the door could not reach the API host to interrupt session ${sessionId}: ${error instanceof Error ? error.message : String(error)}` };
+    return { ok: false, message: `the door could not reach the API host to ${action}: ${error instanceof Error ? error.message : String(error)}` };
   }
   const result = rcEventWriteResultFromAnswer(answer);
   if (result.ok) {
@@ -3785,53 +3825,102 @@ async function interruptRcSession(deps, sessionId) {
   }
   return result;
 }
+async function interruptRcSession(deps, sessionId) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcInterruptPayload(requestId), `interrupt session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
 async function setRcSessionModel(deps, sessionId, model) {
   if (model === "") {
     return { ok: false, message: "a set-model write needs a non-empty model id: the SDK's own field treats an omitted or null value as a reset to the session default, which this operation never sends, and an empty string is neither" };
   }
-  const credential = deps.credentialOf(sessionId);
-  if (credential === void 0) {
-    return { ok: false, message: rcSessionNotObservedMessage(sessionId) };
-  }
-  if (credential.authorization === void 0) {
-    return noOAuthCredentialResult(sessionId);
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcSetModelPayload(requestId, model), `set the model on session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function setRcSessionPermissionMode(deps, sessionId, mode) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcSetPermissionModePayload(requestId, mode), `set the permission mode on session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function endRcSession(deps, sessionId, reason) {
+  if (reason === "") {
+    return { ok: false, message: "an end-session write needs either no reason or a non-empty one: the worker reads an absent reason as its own unspecified form, and an empty string is neither" };
   }
-  const body = JSON.stringify(buildRcEventWriteBody(buildRcSetModelPayload(deps.newUuid(), model)));
-  let answer;
-  try {
-    answer = await deps.dial.writeEvents(sessionId, rcWriteHeaders(credential), body);
-  } catch (error) {
-    return { ok: false, message: `the door could not reach the API host to set the model on session ${sessionId}: ${error instanceof Error ? error.message : String(error)}` };
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcEndSessionPayload(requestId, reason), `end session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function getRcSessionUsage(deps, sessionId, skipBehaviors) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcGetUsagePayload(requestId, skipBehaviors), `request the usage of session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function getRcSessionContextUsage(deps, sessionId, detail) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcGetContextUsagePayload(requestId, detail), `request the context usage of session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function readRcSessionFile(deps, sessionId, path32, options) {
+  if (path32 === "") {
+    return { ok: false, message: "a read-file write needs a non-empty path: the SDK's own field names the file the worker resolves against the session's cwd, and an empty string names none" };
   }
-  const result = rcEventWriteResultFromAnswer(answer);
-  if (result.ok) {
-    deps.noteSequenceNums(sessionId, result.sequenceNums);
+  if (options?.maxBytes !== void 0 && (!Number.isInteger(options.maxBytes) || options.maxBytes <= 0)) {
+    return { ok: false, message: "a read-file write's max-bytes is a positive whole number of bytes: the SDK's own field caps the read, and a zero or negative cap reads nothing" };
   }
-  return result;
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcReadFilePayload(requestId, path32, options), `read ${path32} from session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
 }
-async function setRcSessionPermissionMode(deps, sessionId, mode) {
-  const credential = deps.credentialOf(sessionId);
-  if (credential === void 0) {
-    return { ok: false, message: rcSessionNotObservedMessage(sessionId) };
+async function suggestRcSessionFiles(deps, sessionId, query) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcFileSuggestionsPayload(requestId, query), `request file suggestions from session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function getRcSessionMcpStatus(deps, sessionId) {
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcMcpStatusPayload(requestId), `request the MCP status of session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function reconnectRcSessionMcpServer(deps, sessionId, serverName) {
+  if (serverName === "") {
+    return { ok: false, message: "an mcp-reconnect write needs a non-empty server name: the SDK's own field names the server as mcp_status reports it, and an empty string names none" };
   }
-  if (credential.authorization === void 0) {
-    return noOAuthCredentialResult(sessionId);
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcMcpReconnectPayload(requestId, serverName), `reconnect MCP server ${serverName} on session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function authenticateRcSessionMcpServer(deps, sessionId, serverName, redirectUri) {
+  if (serverName === "" || redirectUri === "") {
+    return { ok: false, message: "an mcp-authenticate write needs a non-empty server name and redirect URI: the CLI's own request names the server and where its OAuth flow redirects back to, and an empty string names neither" };
   }
-  const body = JSON.stringify(buildRcEventWriteBody(buildRcSetPermissionModePayload(deps.newUuid(), mode)));
-  let answer;
-  try {
-    answer = await deps.dial.writeEvents(sessionId, rcWriteHeaders(credential), body);
-  } catch (error) {
-    return { ok: false, message: `the door could not reach the API host to set the permission mode on session ${sessionId}: ${error instanceof Error ? error.message : String(error)}` };
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcMcpAuthenticatePayload(requestId, serverName, redirectUri), `authenticate MCP server ${serverName} on session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function submitRcSessionMcpOAuthCallbackUrl(deps, sessionId, serverName, callbackUrl) {
+  if (serverName === "" || callbackUrl === "") {
+    return { ok: false, message: "an mcp-oauth-callback-url write needs a non-empty server name and callback URL: the CLI's own request names the server and the URL its OAuth flow landed on, and an empty string names neither" };
   }
-  const result = rcEventWriteResultFromAnswer(answer);
-  if (result.ok) {
-    deps.noteSequenceNums(sessionId, result.sequenceNums);
+  const requestId = deps.newUuid();
+  const result = await deliverRcClientPayload(deps, sessionId, buildRcMcpOAuthCallbackUrlPayload(requestId, serverName, callbackUrl), `hand MCP server ${serverName}'s OAuth callback to session ${sessionId}`);
+  return result.ok ? { ...result, requestId } : result;
+}
+async function sendRcKeepAlive(deps, sessionId) {
+  return await deliverRcClientPayload(deps, sessionId, buildRcKeepAlivePayload(), `keep session ${sessionId} alive`);
+}
+async function teleportRcSession(deps, sessionId, marker) {
+  if (marker === "") {
+    return { ok: false, message: "a teleport write needs a non-empty marker: the teleport relay anchors on a marker line's uuid and string content, and an empty string carries neither" };
   }
-  return result;
+  return await deliverRcClientPayload(deps, sessionId, buildRcUserMessagePayload(deps.newUuid(), sessionId, marker), `teleport a marker into session ${sessionId}`, "teleport-events");
+}
+function buildRcMarkReadBody(eventId) {
+  return eventId === void 0 ? {} : { event_id: eventId };
 }
 
 // src/frontdoor/rcControl.ts
+import * as https from "node:https";
 var RC_PERMISSION_MODE_LIST = RC_PERMISSION_MODES.join(", ");
 var CONTROL_PATH_PREFIX = "/__agent-shim/rc";
 var CONTROL_BODY_CAP_BYTES = 10485760;
@@ -3840,6 +3929,25 @@ function answerJson(response, status, body) {
   response.writeHead(status, { "content-type": "application/json", "content-length": String(Buffer.byteLength(text, "utf8")) });
   response.end(text);
 }
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function bodyString(body, field) {
+  const value = body[field];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function bodyStringAllowingEmpty(body, field) {
+  const value = body[field];
+  return typeof value === "string" ? value : void 0;
+}
+function bodyBoolean(body, field) {
+  const value = body[field];
+  return typeof value === "boolean" ? value : void 0;
+}
+function bodyPositiveInteger(body, field) {
+  const value = body[field];
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
 async function readBody(request4) {
   return await new Promise((resolve, reject) => {
     const chunks = [];
@@ -3867,9 +3975,136 @@ function createRcControlHandler(deps) {
   const pendingPath = `${CONTROL_PATH_PREFIX}/pending`;
   const injectPath = `${CONTROL_PATH_PREFIX}/inject`;
   const answerPath = `${CONTROL_PATH_PREFIX}/answer`;
-  const interruptPath = `${CONTROL_PATH_PREFIX}/interrupt`;
-  const setModelPath = `${CONTROL_PATH_PREFIX}/set-model`;
-  const setPermissionModePath = `${CONTROL_PATH_PREFIX}/set-permission-mode`;
+  const controlWrites = [
+    {
+      name: "interrupt",
+      path: "interrupt",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        return session === void 0 ? { error: "the interrupt body must be JSON naming a non-empty session id" } : { session, run: async () => await deps.interrupt(session) };
+      }
+    },
+    {
+      name: "set-model",
+      path: "set-model",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const model = bodyString(body, "model");
+        return session === void 0 || model === void 0 ? { error: "the set-model body must be JSON naming a non-empty session id and model id" } : { session, run: async () => await deps.setModel(session, model) };
+      }
+    },
+    {
+      name: "set-permission-mode",
+      path: "set-permission-mode",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const mode = body.mode;
+        return session === void 0 || !isRcPermissionMode(mode) ? { error: `the set-permission-mode body must be JSON naming a non-empty session id and a mode the SDK's own type permits (${RC_PERMISSION_MODE_LIST})` } : { session, run: async () => await deps.setPermissionMode(session, mode) };
+      }
+    },
+    {
+      name: "end-session",
+      path: "end-session",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const reason = "reason" in body ? bodyString(body, "reason") : void 0;
+        return session === void 0 || "reason" in body && reason === void 0 ? { error: "the end-session body must be JSON naming a non-empty session id, and a reason only as a non-empty string or absent" } : { session, run: async () => await deps.endSession(session, reason) };
+      }
+    },
+    {
+      name: "get-usage",
+      path: "get-usage",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const skipBehaviors = "skipBehaviors" in body ? bodyBoolean(body, "skipBehaviors") : void 0;
+        return session === void 0 || "skipBehaviors" in body && skipBehaviors === void 0 ? { error: "the get-usage body must be JSON naming a non-empty session id, and skipBehaviors only as a boolean or absent" } : { session, run: async () => await deps.getUsage(session, skipBehaviors) };
+      }
+    },
+    {
+      name: "get-context-usage",
+      path: "get-context-usage",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const detail = "detail" in body && isRcContextUsageDetail(body.detail) ? body.detail : void 0;
+        return session === void 0 || "detail" in body && detail === void 0 ? { error: `the get-context-usage body must be JSON naming a non-empty session id, and a detail level the SDK's own type permits (${RC_CONTEXT_USAGE_DETAILS.join(", ")}) or none` } : { session, run: async () => await deps.getContextUsage(session, detail) };
+      }
+    },
+    {
+      name: "read-file",
+      path: "read-file",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const path32 = bodyString(body, "path");
+        const maxBytes = "maxBytes" in body ? bodyPositiveInteger(body, "maxBytes") : void 0;
+        const encoding = "encoding" in body && isRcReadFileEncoding(body.encoding) ? body.encoding : void 0;
+        const refused2 = session === void 0 || path32 === void 0 || "maxBytes" in body && maxBytes === void 0 || "encoding" in body && encoding === void 0;
+        return refused2 ? { error: `the read-file body must be JSON naming a non-empty session id and path, maxBytes only as a positive whole number or absent, and an encoding the SDK's own type permits (${RC_READ_FILE_ENCODINGS.join(", ")}) or none` } : { session, run: async () => await deps.readFile(session, path32, { ...maxBytes === void 0 ? {} : { maxBytes }, ...encoding === void 0 ? {} : { encoding } }) };
+      }
+    },
+    {
+      name: "file-suggestions",
+      path: "file-suggestions",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const query = bodyStringAllowingEmpty(body, "query");
+        return session === void 0 || query === void 0 ? { error: "the file-suggestions body must be JSON naming a non-empty session id and a query string, which may be empty" } : { session, run: async () => await deps.fileSuggestions(session, query) };
+      }
+    },
+    {
+      name: "keep-alive",
+      path: "keep-alive",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        return session === void 0 ? { error: "the keep-alive body must be JSON naming a non-empty session id" } : { session, run: async () => await deps.keepAlive(session) };
+      }
+    },
+    {
+      name: "mcp-status",
+      path: "mcp-status",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        return session === void 0 ? { error: "the mcp-status body must be JSON naming a non-empty session id" } : { session, run: async () => await deps.mcpStatus(session) };
+      }
+    },
+    {
+      name: "mcp-reconnect",
+      path: "mcp-reconnect",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const serverName = bodyString(body, "serverName");
+        return session === void 0 || serverName === void 0 ? { error: "the mcp-reconnect body must be JSON naming a non-empty session id and server name" } : { session, run: async () => await deps.mcpReconnect(session, serverName) };
+      }
+    },
+    {
+      name: "mcp-authenticate",
+      path: "mcp-authenticate",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const serverName = bodyString(body, "serverName");
+        const redirectUri = bodyString(body, "redirectUri");
+        return session === void 0 || serverName === void 0 || redirectUri === void 0 ? { error: "the mcp-authenticate body must be JSON naming a non-empty session id, server name, and redirect URI" } : { session, run: async () => await deps.mcpAuthenticate(session, serverName, redirectUri) };
+      }
+    },
+    {
+      name: "mcp-oauth-callback-url",
+      path: "mcp-oauth-callback-url",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const serverName = bodyString(body, "serverName");
+        const callbackUrl = bodyString(body, "callbackUrl");
+        return session === void 0 || serverName === void 0 || callbackUrl === void 0 ? { error: "the mcp-oauth-callback-url body must be JSON naming a non-empty session id, server name, and callback URL" } : { session, run: async () => await deps.mcpOAuthCallbackUrl(session, serverName, callbackUrl) };
+      }
+    },
+    {
+      name: "teleport",
+      path: "teleport",
+      read: (body) => {
+        const session = bodyString(body, "session");
+        const marker = bodyString(body, "marker");
+        return session === void 0 || marker === void 0 ? { error: "the teleport body must be JSON naming a non-empty session id and marker" } : { session, run: async () => await deps.teleport(session, marker) };
+      }
+    }
+  ];
   return (request4, response) => {
     const presented = request4.headers.authorization;
     const bearerPrefix = "bearer ".length;
@@ -3954,73 +4189,33 @@ function createRcControlHandler(deps) {
         answerJson(response, HTTP_STATUS.badGateway, { error: result.message });
         return;
       }
-      if (url.pathname === interruptPath) {
-        if (request4.method !== "POST") {
-          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: "the interrupt operation is a POST" });
-          return;
-        }
-        let parsed;
-        try {
-          parsed = JSON.parse(await readBody(request4));
-        } catch {
-          answerJson(response, HTTP_STATUS.badRequest, { error: "the interrupt body is not readable JSON within the control body cap" });
-          return;
-        }
-        if (typeof parsed !== "object" || parsed === null || !("session" in parsed) || typeof parsed.session !== "string" || parsed.session === "") {
-          answerJson(response, HTTP_STATUS.badRequest, { error: "the interrupt body must be JSON naming a non-empty session id" });
-          return;
-        }
-        const result = await deps.interrupt(parsed.session);
-        if (result.ok) {
-          answerJson(response, HTTP_STATUS.ok, { session: parsed.session, sequenceNums: result.sequenceNums });
-          return;
+      for (const route of controlWrites) {
+        if (url.pathname !== `${CONTROL_PATH_PREFIX}/${route.path}`) {
+          continue;
         }
-        answerJson(response, HTTP_STATUS.badGateway, { error: result.message });
-        return;
-      }
-      if (url.pathname === setModelPath) {
         if (request4.method !== "POST") {
-          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: "the set-model operation is a POST" });
+          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: `the ${route.name} operation is a POST` });
           return;
         }
         let parsed;
         try {
           parsed = JSON.parse(await readBody(request4));
         } catch {
-          answerJson(response, HTTP_STATUS.badRequest, { error: "the set-model body is not readable JSON within the control body cap" });
-          return;
-        }
-        if (typeof parsed !== "object" || parsed === null || !("session" in parsed) || !("model" in parsed) || typeof parsed.session !== "string" || typeof parsed.model !== "string" || parsed.session === "" || parsed.model === "") {
-          answerJson(response, HTTP_STATUS.badRequest, { error: "the set-model body must be JSON naming a non-empty session id and model id" });
-          return;
-        }
-        const result = await deps.setModel(parsed.session, parsed.model);
-        if (result.ok) {
-          answerJson(response, HTTP_STATUS.ok, { session: parsed.session, model: parsed.model, sequenceNums: result.sequenceNums });
-          return;
-        }
-        answerJson(response, HTTP_STATUS.badGateway, { error: result.message });
-        return;
-      }
-      if (url.pathname === setPermissionModePath) {
-        if (request4.method !== "POST") {
-          answerJson(response, HTTP_STATUS.methodNotAllowed, { error: "the set-permission-mode operation is a POST" });
+          answerJson(response, HTTP_STATUS.badRequest, { error: `the ${route.name} body is not readable JSON within the control body cap` });
           return;
         }
-        let parsed;
-        try {
-          parsed = JSON.parse(await readBody(request4));
-        } catch {
-          answerJson(response, HTTP_STATUS.badRequest, { error: "the set-permission-mode body is not readable JSON within the control body cap" });
+        if (!isJsonObject(parsed)) {
+          answerJson(response, HTTP_STATUS.badRequest, { error: `the ${route.name} body must be a JSON object` });
           return;
         }
-        if (typeof parsed !== "object" || parsed === null || !("session" in parsed) || !("mode" in parsed) || typeof parsed.session !== "string" || parsed.session === "" || !isRcPermissionMode(parsed.mode)) {
-          answerJson(response, HTTP_STATUS.badRequest, { error: `the set-permission-mode body must be JSON naming a non-empty session id and a mode the SDK's own type permits (${RC_PERMISSION_MODE_LIST})` });
+        const read = route.read(parsed);
+        if ("error" in read) {
+          answerJson(response, HTTP_STATUS.badRequest, { error: read.error });
           return;
         }
-        const result = await deps.setPermissionMode(parsed.session, parsed.mode);
+        const result = await read.run();
         if (result.ok) {
-          answerJson(response, HTTP_STATUS.ok, { session: parsed.session, mode: parsed.mode, sequenceNums: result.sequenceNums });
+          answerJson(response, HTTP_STATUS.ok, { session: read.session, ...result.requestId === void 0 ? {} : { request: result.requestId }, sequenceNums: result.sequenceNums });
           return;
         }
         answerJson(response, HTTP_STATUS.badGateway, { error: result.message });
@@ -4138,6 +4333,19 @@ function sequenceNumsOfBody(body) {
   }
   return sequenceNums;
 }
+function requestIdOfBody(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("request" in parsed)) {
+    return void 0;
+  }
+  const value = parsed.request;
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
 function frontDoorRcControl(transport, token) {
   const headers = { authorization: `Bearer ${token}` };
   const listAnswerOf = async (path32, what) => {
@@ -4226,7 +4434,8 @@ function frontDoorRcControl(transport, token) {
       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 };
+      const requestId = requestIdOfBody(answer.body);
+      return requestId === void 0 ? { ok: true, sequenceNums } : { ok: true, sequenceNums, requestId };
     }
     return { ok: false, message: describeFailure(answer.status, controlErrorOf(answer.body) ?? answer.body) };
   };
@@ -4243,7 +4452,22 @@ function frontDoorRcControl(transport, token) {
     ),
     interruptSession: async (sessionId) => await writeOf(`${CONTROL_PATH_PREFIX}/interrupt`, JSON.stringify({ session: sessionId }), (status, message) => `interrupting ${sessionId} failed (HTTP ${String(status)}): ${message}`),
     setModel: async (sessionId, model) => await writeOf(`${CONTROL_PATH_PREFIX}/set-model`, JSON.stringify({ session: sessionId, model }), (status, message) => `setting the model on ${sessionId} failed (HTTP ${String(status)}): ${message}`),
-    setPermissionMode: async (sessionId, mode) => await writeOf(`${CONTROL_PATH_PREFIX}/set-permission-mode`, JSON.stringify({ session: sessionId, mode }), (status, message) => `setting the permission mode on ${sessionId} failed (HTTP ${String(status)}): ${message}`)
+    setPermissionMode: async (sessionId, mode) => await writeOf(`${CONTROL_PATH_PREFIX}/set-permission-mode`, JSON.stringify({ session: sessionId, mode }), (status, message) => `setting the permission mode on ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    endSession: async (sessionId, reason) => await writeOf(`${CONTROL_PATH_PREFIX}/end-session`, JSON.stringify({ session: sessionId, ...reason === void 0 ? {} : { reason } }), (status, message) => `ending ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    getUsage: async (sessionId, skipBehaviors) => await writeOf(`${CONTROL_PATH_PREFIX}/get-usage`, JSON.stringify({ session: sessionId, ...skipBehaviors === void 0 ? {} : { skipBehaviors } }), (status, message) => `requesting the usage of ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    getContextUsage: async (sessionId, detail) => await writeOf(`${CONTROL_PATH_PREFIX}/get-context-usage`, JSON.stringify({ session: sessionId, ...detail === void 0 ? {} : { detail } }), (status, message) => `requesting the context usage of ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    readFile: async (sessionId, path32, options) => await writeOf(
+      `${CONTROL_PATH_PREFIX}/read-file`,
+      JSON.stringify({ session: sessionId, path: path32, ...options?.maxBytes === void 0 ? {} : { maxBytes: options.maxBytes }, ...options?.encoding === void 0 ? {} : { encoding: options.encoding } }),
+      (status, message) => `reading ${path32} from ${sessionId} failed (HTTP ${String(status)}): ${message}`
+    ),
+    fileSuggestions: async (sessionId, query) => await writeOf(`${CONTROL_PATH_PREFIX}/file-suggestions`, JSON.stringify({ session: sessionId, query }), (status, message) => `requesting file suggestions from ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    keepAlive: async (sessionId) => await writeOf(`${CONTROL_PATH_PREFIX}/keep-alive`, JSON.stringify({ session: sessionId }), (status, message) => `keeping ${sessionId} alive failed (HTTP ${String(status)}): ${message}`),
+    mcpStatus: async (sessionId) => await writeOf(`${CONTROL_PATH_PREFIX}/mcp-status`, JSON.stringify({ session: sessionId }), (status, message) => `requesting the MCP status of ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    mcpReconnect: async (sessionId, serverName) => await writeOf(`${CONTROL_PATH_PREFIX}/mcp-reconnect`, JSON.stringify({ session: sessionId, serverName }), (status, message) => `reconnecting MCP server ${serverName} on ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    mcpAuthenticate: async (sessionId, serverName, redirectUri) => await writeOf(`${CONTROL_PATH_PREFIX}/mcp-authenticate`, JSON.stringify({ session: sessionId, serverName, redirectUri }), (status, message) => `authenticating MCP server ${serverName} on ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    mcpOAuthCallbackUrl: async (sessionId, serverName, callbackUrl) => await writeOf(`${CONTROL_PATH_PREFIX}/mcp-oauth-callback-url`, JSON.stringify({ session: sessionId, serverName, callbackUrl }), (status, message) => `handing MCP server ${serverName}'s OAuth callback to ${sessionId} failed (HTTP ${String(status)}): ${message}`),
+    teleport: async (sessionId, marker) => await writeOf(`${CONTROL_PATH_PREFIX}/teleport`, JSON.stringify({ session: sessionId, marker }), (status, message) => `teleporting a marker into ${sessionId} failed (HTTP ${String(status)}): ${message}`)
   };
 }
 
@@ -4390,36 +4614,38 @@ function tlsFacts(options) {
 }
 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 = https2.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") });
-        });
+  const post = async (path32, headers, body) => await new Promise((resolve, reject) => {
+    const options = {
+      host: target.host,
+      port: target.port,
+      method: "POST",
+      path: path32,
+      // 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 = https2.request(options, (response) => {
+      const chunks = [];
+      response.on("data", (chunk) => {
+        chunks.push(chunk);
       });
-      request4.once("error", reject);
-      request4.end(body);
-    })
+      response.on("end", () => {
+        resolve({ status: response.statusCode ?? HTTP_BAD_GATEWAY, body: Buffer.concat(chunks).toString("utf8") });
+      });
+    });
+    request4.once("error", reject);
+    request4.end(body);
+  });
+  return {
+    writeEvents: async (sessionId, headers, body) => await post(`/v1/code/sessions/${encodeURIComponent(sessionId)}/events`, headers, body),
+    writeTeleportEvents: async (sessionId, headers, body) => await post(`/v1/code/sessions/${encodeURIComponent(sessionId)}/teleport-events`, headers, body)
   };
 }
 var NO_CHUNKS = {
@@ -4437,7 +4663,8 @@ function lateRcEventDial(resolve) {
     return built.dial;
   };
   return {
-    writeEvents: async (sessionId, headers, body) => await dialFor().writeEvents(sessionId, headers, body)
+    writeEvents: async (sessionId, headers, body) => await dialFor().writeEvents(sessionId, headers, body),
+    writeTeleportEvents: async (sessionId, headers, body) => await dialFor().writeTeleportEvents(sessionId, headers, body)
   };
 }
 function lateRcStreamDial(resolve) {
@@ -4450,7 +4677,8 @@ function lateRcStreamDial(resolve) {
     return built.dial;
   };
   return {
-    announcePresence: async (sessionId, headers, clientId) => await dialFor().announcePresence(sessionId, headers, clientId),
+    announcePresence: async (sessionId, headers, clientId, clear) => await dialFor().announcePresence(sessionId, headers, clientId, clear),
+    markRead: async (sessionId, headers, eventId) => await dialFor().markRead(sessionId, headers, eventId),
     openStream: async (sessionId, headers, resume, signal) => await dialFor().openStream(sessionId, headers, resume, signal)
   };
 }
@@ -4492,11 +4720,16 @@ function realRcStreamDial(target = { host: CONNECT_INTERCEPT_HOST, port: HTTPS_P
     return Buffer.concat(chunks).toString("utf8");
   };
   return {
-    announcePresence: async (sessionId, headers, clientId) => {
-      const body = JSON.stringify({ client_id: clientId, clear: false });
+    announcePresence: async (sessionId, headers, clientId, clear) => {
+      const body = JSON.stringify({ client_id: clientId, clear });
       const { status, response } = await request4("POST", `/v1/code/sessions/${encodeURIComponent(sessionId)}/client/presence`, { ...headers, "content-type": "application/json" }, body, new AbortController().signal);
       return { status, body: await readAll(response) };
     },
+    markRead: async (sessionId, headers, eventId) => {
+      const body = JSON.stringify(buildRcMarkReadBody(eventId));
+      const { status, response } = await request4("POST", `/v1/code/sessions/${encodeURIComponent(sessionId)}/mark_read`, { ...headers, "content-type": "application/json" }, body, new AbortController().signal);
+      return { status, body: await readAll(response) };
+    },
     openStream: async (sessionId, headers, resume, signal) => {
       const path32 = resume === void 0 ? `/v1/code/sessions/${encodeURIComponent(sessionId)}/events/stream` : `/v1/code/sessions/${encodeURIComponent(sessionId)}/events/stream?from_sequence_num=${String(resume.fromSequenceNum)}`;
       const streamHeaders = resume === void 0 ? headers : { ...headers, "last-event-id": String(resume.fromSequenceNum) };
@@ -4865,6 +5098,52 @@ var RcSetPermissionModeInputSchema = z4.strictObject({
   session: z4.string().min(1),
   mode: RcPermissionModeSchema
 });
+var RcEndSessionInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  reason: z4.string().min(1).optional()
+});
+var RcGetUsageInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  skipBehaviors: z4.boolean().optional()
+});
+var RcGetContextUsageInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  detail: z4.enum(RC_CONTEXT_USAGE_DETAILS).optional()
+});
+var RcReadFileInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  path: z4.string().min(1),
+  maxBytes: z4.number().int().positive().optional(),
+  encoding: z4.enum(RC_READ_FILE_ENCODINGS).optional()
+});
+var RcFileSuggestionsInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  query: z4.string()
+});
+var RcKeepAliveInputSchema = z4.strictObject({
+  session: z4.string().min(1)
+});
+var RcMcpStatusInputSchema = z4.strictObject({
+  session: z4.string().min(1)
+});
+var RcMcpReconnectInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  serverName: z4.string().min(1)
+});
+var RcMcpAuthenticateInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  serverName: z4.string().min(1),
+  redirectUri: z4.string().min(1)
+});
+var RcMcpOAuthCallbackUrlInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  serverName: z4.string().min(1),
+  callbackUrl: z4.string().min(1)
+});
+var RcTeleportInputSchema = z4.strictObject({
+  session: z4.string().min(1),
+  marker: z4.string().min(1)
+});
 var RcListOutputSchema = z4.strictObject({ sessions: z4.readonly(z4.array(RcSessionSummarySchema)) });
 var RcStatusOutputSchema = z4.strictObject({ statuses: z4.readonly(z4.array(RcSessionStatusSchema)) });
 var RcPendingOutputSchema = z4.strictObject({ pending: z4.readonly(z4.array(RcPendingRequestSummarySchema)) });
@@ -4872,6 +5151,11 @@ var RcWriteOutputSchema = z4.strictObject({
   session: z4.string(),
   sequenceNums: z4.readonly(z4.array(z4.number()))
 });
+var RcControlWriteOutputSchema = z4.strictObject({
+  session: z4.string(),
+  request: z4.string(),
+  sequenceNums: z4.readonly(z4.array(z4.number()))
+});
 var RcAnswerOutputSchema = z4.strictObject({
   session: z4.string(),
   request: z4.string(),
@@ -4900,6 +5184,15 @@ function createRcApiRouter(deps) {
     }
     return result.sequenceNums;
   };
+  const deliveredControl = (sessionId, result) => {
+    if (!result.ok) {
+      throw new ORPCError("BAD_GATEWAY", { message: result.message });
+    }
+    if (result.requestId === void 0) {
+      throw new ORPCError("INTERNAL_SERVER_ERROR", { message: "the control request was delivered but the door cannot name the request id it minted, so the worker's answer cannot be matched" });
+    }
+    return { request: result.requestId, sequenceNums: result.sequenceNums };
+  };
   return {
     rc: {
       list: authed.output(RcListOutputSchema).handler(() => ({ sessions: deps.list() })),
@@ -4922,9 +5215,20 @@ function createRcApiRouter(deps) {
         const decision = { approve: input.approve, message: input.approve || input.text === void 0 ? void 0 : input.text };
         return { session: input.session, request: input.request, sequenceNums: delivered(input.session, await deps.answer(input.session, input.request, decision)) };
       }),
-      interrupt: authed.input(RcInterruptInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.interrupt(input.session)) })),
-      setModel: authed.input(RcSetModelInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.setModel(input.session, input.model)) })),
-      setPermissionMode: authed.input(RcSetPermissionModeInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.setPermissionMode(input.session, input.mode)) })),
+      interrupt: authed.input(RcInterruptInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.interrupt(input.session)) })),
+      setModel: authed.input(RcSetModelInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.setModel(input.session, input.model)) })),
+      setPermissionMode: authed.input(RcSetPermissionModeInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.setPermissionMode(input.session, input.mode)) })),
+      endSession: authed.input(RcEndSessionInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.endSession(input.session, input.reason)) })),
+      getUsage: authed.input(RcGetUsageInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.getUsage(input.session, input.skipBehaviors)) })),
+      getContextUsage: authed.input(RcGetContextUsageInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.getContextUsage(input.session, input.detail)) })),
+      readFile: authed.input(RcReadFileInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.readFile(input.session, input.path, { ...input.maxBytes === void 0 ? {} : { maxBytes: input.maxBytes }, ...input.encoding === void 0 ? {} : { encoding: input.encoding } })) })),
+      fileSuggestions: authed.input(RcFileSuggestionsInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.fileSuggestions(input.session, input.query)) })),
+      keepAlive: authed.input(RcKeepAliveInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.keepAlive(input.session)) })),
+      mcpStatus: authed.input(RcMcpStatusInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpStatus(input.session)) })),
+      mcpReconnect: authed.input(RcMcpReconnectInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpReconnect(input.session, input.serverName)) })),
+      mcpAuthenticate: authed.input(RcMcpAuthenticateInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpAuthenticate(input.session, input.serverName, input.redirectUri)) })),
+      mcpOAuthCallbackUrl: authed.input(RcMcpOAuthCallbackUrlInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpOAuthCallbackUrl(input.session, input.serverName, input.callbackUrl)) })),
+      teleport: authed.input(RcTeleportInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.teleport(input.session, input.marker)) })),
       subscribe: authed.input(RcSessionQuerySchema).output(eventIterator(RcStreamEventSchema)).handler(async function* ({ input, signal }) {
         const queue = [];
         let wake;
@@ -9881,9 +10185,26 @@ function createRcStreamHub(deps) {
     }
     return headers;
   };
+  let receiptFailureLogged = false;
+  const sendReceipt = (attachment, headers, eventId) => {
+    if (eventId === void 0) {
+      return;
+    }
+    deps.dial.markRead(attachment.sessionId, headers, eventId).then(
+      () => {
+        receiptFailureLogged = false;
+      },
+      (error) => {
+        if (!receiptFailureLogged) {
+          receiptFailureLogged = true;
+          deps.log?.(`rc stream ${attachment.sessionId}: the read receipt for event ${eventId} could not be sent (${error instanceof Error ? error.message : String(error)}); further receipt failures stay quiet until one lands`);
+        }
+      }
+    );
+  };
   const attempt = async (attachment, credential) => {
     const headers = streamHeaders(credential);
-    const presence = await deps.dial.announcePresence(attachment.sessionId, headers, attachment.clientId);
+    const presence = await deps.dial.announcePresence(attachment.sessionId, headers, attachment.clientId, false);
     if (presence.status === HTTP_STATUS.unauthorized) {
       return "unauthorized";
     }
@@ -9903,6 +10224,7 @@ function createRcStreamHub(deps) {
     const parser = createSseParser();
     for await (const chunk of answer.chunks) {
       attachment.controller.signal.throwIfAborted();
+      let lastEventId;
       for (const parsed of parser.write(Buffer.from(chunk).toString("utf8"))) {
         const envelope = parseRcStreamEnvelope(parsed);
         if (envelope === void 0) {
@@ -9910,10 +10232,21 @@ function createRcStreamHub(deps) {
         }
         deps.fileStreamEvent(attachment.sessionId, envelope);
         deps.fanout.publish({ session: attachment.sessionId, envelope });
+        if (typeof envelope.event_id === "string" && envelope.event_type !== "mark_read") {
+          lastEventId = envelope.event_id;
+        }
       }
+      sendReceipt(attachment, headers, lastEventId);
     }
     return "dropped";
   };
+  const clearPresence = (attachment, headers) => {
+    if (headers === void 0) {
+      return;
+    }
+    void deps.dial.announcePresence(attachment.sessionId, headers, attachment.clientId, true).catch(() => {
+    });
+  };
   const runLoop = async (attachment) => {
     let retriedUnauthorized = false;
     for (; ; ) {
@@ -9925,6 +10258,7 @@ function createRcStreamHub(deps) {
       if (!live || credential?.authorization === void 0) {
         deps.log?.(`rc stream ${attachment.sessionId}: the attachment ended (${live ? "the session's client credential is no longer known" : "the tracker gave up on the session"})`);
         persistCursor(attachment.sessionId);
+        clearPresence(attachment, credential === void 0 ? void 0 : streamHeaders(credential));
         if (attachments.get(attachment.sessionId) === attachment) {
           attachments.delete(attachment.sessionId);
         }
@@ -9987,6 +10321,8 @@ function createRcStreamHub(deps) {
     close: () => {
       for (const attachment of attachments.values()) {
         persistCursor(attachment.sessionId);
+        const credential = deps.credentialOf(attachment.sessionId);
+        clearPresence(attachment, credential?.authorization === void 0 ? void 0 : streamHeaders(credential));
         attachment.stop();
       }
       attachments.clear();
@@ -9994,6 +10330,193 @@ function createRcStreamHub(deps) {
   };
 }
 
+// src/frontdoor/rcSelfHostEndpoints.ts
+var RC_SOURCE_WORKER = "worker";
+var RC_SOURCE_CLIENT = "client";
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJsonObject2(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+  return isRecord6(parsed) ? parsed : void 0;
+}
+function nonEmptyString2(record, field) {
+  const value = record === void 0 ? void 0 : record[field];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function numberOf(record, field) {
+  const value = record === void 0 ? void 0 : record[field];
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) {
+    return Number(value);
+  }
+  return void 0;
+}
+function pageOfRcChannel(url, rows, idOf, rowOf) {
+  const query = new URL(url, "http://127.0.0.1").searchParams;
+  const anchor = query.get("after_event_id") ?? query.get("cursor");
+  const rawLimit = query.get("limit");
+  const limit = rawLimit === null ? void 0 : numberOf({ value: rawLimit }, "value");
+  if (limit !== void 0 && limit < 1) {
+    return { error: "the limit names a whole number of rows of at least one" };
+  }
+  const from = anchor === null ? 0 : rows.findIndex((row) => idOf(row) === anchor) + 1;
+  if (anchor !== null && from === 0) {
+    return { error: `the anchor names an event id this surface holds no row for: ${anchor}` };
+  }
+  const page = limit === void 0 ? rows.slice(from) : rows.slice(from, from + limit);
+  const last = page[page.length - 1];
+  return { data: page.map(rowOf), ...last === void 0 ? {} : { next_cursor: idOf(last) } };
+}
+async function serveRcClientChannels(ctx, tail, method, maxBatchEvents) {
+  const { request: request4, response, session } = ctx;
+  if (tail === "client/presence" && method === "POST") {
+    const body = parseJsonObject2(await ctx.readBody(request4.body, CONTROL_BODY_CAP_BYTES));
+    const clientId = nonEmptyString2(body, "client_id");
+    const clear = body?.clear;
+    if (clientId === void 0 || clear !== void 0 && typeof clear !== "boolean") {
+      await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a presence announcement is JSON naming a non-empty client_id, with clear only as a boolean or absent" } });
+      return true;
+    }
+    if (clear === true) {
+      session.clients.delete(clientId);
+      ctx.log?.(`rc selfhost ${session.id}: client ${clientId} cleared its presence`);
+    } else {
+      session.clients.set(clientId, ctx.now());
+      ctx.log?.(`rc selfhost ${session.id}: client ${clientId} announced its presence${session.clients.size === 1 ? "" : ` (${String(session.clients.size)} clients now announced)`}`);
+    }
+    await ctx.answerJson(response, HTTP_STATUS.ok, { refresh_after_seconds: ctx.presenceRefreshSeconds });
+    return true;
+  }
+  if (tail === "mark_read" && method === "POST") {
+    const body = parseJsonObject2(await ctx.readBody(request4.body, CONTROL_BODY_CAP_BYTES));
+    const eventId = nonEmptyString2(body, "event_id");
+    const clientId = nonEmptyString2(body, "client_id");
+    if (body !== void 0 && "event_id" in body && eventId === void 0 || "client_id" in (body ?? {}) && clientId === void 0) {
+      await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a read receipt is JSON naming the event_id it read or none for the whole session, and client_id only as a non-empty string or absent" } });
+      return true;
+    }
+    const receipt = ctx.publish(session, clientId ?? RC_SOURCE_CLIENT, { type: "mark_read", ...eventId === void 0 ? {} : { event_id: eventId }, ...clientId === void 0 ? {} : { client_id: clientId } }, true);
+    ctx.log?.(`rc selfhost ${session.id}: ${clientId === void 0 ? "an unnamed client" : `client ${clientId}`} marked ${eventId === void 0 ? "the session read" : `event ${eventId} read`} as sequence ${String(receipt.sequenceNum)}`);
+    await ctx.answerJson(response, HTTP_STATUS.ok, {});
+    return true;
+  }
+  if (tail === "teleport-events" && method === "POST") {
+    const body = parseJsonObject2(await ctx.readBody(request4.body, CONTROL_BODY_CAP_BYTES));
+    const events = body?.events;
+    if (!Array.isArray(events) || events.length === 0 || events.length > maxBatchEvents) {
+      await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: `a teleport write is a non-empty array of at most ${String(maxBatchEvents)} events` } });
+      return true;
+    }
+    const results = [];
+    for (const event of events) {
+      if (!isRecord6(event) || !isRecord6(event.payload)) {
+        await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "every event in a teleport write is an object carrying one payload object" } });
+        return true;
+      }
+      const published = ctx.publish(session, RC_SOURCE_CLIENT, event.payload);
+      results.push({ sequence_num: String(published.sequenceNum), duplicate: published.duplicate });
+    }
+    ctx.sweep();
+    ctx.log?.(`rc selfhost ${session.id}: teleport write published ${String(results.length)} marker event(s)`);
+    await ctx.answerJson(response, HTTP_STATUS.ok, { results });
+    return true;
+  }
+  if (tail === "teleport-events" && method === "GET") {
+    const page = pageOfRcChannel(request4.url, session.events, (event) => event.eventId, (event) => ({ event_id: event.eventId, payload: event.payload }));
+    if ("error" in page) {
+      await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: page.error } });
+      return true;
+    }
+    await ctx.answerJson(response, HTTP_STATUS.ok, page);
+    return true;
+  }
+  return false;
+}
+var compatSessionRow = (session, now) => ({ id: session.id, title: session.title, created_at: new Date(session.createdAt).toISOString(), updated_at: new Date(now()).toISOString(), session_status: "active" });
+async function serveRcCompatSessions(ctx, pathname, compatPath) {
+  const { request: request4, response } = ctx;
+  const method = request4.method.toUpperCase();
+  if (pathname === compatPath) {
+    if (method !== "GET") {
+      await ctx.answerJson(response, HTTP_STATUS.methodNotAllowed, { type: "error", error: { type: "api_error", message: "the compatibility session list is a GET" } });
+      return;
+    }
+    const listRefusal = ctx.credentialRefusal(request4.headers);
+    if (listRefusal !== void 0) {
+      await ctx.unauthorized(response, listRefusal);
+      return;
+    }
+    await ctx.answerJson(response, HTTP_STATUS.ok, { data: [...ctx.sessions.values()].map((session2) => compatSessionRow(session2, ctx.now)) });
+    return;
+  }
+  const rest = pathname.slice(`${compatPath}/`.length);
+  const slash = rest.indexOf("/");
+  const address = slash === -1 ? rest : rest.slice(0, slash);
+  const compatTail = slash === -1 ? "" : rest.slice(slash + 1);
+  const refusal = ctx.credentialRefusal(request4.headers);
+  if (refusal !== void 0) {
+    await ctx.unauthorized(response, refusal);
+    return;
+  }
+  const session = ctx.sessions.get(address) ?? ctx.sessions.get(`cse_${address}`);
+  if (compatTail === "") {
+    if (method === "GET") {
+      if (session === void 0) {
+        await ctx.answerJson(response, HTTP_STATUS.notFound, { type: "error", error: { type: "api_error", message: `Session not found: ${address}` } });
+        return;
+      }
+      await ctx.answerJson(response, HTTP_STATUS.ok, compatSessionRow(session, ctx.now));
+      return;
+    }
+    if (method === "PATCH" || method === "PUT") {
+      if (session === void 0) {
+        await ctx.answerJson(response, HTTP_STATUS.notFound, { type: "error", error: { type: "api_error", message: `Session not found: ${address}` } });
+        return;
+      }
+      const body = parseJsonObject2(await ctx.readBody(request4.body, CONTROL_BODY_CAP_BYTES));
+      const title = nonEmptyString2(body, "title");
+      if (title === void 0) {
+        await ctx.answerJson(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a compatibility session update is JSON naming a non-empty title" } });
+        return;
+      }
+      session.title = title;
+      session.lastTrafficAt = ctx.now();
+      ctx.log?.(`rc selfhost ${session.id}: retitled through the compatibility family`);
+      await ctx.answerJson(response, HTTP_STATUS.ok, compatSessionRow(session, ctx.now));
+      return;
+    }
+    await ctx.answerJson(response, HTTP_STATUS.methodNotAllowed, { type: "error", error: { type: "api_error", message: "the compatibility session read is a GET and its update a PATCH or PUT" } });
+    return;
+  }
+  if ((compatTail === "archive" || compatTail === "unarchive") && method === "POST") {
+    await ctx.readBody(request4.body, CONTROL_BODY_CAP_BYTES);
+    if (session === void 0) {
+      await ctx.answerJson(response, HTTP_STATUS.notFound, { type: "error", error: { type: "api_error", message: `Session not found: ${address}` } });
+      return;
+    }
+    if (compatTail === "unarchive") {
+      await ctx.answerJson(response, HTTP_STATUS.ok, compatSessionRow(session, ctx.now));
+      return;
+    }
+    for (const sink of [...session.workerStreams, ...session.clientStreams]) {
+      sink.retire();
+    }
+    ctx.sessions.delete(session.id);
+    ctx.log?.(`rc selfhost ${session.id}: archived through the compatibility family`);
+    await ctx.answerJson(response, HTTP_STATUS.ok, {});
+    return;
+  }
+  await ctx.answerJson(response, HTTP_STATUS.notFound, { type: "error", error: { type: "api_error", message: `the compatibility session family serves no path "${compatTail}"` } });
+}
+
 // src/frontdoor/rcWebFetch.ts
 import * as dns2 from "node:dns";
 import * as http2 from "node:http";
@@ -10262,21 +10785,19 @@ var RC_PRESENCE_REFRESH_SECONDS = 60;
 var RC_SELF_HOST_MAX_BATCH_EVENTS = 100;
 var RC_SELF_HOST_WORKER_EPOCH = 1;
 var RC_STREAM_EVENT_NAME2 = "client_event";
-var RC_SOURCE_WORKER = "worker";
-var RC_SOURCE_CLIENT = "client";
 var CONFLICT_REASON_HEADER2 = "x-ccr-conflict-reason";
 var CONFLICT_REASON_EPOCH_STALE = "epoch_stale";
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isWebSearchRefusal(value) {
   return !Array.isArray(value);
 }
-function nonEmptyString2(record, field) {
+function nonEmptyString3(record, field) {
   const value = record === void 0 ? void 0 : record[field];
   return typeof value === "string" && value !== "" ? value : void 0;
 }
-function numberOf(record, field) {
+function numberOf2(record, field) {
   const value = record === void 0 ? void 0 : record[field];
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -10343,14 +10864,14 @@ async function readBody2(request4, capBytes) {
     });
   });
 }
-function parseJsonObject2(body) {
+function parseJsonObject3(body) {
   let parsed;
   try {
     parsed = JSON.parse(body);
   } catch {
     return void 0;
   }
-  return isRecord6(parsed) ? parsed : void 0;
+  return isRecord7(parsed) ? parsed : void 0;
 }
 function mintWorkerJwt(randomToken, issuedAt) {
   const encode = (value) => Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
@@ -10373,11 +10894,16 @@ function createRcSelfHostSurface(deps) {
     for (const session of sessions.values()) {
       while (session.events[0] !== void 0 && now - session.events[0].storedAt > RC_SELF_HOST_RETENTION_MS) {
         const dropped = session.events.shift();
-        const uuid = dropped === void 0 ? void 0 : nonEmptyString2(dropped.payload, "uuid");
+        const uuid = dropped === void 0 ? void 0 : nonEmptyString3(dropped.payload, "uuid");
         if (uuid !== void 0) {
           session.seenPayloadUuids.delete(uuid);
         }
       }
+      for (const [clientId, lastSeenAt] of session.clients) {
+        if (now - lastSeenAt > RC_SELF_HOST_RETENTION_MS) {
+          session.clients.delete(clientId);
+        }
+      }
       if (session.workerStreams.size === 0 && session.clientStreams.size === 0 && now - session.lastTrafficAt > RC_SELF_HOST_RETENTION_MS) {
         sessions.delete(session.id);
       }
@@ -10416,7 +10942,7 @@ function createRcSelfHostSurface(deps) {
   const frameOf = (event) => {
     const envelope = {
       event_id: event.eventId,
-      event_type: nonEmptyString2(event.payload, "type") ?? "event",
+      event_type: nonEmptyString3(event.payload, "type") ?? "event",
       sequence_num: event.sequenceNum,
       source: event.source,
       payload: event.payload,
@@ -10430,7 +10956,7 @@ data: ${JSON.stringify(envelope)}
   };
   const holdStream = async (session, which, wantsReplay, request4, response) => {
     const url = new URL(request4.url, "http://127.0.0.1");
-    const cursor = numberOf({ value: url.searchParams.get("from_sequence_num") }, "value") ?? numberOf({ value: singleHeader2(request4.headers, "last-event-id") }, "value");
+    const cursor = numberOf2({ value: url.searchParams.get("from_sequence_num") }, "value") ?? numberOf2({ value: singleHeader2(request4.headers, "last-event-id") }, "value");
     const replay = cursor === void 0 ? [] : session.events.filter((event) => wantsReplay(event) && event.sequenceNum > cursor);
     response.start(HTTP_STATUS.ok, { "content-type": "text/event-stream", "cache-control": "no-cache" });
     response.flush();
@@ -10459,8 +10985,8 @@ data: ${JSON.stringify(envelope)}
     sink.retire();
     response.end();
   };
-  const publish = (session, source, payload) => {
-    const uuid = nonEmptyString2(payload, "uuid");
+  const publish = (session, source, payload, toWorker = source === RC_SOURCE_CLIENT) => {
+    const uuid = nonEmptyString3(payload, "uuid");
     const duplicate = uuid !== void 0 && session.seenPayloadUuids.has(uuid);
     session.sequenceNum += 1;
     const event = {
@@ -10468,9 +10994,9 @@ data: ${JSON.stringify(envelope)}
       eventId: uuid ?? deps.newUuid(),
       source,
       // The one enrichment the real service was observed making on the live rig's stream: the wall-clock instant it took the write. The worker's handler ignores it; the door's own parser forwards it verbatim.
-      payload: source === RC_SOURCE_CLIENT ? { ...payload, server_received_wall_ms: deps.now() } : payload,
+      payload: source === RC_SOURCE_WORKER ? payload : { ...payload, server_received_wall_ms: deps.now() },
       createdAt: new Date(deps.now()).toISOString(),
-      toWorker: source === RC_SOURCE_CLIENT,
+      toWorker,
       storedAt: deps.now()
     };
     session.events.push(event);
@@ -10518,8 +11044,26 @@ data: ${JSON.stringify(envelope)}
     }
     session.lastTrafficAt = deps.now();
     if (tail === "") {
+      if (method === "PATCH" || method === "PUT") {
+        const refusal = credentialRefusal(request4.headers);
+        if (refusal !== void 0) {
+          await unauthorized(response, refusal);
+          return;
+        }
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const title = nonEmptyString3(body, "title");
+        if (title === void 0) {
+          await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a session update is JSON naming a non-empty title" } });
+          return;
+        }
+        session.title = title;
+        session.lastTrafficAt = deps.now();
+        deps.log?.(`rc selfhost ${session.id}: retitled at its client's request`);
+        await answerJson2(response, HTTP_STATUS.ok, {});
+        return;
+      }
       if (method !== "GET") {
-        await answerJson2(response, HTTP_STATUS.methodNotAllowed, { type: "error", error: { type: "api_error", message: "the session read is a GET" } });
+        await answerJson2(response, HTTP_STATUS.methodNotAllowed, { type: "error", error: { type: "api_error", message: "the session read is a GET, and its update a PATCH or PUT" } });
         return;
       }
       await answerJson2(response, HTTP_STATUS.ok, { session: { id: session.id, title: session.title, created_at: new Date(session.createdAt).toISOString(), status: "active" } });
@@ -10564,17 +11108,17 @@ data: ${JSON.stringify(envelope)}
         return;
       }
       if (workerTail === "" && method === "PUT") {
-        const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
-        const claimedEpoch = numberOf(body, "worker_epoch");
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const claimedEpoch = numberOf2(body, "worker_epoch");
         if (claimedEpoch !== void 0 && claimedEpoch !== RC_SELF_HOST_WORKER_EPOCH) {
           await epochStale(response);
           return;
         }
-        const status = nonEmptyString2(body, "worker_status");
+        const status = nonEmptyString3(body, "worker_status");
         if (status !== void 0) {
           session.workerStatus = status;
         }
-        if (isRecord6(body?.external_metadata)) {
+        if (isRecord7(body?.external_metadata)) {
           session.externalMetadata = body.external_metadata;
         }
         await answerJson2(response, HTTP_STATUS.ok, {});
@@ -10591,8 +11135,8 @@ data: ${JSON.stringify(envelope)}
         return;
       }
       if (workerTail === "events" && method === "POST") {
-        const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
-        const claimedEpoch = numberOf(body, "worker_epoch");
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const claimedEpoch = numberOf2(body, "worker_epoch");
         if (claimedEpoch !== void 0 && claimedEpoch !== RC_SELF_HOST_WORKER_EPOCH) {
           await epochStale(response);
           return;
@@ -10604,7 +11148,7 @@ data: ${JSON.stringify(envelope)}
         }
         const results = [];
         for (const event of events) {
-          if (!isRecord6(event) || !isRecord6(event.payload)) {
+          if (!isRecord7(event) || !isRecord7(event.payload)) {
             await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "every event in a batch is an object carrying one payload object" } });
             return;
           }
@@ -10625,8 +11169,8 @@ data: ${JSON.stringify(envelope)}
         return;
       }
       if (workerTail === "internal-events" && method === "POST") {
-        const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
-        const claimedEpoch = numberOf(body, "worker_epoch");
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const claimedEpoch = numberOf2(body, "worker_epoch");
         if (claimedEpoch !== void 0 && claimedEpoch !== RC_SELF_HOST_WORKER_EPOCH) {
           await epochStale(response);
           return;
@@ -10637,19 +11181,26 @@ data: ${JSON.stringify(envelope)}
           return;
         }
         for (const event of events) {
-          if (isRecord6(event)) {
-            session.internalEvents.push({ cursor: deps.newUuid(), body: event });
+          if (isRecord7(event)) {
+            session.internalEvents.push({ eventId: deps.newUuid(), body: event });
           }
         }
         await answerJson2(response, HTTP_STATUS.ok, {});
         return;
       }
       if (workerTail === "internal-events" && method === "GET") {
-        const url = new URL(request4.url, "http://127.0.0.1");
-        const cursor = url.searchParams.get("cursor");
-        const from = cursor === null ? 0 : session.internalEvents.findIndex((event) => event.cursor === cursor) + 1;
-        const page = session.internalEvents.slice(from);
-        await answerJson2(response, HTTP_STATUS.ok, { data: page.map((event) => event.body), next_cursor: page.length === 0 ? void 0 : page[page.length - 1]?.cursor });
+        const query = new URL(request4.url, "http://127.0.0.1").searchParams;
+        if (query.get("session_agent_id") !== null || query.get("subagents") !== null) {
+          await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "this surface keeps one internal-events channel per session, so an agent-scoped read has no subset to serve" } });
+          return;
+        }
+        const page = pageOfRcChannel(request4.url, session.internalEvents, (event) => event.eventId, (event) => ({ event_id: event.eventId, payload: event.body }));
+        if ("error" in page) {
+          const anchorUnknown = query.get("after_event_id") !== null && page.error.startsWith("the anchor names an event id");
+          await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: anchorUnknown ? "after_event_id_not_found" : "invalid_request_error", message: page.error } });
+          return;
+        }
+        await answerJson2(response, HTTP_STATUS.ok, page);
         return;
       }
       if (workerTail === "diagnostics" && method === "POST") {
@@ -10658,8 +11209,8 @@ data: ${JSON.stringify(envelope)}
         return;
       }
       if (workerTail === "web-fetch" && method === "POST") {
-        const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
-        const target = nonEmptyString2(body, "url");
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const target = nonEmptyString3(body, "url");
         if (target === void 0) {
           await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a worker web-fetch carries one url" } });
           return;
@@ -10681,8 +11232,8 @@ data: ${JSON.stringify(envelope)}
         return;
       }
       if (workerTail === "web-search" && method === "POST") {
-        const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
-        const query = nonEmptyString2(body, "query");
+        const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+        const query = nonEmptyString3(body, "query");
         if (query === void 0) {
           await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "a worker web-search carries one query" } });
           return;
@@ -10693,7 +11244,7 @@ data: ${JSON.stringify(envelope)}
           await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "the domain filters of a worker web-search are string arrays" } });
           return;
         }
-        const searchProfile = nonEmptyString2(body, "search_profile");
+        const searchProfile = nonEmptyString3(body, "search_profile");
         const backend = deps.webSearch;
         if (backend === void 0) {
           deps.log?.(`rc selfhost ${session.id}: worker web-search of "${query}" refused: no search backend serves this door`);
@@ -10718,7 +11269,7 @@ data: ${JSON.stringify(envelope)}
       return;
     }
     if (tail === "events" && method === "POST") {
-      const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+      const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
       const events = body?.events;
       if (!Array.isArray(events) || events.length === 0 || events.length > RC_SELF_HOST_MAX_BATCH_EVENTS) {
         await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: `a client event write is a non-empty array of at most ${String(RC_SELF_HOST_MAX_BATCH_EVENTS)} events` } });
@@ -10726,7 +11277,7 @@ data: ${JSON.stringify(envelope)}
       }
       const results = [];
       for (const event of events) {
-        if (!isRecord6(event) || !isRecord6(event.payload)) {
+        if (!isRecord7(event) || !isRecord7(event.payload)) {
           await answerJson2(response, HTTP_STATUS.badRequest, { type: "error", error: { type: "invalid_request_error", message: "every event in a write is an object carrying one payload object" } });
           return;
         }
@@ -10738,26 +11289,14 @@ data: ${JSON.stringify(envelope)}
       return;
     }
     if (tail === "events" && method === "GET") {
-      await answerJson2(response, HTTP_STATUS.ok, { data: session.events.map((event) => ({ event_id: event.eventId, event_type: nonEmptyString2(event.payload, "type") ?? "event", sequence_num: event.sequenceNum, source: event.source, payload: event.payload, created_at: event.createdAt })) });
+      await answerJson2(response, HTTP_STATUS.ok, { data: session.events.map((event) => ({ event_id: event.eventId, event_type: nonEmptyString3(event.payload, "type") ?? "event", sequence_num: event.sequenceNum, source: event.source, payload: event.payload, created_at: event.createdAt })) });
       return;
     }
     if (tail === "events/stream" && method === "GET") {
       await holdStream(session, "clientStreams", () => true, request4, response);
       return;
     }
-    if (tail === "client/presence" && method === "POST") {
-      await readBody2(request4.body, CONTROL_BODY_CAP_BYTES);
-      await answerJson2(response, HTTP_STATUS.ok, { refresh_after_seconds: RC_PRESENCE_REFRESH_SECONDS });
-      return;
-    }
-    if (tail === "mark_read" && method === "POST") {
-      await readBody2(request4.body, CONTROL_BODY_CAP_BYTES);
-      await answerJson2(response, HTTP_STATUS.ok, {});
-      return;
-    }
-    if (tail === "teleport-events" && method === "POST") {
-      await readBody2(request4.body, CONTROL_BODY_CAP_BYTES);
-      await answerJson2(response, HTTP_STATUS.ok, {});
+    if (await serveRcClientChannels({ request: request4, response, session, answerJson: answerJson2, readBody: readBody2, publish, sweep, now: deps.now, presenceRefreshSeconds: RC_PRESENCE_REFRESH_SECONDS, ...deps.log === void 0 ? {} : { log: deps.log } }, tail, method, RC_SELF_HOST_MAX_BATCH_EVENTS)) {
       return;
     }
     await answerJson2(response, HTTP_STATUS.notFound, { type: "error", error: { type: "api_error", message: `the self-hosted Remote Control surface serves no path "${tail}"` } });
@@ -10774,17 +11313,8 @@ data: ${JSON.stringify(envelope)}
         await noCredential(response);
         return;
       }
-      if (pathname === RC_COMPAT_SESSIONS_PATH) {
-        if (method !== "GET") {
-          await answerJson2(response, HTTP_STATUS.methodNotAllowed, { type: "error", error: { type: "api_error", message: "the compatibility session list is a GET" } });
-          return;
-        }
-        const listRefusal = credentialRefusal(request4.headers);
-        if (listRefusal !== void 0) {
-          await unauthorized(response, listRefusal);
-          return;
-        }
-        await answerJson2(response, HTTP_STATUS.ok, { data: [] });
+      if (pathname === RC_COMPAT_SESSIONS_PATH || pathname.startsWith(`${RC_COMPAT_SESSIONS_PATH}/`)) {
+        await serveRcCompatSessions({ request: request4, response, sessions, answerJson: answerJson2, readBody: readBody2, credentialRefusal, unauthorized, now: deps.now, ...deps.log === void 0 ? {} : { log: deps.log } }, pathname, RC_COMPAT_SESSIONS_PATH);
         return;
       }
       if (pathname !== RC_SESSIONS_PATH_PREFIX2 && !pathname.startsWith(`${RC_SESSIONS_PATH_PREFIX2}/`)) {
@@ -10798,11 +11328,11 @@ data: ${JSON.stringify(envelope)}
             await unauthorized(response, createRefusal);
             return;
           }
-          const body = parseJsonObject2(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
+          const body = parseJsonObject3(await readBody2(request4.body, CONTROL_BODY_CAP_BYTES));
           const session = {
             id: `${RC_SESSION_ID_PREFIX2}${deps.newUuid()}`,
             createdAt: deps.now(),
-            title: nonEmptyString2(body, "title"),
+            title: nonEmptyString3(body, "title"),
             workerJwts: /* @__PURE__ */ new Set(),
             sequenceNum: 0,
             events: [],
@@ -10810,6 +11340,7 @@ data: ${JSON.stringify(envelope)}
             workerStreams: /* @__PURE__ */ new Set(),
             clientStreams: /* @__PURE__ */ new Set(),
             internalEvents: [],
+            clients: /* @__PURE__ */ new Map(),
             workerStatus: void 0,
             externalMetadata: void 0,
             lastTrafficAt: deps.now()
@@ -10854,7 +11385,7 @@ data: ${JSON.stringify(envelope)}
       const pathname = new URL(request4.url ?? "/", "http://127.0.0.1").pathname;
       if (host === RC_SELF_HOST_OAUTH_HOST) {
         if (method === "POST" && pathname === "/v1/oauth/token") {
-          const body = parseJsonObject2(await readBody2(request4, CONTROL_BODY_CAP_BYTES));
+          const body = parseJsonObject3(await readBody2(request4, CONTROL_BODY_CAP_BYTES));
           const record = deps.credentialRecord();
           if (record === void 0) {
             answerServerJson(response, HTTP_SERVICE_UNAVAILABLE, { error: "the front door's self-hosted Remote Control surface is on but no credential has been minted for it" });
@@ -10940,7 +11471,7 @@ var RC_SELF_HOST_RECORD_DIR = "rc-selfhost";
 var RC_SELF_HOST_RECORD_FILE = "credential.json";
 var SELF_HOST_EMAIL = "selfhost@agent-shim.invalid";
 var SELF_HOST_SUBSCRIPTION_TYPE = "max";
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function readJsonObject(fs12, file) {
@@ -10954,7 +11485,7 @@ function readJsonObject(fs12, file) {
   } catch {
     return void 0;
   }
-  return isRecord7(parsed) ? parsed : void 0;
+  return isRecord8(parsed) ? parsed : void 0;
 }
 function readRcSelfHostRecord(fs12, frontdoorDir) {
   const parsed = readJsonObject(fs12, path28.join(frontdoorDir, RC_SELF_HOST_RECORD_DIR, RC_SELF_HOST_RECORD_FILE));
@@ -10978,7 +11509,7 @@ function mintRcSelfHostCredential(deps) {
   const recordFile = path28.join(recordDir, RC_SELF_HOST_RECORD_FILE);
   const previousRecord = readRcSelfHostRecord(deps.fs, deps.frontdoorDir);
   const existingCredentials = readJsonObject(deps.fs, credentialsFile);
-  const existingOauth = isRecord7(existingCredentials?.claudeAiOauth) ? existingCredentials.claudeAiOauth : void 0;
+  const existingOauth = isRecord8(existingCredentials?.claudeAiOauth) ? existingCredentials.claudeAiOauth : void 0;
   const existingToken = typeof existingOauth?.accessToken === "string" && existingOauth.accessToken !== "" ? existingOauth.accessToken : void 0;
   const existingIsOwn = existingToken !== void 0 && previousRecord?.accessToken === existingToken;
   if (existingToken !== void 0 && !existingIsOwn && !deps.force) {
@@ -10995,7 +11526,7 @@ function mintRcSelfHostCredential(deps) {
   deps.fs.writeFilePrivate(credentialsFile, `${JSON.stringify({ ...existingCredentials, claudeAiOauth: { accessToken, refreshToken, expiresAt: null, scopes: [...RC_SELF_HOST_SCOPE_LIST], subscriptionType: SELF_HOST_SUBSCRIPTION_TYPE, rateLimitTier: null } }, null, 2)}
 `);
   const claudeJson = readJsonObject(deps.fs, claudeJsonFile) ?? {};
-  const existingBlock = (value) => isRecord7(value) ? value : {};
+  const existingBlock = (value) => isRecord8(value) ? value : {};
   deps.fs.writeFilePrivate(claudeJsonFile, `${JSON.stringify({
     ...claudeJson,
     oauthAccount: {
@@ -11194,7 +11725,7 @@ import path30 from "node:path";
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.23.0",
+  version: "8.25.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "MIT",
   author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -12436,10 +12967,12 @@ export {
   ProviderKindMismatchError,
   ProviderNotFoundError,
   ProviderSchema,
+  RC_CONTEXT_USAGE_DETAILS,
   RC_IDLE_EXPIRY_MS,
   RC_ORPC_PATH_PREFIX,
   RC_PENDING_DEADLINE_MS,
   RC_PERMISSION_MODES,
+  RC_READ_FILE_ENCODINGS,
   RC_REQUEST_PARSE_CAP_BYTES,
   RC_SELF_HOST_ENV,
   RC_SELF_HOST_KEEPALIVE_MS,
@@ -12470,11 +13003,24 @@ export {
   addPool,
   addProvider,
   answerRcControlRequest,
+  authenticateRcSessionMcpServer,
   buildEntryFacts,
   buildLayoutPaths,
+  buildRcControlRequestPayload,
   buildRcControlResponsePayload,
+  buildRcEndSessionPayload,
   buildRcEventWriteBody,
+  buildRcFileSuggestionsPayload,
+  buildRcGetContextUsagePayload,
+  buildRcGetUsagePayload,
   buildRcInterruptPayload,
+  buildRcKeepAlivePayload,
+  buildRcMarkReadBody,
+  buildRcMcpAuthenticatePayload,
+  buildRcMcpOAuthCallbackUrlPayload,
+  buildRcMcpReconnectPayload,
+  buildRcMcpStatusPayload,
+  buildRcReadFilePayload,
   buildRcSetModelPayload,
   buildRcSetPermissionModePayload,
   buildRcUserMessagePayload,
@@ -12507,6 +13053,7 @@ export {
   doorApiAuth,
   doorApiNodeHandlerOf,
   effectiveWindow,
+  endRcSession,
   ensureCa,
   ensureFrontDoor,
   ensureHeadroom,
@@ -12523,6 +13070,9 @@ export {
   frontDoorRcApiClient,
   frontDoorRcControl,
   generateCa,
+  getRcSessionContextUsage,
+  getRcSessionMcpStatus,
+  getRcSessionUsage,
   headroomSocketTarget,
   identityExists,
   injectRcUserMessage,
@@ -12530,7 +13080,9 @@ export {
   isIdentityDirectoryName,
   isInterceptedHost,
   isPrivateAddress,
+  isRcContextUsageDetail,
   isRcPermissionMode,
+  isRcReadFileEncoding,
   lateRcEventDial,
   lateRcStreamDial,
   listDirectoryRules,
@@ -12564,6 +13116,7 @@ export {
   readProfile,
   readProvider,
   readRcSelfHostRecord,
+  readRcSessionFile,
   readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
@@ -12571,6 +13124,7 @@ export {
   realRcEventDial,
   realRcStreamDial,
   realRcWebFetch,
+  reconnectRcSessionMcpServer,
   recoverFarm,
   recoveryDiagnostics,
   removeDirectoryRule,
@@ -12590,6 +13144,7 @@ export {
   runFrontDoorSupervisor,
   runLauncher,
   runSupervisor,
+  sendRcKeepAlive,
   servedByPipeline,
   setAllowAmbientCredential,
   setDefaultConfigProfile,
@@ -12605,6 +13160,9 @@ export {
   snapshotPath,
   spawnClaude,
   startConnectServer,
+  submitRcSessionMcpOAuthCallbackUrl,
+  suggestRcSessionFiles,
+  teleportRcSession,
   topLevelNames,
   updateDirectoryRule,
   updateProvider,