agent-shim 8.23.0 → 8.24.0

package/dist/index.mjs

@@ -3630,6 +3630,8 @@ function rcObserverAsPassthrough(observer) {
     }
   };
 }
+
+// src/frontdoor/rcWrites.ts
 function buildRcUserMessagePayload(uuid, sessionId, text) {
   return {
     type: "user",
@@ -3730,14 +3732,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 +3807,7 @@ async function answerRcControlRequest(deps, sessionId, requestId, decision) {
   }
   return result;
 }
-async function interruptRcSession(deps, sessionId) {
+async function deliverRcClientPayload(deps, sessionId, payload, action) {
   const credential = deps.credentialOf(sessionId);
   if (credential === void 0) {
     return { ok: false, message: rcSessionNotObservedMessage(sessionId) };
@@ -3772,12 +3815,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);
   } 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,50 +3828,89 @@ 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) };
-  }
-  if (credential.authorization === void 0) {
-    return noOAuthCredentialResult(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" };
   }
-  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, 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 result = rcEventWriteResultFromAnswer(answer);
-  if (result.ok) {
-    deps.noteSequenceNums(sessionId, result.sequenceNums);
+  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" };
   }
-  return result;
+  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`);
 }
 
 // src/frontdoor/rcControl.ts
@@ -3840,6 +3922,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 +3968,127 @@ 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) };
+      }
+    }
+  ];
   return (request4, response) => {
     const presented = request4.headers.authorization;
     const bearerPrefix = "bearer ".length;
@@ -3954,73 +4173,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" });
+          answerJson(response, HTTP_STATUS.badRequest, { error: `the ${route.name} 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" });
+        if (!isJsonObject(parsed)) {
+          answerJson(response, HTTP_STATUS.badRequest, { error: `the ${route.name} body must be a JSON object` });
           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 });
+        const read = route.read(parsed);
+        if ("error" in read) {
+          answerJson(response, HTTP_STATUS.badRequest, { error: read.error });
           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" });
-          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" });
-          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})` });
-          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 +4317,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 +4418,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 +4436,21 @@ 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}`)
   };
 }
 
@@ -4865,6 +5072,48 @@ 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 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 +5121,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 +5154,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 +5185,19 @@ 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)) })),
       subscribe: authed.input(RcSessionQuerySchema).output(eventIterator(RcStreamEventSchema)).handler(async function* ({ input, signal }) {
         const queue = [];
         let wake;
@@ -11194,7 +11467,7 @@ import path30 from "node:path";
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.23.0",
+  version: "8.24.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 +12709,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 +12745,23 @@ export {
   addPool,
   addProvider,
   answerRcControlRequest,
+  authenticateRcSessionMcpServer,
   buildEntryFacts,
   buildLayoutPaths,
+  buildRcControlRequestPayload,
   buildRcControlResponsePayload,
+  buildRcEndSessionPayload,
   buildRcEventWriteBody,
+  buildRcFileSuggestionsPayload,
+  buildRcGetContextUsagePayload,
+  buildRcGetUsagePayload,
   buildRcInterruptPayload,
+  buildRcKeepAlivePayload,
+  buildRcMcpAuthenticatePayload,
+  buildRcMcpOAuthCallbackUrlPayload,
+  buildRcMcpReconnectPayload,
+  buildRcMcpStatusPayload,
+  buildRcReadFilePayload,
   buildRcSetModelPayload,
   buildRcSetPermissionModePayload,
   buildRcUserMessagePayload,
@@ -12507,6 +12794,7 @@ export {
   doorApiAuth,
   doorApiNodeHandlerOf,
   effectiveWindow,
+  endRcSession,
   ensureCa,
   ensureFrontDoor,
   ensureHeadroom,
@@ -12523,6 +12811,9 @@ export {
   frontDoorRcApiClient,
   frontDoorRcControl,
   generateCa,
+  getRcSessionContextUsage,
+  getRcSessionMcpStatus,
+  getRcSessionUsage,
   headroomSocketTarget,
   identityExists,
   injectRcUserMessage,
@@ -12530,7 +12821,9 @@ export {
   isIdentityDirectoryName,
   isInterceptedHost,
   isPrivateAddress,
+  isRcContextUsageDetail,
   isRcPermissionMode,
+  isRcReadFileEncoding,
   lateRcEventDial,
   lateRcStreamDial,
   listDirectoryRules,
@@ -12564,6 +12857,7 @@ export {
   readProfile,
   readProvider,
   readRcSelfHostRecord,
+  readRcSessionFile,
   readUsageSnapshot,
   realConnectCertStore,
   realConnectEffects,
@@ -12571,6 +12865,7 @@ export {
   realRcEventDial,
   realRcStreamDial,
   realRcWebFetch,
+  reconnectRcSessionMcpServer,
   recoverFarm,
   recoveryDiagnostics,
   removeDirectoryRule,
@@ -12590,6 +12885,7 @@ export {
   runFrontDoorSupervisor,
   runLauncher,
   runSupervisor,
+  sendRcKeepAlive,
   servedByPipeline,
   setAllowAmbientCredential,
   setDefaultConfigProfile,
@@ -12605,6 +12901,8 @@ export {
   snapshotPath,
   spawnClaude,
   startConnectServer,
+  submitRcSessionMcpOAuthCallbackUrl,
+  suggestRcSessionFiles,
   topLevelNames,
   updateDirectoryRule,
   updateProvider,