agent-shim 8.28.0 → 8.30.0

package/dist/index.mjs

@@ -5028,10 +5028,113 @@ function createRcCredentialStore(fs12, dir) {
 // src/frontdoor/rcApi.ts
 import { createORPCClient, ORPCError } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { OpenAPIHandler } from "@orpc/openapi/node";
 import { eventIterator, os as os2, withEventMeta } from "@orpc/server";
 import { BodyLimitPlugin, RPCHandler } from "@orpc/server/node";
 import { Agent as Agent3, fetch as undiciFetch } from "undici";
 
+// package.json
+var package_default = {
+  name: "agent-shim",
+  version: "8.30.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>",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ExaDev/agent-shim.git"
+  },
+  homepage: "https://github.com/ExaDev/agent-shim#readme",
+  bugs: "https://github.com/ExaDev/agent-shim/issues",
+  keywords: [
+    "claude-code",
+    "claude",
+    "cli"
+  ],
+  packageManager: "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
+  type: "module",
+  engines: {
+    node: "^22.18 || >=24"
+  },
+  bin: {
+    "agent-shim": "dist/cli.cjs",
+    "claude-use": "dist/cli.cjs"
+  },
+  files: [
+    "dist/cli.cjs",
+    "dist/index.mjs",
+    "dist/index.cjs",
+    "dist/types"
+  ],
+  scripts: {
+    prepare: "husky && node scripts/build.mts --bundle-only",
+    typecheck: "turbo run _typecheck",
+    _typecheck: "tsc --noEmit",
+    lint: "turbo run _lint",
+    _lint: "eslint . --cache --cache-location .eslintcache --max-warnings 0",
+    test: "turbo run _test",
+    _test: "vitest run",
+    "test:coverage": "turbo run _test:coverage",
+    "_test:coverage": "vitest run --coverage",
+    knip: "turbo run _knip",
+    _knip: "knip --cache",
+    build: "turbo run _build",
+    _build: "node scripts/build.mts",
+    "build:bundle": "node scripts/build.mts --bundle-only",
+    prepublishOnly: "pnpm build:bundle",
+    schema: "node scripts/gen-schema.mts"
+  },
+  dependencies: {
+    "@clack/prompts": "^1.8.0",
+    "@orpc/client": "1.15.4",
+    "@orpc/openapi": "1.15.4",
+    "@orpc/server": "1.15.4",
+    commander: "^15.0.0",
+    cosmiconfig: "^10.0.1",
+    picomatch: "^4.0.7",
+    undici: "7.29.1",
+    zod: "^4.6.1"
+  },
+  devDependencies: {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@exadev/eslint-config": "2.12.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^26.5.1",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.11",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
+    esbuild: "^0.28.2",
+    eslint: "^10.10.0",
+    globals: "^17.12.0",
+    husky: "^9.1.7",
+    jiti: "^2.7.0",
+    knip: "^6.35.1",
+    "lint-staged": "^17.5.0",
+    rollup: "4.64.0",
+    "rollup-plugin-dts": "6.5.1",
+    "semantic-release": "^25.0.9",
+    turbo: "^2.11.5",
+    typescript: "^6.0.3",
+    "typescript-eslint": "^8.70.0",
+    vitest: "^4.1.11"
+  },
+  main: "dist/index.cjs",
+  module: "dist/index.mjs",
+  types: "dist/types/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/types/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+};
+
 // src/frontdoor/rcSchemas.ts
 import { z as z4 } from "zod";
 var RcPermissionModeSchema = z4.enum(RC_PERMISSION_MODES);
@@ -5193,18 +5296,23 @@ var RcAnswerOutputSchema = z4.strictObject({
 
 // src/frontdoor/rcApi.ts
 var RC_ORPC_PATH_PREFIX = "/__agent-shim/orpc";
+var RC_OPENAPI_DOC_PATH = "/openapi.json";
 var RC_SUBSCRIBER_BUFFER_EVENTS = 100;
+function doorApiBearer(headers) {
+  const presented = headers.authorization;
+  const bearerPrefix = "bearer ".length;
+  return typeof presented === "string" && presented.slice(0, bearerPrefix).toLowerCase() === "bearer " ? presented.slice(bearerPrefix) : void 0;
+}
 function doorApiAuth(expectedToken) {
   return os2.$context().use(({ context, next }) => {
-    const presented = context.headers.authorization;
-    const bearerPrefix = "bearer ".length;
-    const token = typeof presented === "string" && presented.slice(0, bearerPrefix).toLowerCase() === "bearer " ? presented.slice(bearerPrefix) : void 0;
+    const token = doorApiBearer(context.headers);
     if (token === void 0 || !isLiveCapability(token, [expectedToken])) {
       throw new ORPCError("UNAUTHORIZED", { message: "the front door's typed API demands this generation's control token as a Bearer credential" });
     }
     return next();
   });
 }
+var RC_API_TAG = "remote-control";
 function createRcApiRouter(deps) {
   const authed = doorApiAuth(deps.expectedToken);
   const delivered = (sessionId, result) => {
@@ -5224,41 +5332,41 @@ function createRcApiRouter(deps) {
   };
   return {
     rc: {
-      list: authed.output(RcListOutputSchema).handler(() => ({ sessions: deps.list() })),
-      status: authed.input(RcSessionQuerySchema).output(RcStatusOutputSchema).handler(({ input }) => {
+      list: authed.route({ method: "GET", path: "/rest/rc/sessions", summary: "List the observed Remote Control sessions", tags: [RC_API_TAG] }).output(RcListOutputSchema).handler(() => ({ sessions: deps.list() })),
+      status: authed.route({ method: "GET", path: "/rest/rc/status", summary: "Read session status, one session's when named", tags: [RC_API_TAG] }).input(RcSessionQuerySchema).output(RcStatusOutputSchema).handler(({ input }) => {
         const statuses = deps.statusOf(input.session);
         if (input.session !== void 0 && !statuses.some((entry) => entry.id === input.session)) {
           throw new ORPCError("NOT_FOUND", { message: rcSessionNotObservedMessage(input.session) });
         }
         return { statuses };
       }),
-      pending: authed.input(RcSessionQuerySchema).output(RcPendingOutputSchema).handler(({ input }) => {
+      pending: authed.route({ method: "GET", path: "/rest/rc/pending", summary: "Read the control requests awaiting an answer", tags: [RC_API_TAG] }).input(RcSessionQuerySchema).output(RcPendingOutputSchema).handler(({ input }) => {
         const pending = deps.pendingOf(input.session);
         if (input.session !== void 0 && deps.statusOf(input.session).length === 0) {
           throw new ORPCError("NOT_FOUND", { message: rcSessionNotObservedMessage(input.session) });
         }
         return { pending };
       }),
-      send: authed.input(RcSendInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.inject(input.session, input.text)) })),
-      answer: authed.input(RcAnswerInputSchema).output(RcAnswerOutputSchema).handler(async ({ input }) => {
+      send: authed.route({ method: "POST", path: "/rest/rc/send", summary: "Send one message into a session", tags: [RC_API_TAG] }).input(RcSendInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.inject(input.session, input.text)) })),
+      answer: authed.route({ method: "POST", path: "/rest/rc/answer", summary: "Answer one pending control request", tags: [RC_API_TAG] }).input(RcAnswerInputSchema).output(RcAnswerOutputSchema).handler(async ({ input }) => {
         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(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 }) {
+      interrupt: authed.route({ method: "POST", path: "/rest/rc/interrupt", summary: "Interrupt a session's running turn", tags: [RC_API_TAG] }).input(RcInterruptInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.interrupt(input.session)) })),
+      setModel: authed.route({ method: "POST", path: "/rest/rc/set-model", summary: "Switch a session's model", tags: [RC_API_TAG] }).input(RcSetModelInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.setModel(input.session, input.model)) })),
+      setPermissionMode: authed.route({ method: "POST", path: "/rest/rc/set-permission-mode", summary: "Switch a session's permission mode", tags: [RC_API_TAG] }).input(RcSetPermissionModeInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.setPermissionMode(input.session, input.mode)) })),
+      endSession: authed.route({ method: "POST", path: "/rest/rc/end-session", summary: "End a session", tags: [RC_API_TAG] }).input(RcEndSessionInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.endSession(input.session, input.reason)) })),
+      getUsage: authed.route({ method: "POST", path: "/rest/rc/get-usage", summary: "Ask a session for its usage snapshot", tags: [RC_API_TAG] }).input(RcGetUsageInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.getUsage(input.session, input.skipBehaviors)) })),
+      getContextUsage: authed.route({ method: "POST", path: "/rest/rc/get-context-usage", summary: "Ask a session for its context usage", tags: [RC_API_TAG] }).input(RcGetContextUsageInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.getContextUsage(input.session, input.detail)) })),
+      readFile: authed.route({ method: "POST", path: "/rest/rc/read-file", summary: "Ask a session to read one file", tags: [RC_API_TAG] }).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.route({ method: "POST", path: "/rest/rc/file-suggestions", summary: "Ask a session for file-path suggestions", tags: [RC_API_TAG] }).input(RcFileSuggestionsInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.fileSuggestions(input.session, input.query)) })),
+      keepAlive: authed.route({ method: "POST", path: "/rest/rc/keep-alive", summary: "Keep a session's bridge alive", tags: [RC_API_TAG] }).input(RcKeepAliveInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.keepAlive(input.session)) })),
+      mcpStatus: authed.route({ method: "POST", path: "/rest/rc/mcp-status", summary: "Ask a session for its MCP servers' status", tags: [RC_API_TAG] }).input(RcMcpStatusInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpStatus(input.session)) })),
+      mcpReconnect: authed.route({ method: "POST", path: "/rest/rc/mcp-reconnect", summary: "Ask a session to reconnect one MCP server", tags: [RC_API_TAG] }).input(RcMcpReconnectInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpReconnect(input.session, input.serverName)) })),
+      mcpAuthenticate: authed.route({ method: "POST", path: "/rest/rc/mcp-authenticate", summary: "Start OAuth for one MCP server on a session", tags: [RC_API_TAG] }).input(RcMcpAuthenticateInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpAuthenticate(input.session, input.serverName, input.redirectUri)) })),
+      mcpOAuthCallbackUrl: authed.route({ method: "POST", path: "/rest/rc/mcp-oauth-callback-url", summary: "Hand a completed MCP OAuth callback to a session", tags: [RC_API_TAG] }).input(RcMcpOAuthCallbackUrlInputSchema).output(RcControlWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, ...deliveredControl(input.session, await deps.mcpOAuthCallbackUrl(input.session, input.serverName, input.callbackUrl)) })),
+      teleport: authed.route({ method: "POST", path: "/rest/rc/teleport", summary: "Teleport a session to a conversation marker", tags: [RC_API_TAG] }).input(RcTeleportInputSchema).output(RcWriteOutputSchema).handler(async ({ input }) => ({ session: input.session, sequenceNums: delivered(input.session, await deps.teleport(input.session, input.marker)) })),
+      subscribe: authed.route({ method: "GET", path: "/rest/rc/events", summary: "Stream a session's Remote Control events (SSE)", tags: [RC_API_TAG] }).input(RcSessionQuerySchema).output(eventIterator(RcStreamEventSchema)).handler(async function* ({ input, signal }) {
         const queue = [];
         let wake;
         const detach = deps.fanout.subscribe(input.session, (event) => {
@@ -5295,15 +5403,44 @@ function createRcApiRouter(deps) {
     }
   };
 }
-function doorApiNodeHandlerOf(router) {
-  const handler = new RPCHandler(router, { plugins: [new BodyLimitPlugin({ maxBodySize: CONTROL_BODY_CAP_BYTES })] });
+function doorApiNodeHandlerOf(router, expectedToken) {
+  const plugins = [new BodyLimitPlugin({ maxBodySize: CONTROL_BODY_CAP_BYTES })];
+  const rpcHandler = new RPCHandler(router, { plugins });
+  const restHandler = new OpenAPIHandler(router, { plugins });
+  let document;
+  const documentOf = async () => document ??= new OpenAPIGenerator().generate(router, { info: { title: "agent-shim front door API", version: package_default.version } });
   return {
     pathPrefix: RC_ORPC_PATH_PREFIX,
-    handle: async (request4, response) => await handler.handle(request4, response, { context: { headers: request4.headers }, prefix: RC_ORPC_PATH_PREFIX })
+    handle: async (request4, response) => {
+      if (request4.method === "GET" && request4.url === `${RC_ORPC_PATH_PREFIX}${RC_OPENAPI_DOC_PATH}`) {
+        const token = doorApiBearer(request4.headers);
+        if (token === void 0 || !isLiveCapability(token, [expectedToken])) {
+          const refusal = new ORPCError("UNAUTHORIZED", { message: "the front door's OpenAPI document demands this generation's control token as a Bearer credential" });
+          response.writeHead(HTTP_STATUS.unauthorized, { "content-type": "application/json" });
+          response.end(JSON.stringify(refusal.toJSON()));
+          return { matched: true };
+        }
+        try {
+          const doc = await documentOf();
+          response.writeHead(HTTP_STATUS.ok, { "content-type": "application/json" });
+          response.end(JSON.stringify(doc));
+        } catch (error) {
+          const refusal = new ORPCError("INTERNAL_SERVER_ERROR", { message: `the OpenAPI document could not be generated from the door's own router: ${error instanceof Error ? error.message : String(error)}` });
+          response.writeHead(HTTP_STATUS.internalServerError, { "content-type": "application/json" });
+          response.end(JSON.stringify(refusal.toJSON()));
+        }
+        return { matched: true };
+      }
+      const rest = await restHandler.handle(request4, response, { context: { headers: request4.headers }, prefix: RC_ORPC_PATH_PREFIX });
+      if (rest.matched) {
+        return rest;
+      }
+      return await rpcHandler.handle(request4, response, { context: { headers: request4.headers }, prefix: RC_ORPC_PATH_PREFIX });
+    }
   };
 }
 function createRcApiNodeHandler(deps) {
-  return doorApiNodeHandlerOf(createRcApiRouter(deps));
+  return doorApiNodeHandlerOf(createRcApiRouter(deps), deps.expectedToken);
 }
 function frontDoorApiLink(port, ca, token) {
   const dispatcher = new Agent3({ connect: { ca } });
@@ -9738,6 +9875,10 @@ var CheckRunInputSchema = z19.strictObject({
   path: z19.string().min(1),
   identity: z19.string().min(1).optional()
 }).refine((input) => path27.isAbsolute(input.path), { message: "path must be absolute: the door cannot resolve a relative path against the caller's working directory" });
+var PoolPickInputSchema = z19.strictObject({
+  pool: z19.string().min(1),
+  path: z19.string().min(1)
+}).refine((input) => path27.isAbsolute(input.path), { message: "path must be absolute: the door cannot resolve a relative path against the caller's working directory" });
 var DoctorFindingSchema = z19.strictObject({
   section: z19.enum(DOCTOR_SECTIONS),
   subject: z19.string().optional(),
@@ -9775,11 +9916,12 @@ var LaunchLifecycleEventSchema = z20.strictObject({
 });
 
 // src/frontdoor/eventsApi.ts
+var EVENTS_API_TAG = "events";
 function createEventsApiRouter(deps) {
   const authed = doorApiAuth(deps.expectedToken);
   return {
     events: {
-      subscribe: authed.input(DoorEventSourceQuerySchema).output(eventIterator2(DoorEventSchema)).handler(async function* ({ input, signal }) {
+      subscribe: authed.route({ method: "GET", path: "/rest/events", summary: "Stream the door's every event source (SSE)", tags: [EVENTS_API_TAG] }).input(DoorEventSourceQuerySchema).output(eventIterator2(DoorEventSchema)).handler(async function* ({ input, signal }) {
         if (input.sources !== void 0) {
           const live = deps.events.sources();
           const unknown = input.sources.filter((source) => !live.includes(source));
@@ -9812,12 +9954,17 @@ function createEventsApiRouter(deps) {
 }
 
 // src/frontdoor/controlApi.ts
+var USAGE_API_TAG = "usage";
+var FRONTDOOR_API_TAG = "frontdoor";
+var CHECK_API_TAG = "check";
+var DOCTOR_API_TAG = "doctor";
+var POOL_API_TAG = "pool";
 function createControlApiRouter(deps) {
   const authed = doorApiAuth(deps.expectedToken);
   return {
     usage: {
-      list: authed.output(UsageListOutputSchema).handler(() => ({ snapshots: deps.usageSnapshots() })),
-      effectiveWindow: authed.input(UsageWindowsInputSchema).output(UsageWindowsOutputSchema).handler(({ input }) => {
+      list: authed.route({ method: "GET", path: "/rest/usage/snapshots", summary: "List every identity's usage snapshot", tags: [USAGE_API_TAG] }).output(UsageListOutputSchema).handler(() => ({ snapshots: deps.usageSnapshots() })),
+      effectiveWindow: authed.route({ method: "GET", path: "/rest/usage/windows", summary: "Read one identity's effective quota windows", tags: [USAGE_API_TAG] }).input(UsageWindowsInputSchema).output(UsageWindowsOutputSchema).handler(({ input }) => {
         const snapshot = deps.usageSnapshotOf(input.identity);
         if (snapshot === void 0) {
           throw new ORPCError3("NOT_FOUND", { message: `identity ${input.identity} has no usage snapshot yet, so no quota window has been observed for it` });
@@ -9834,7 +9981,7 @@ function createControlApiRouter(deps) {
           ...unified?.sevenDay === void 0 ? {} : { sevenDay: effectiveWindow(unified.sevenDay, now) }
         };
       }),
-      live: authed.input(RcSessionQuerySchema).output(UsageLiveOutputSchema).handler(({ input }) => {
+      live: authed.route({ method: "GET", path: "/rest/usage/live", summary: "Read the live rate-limit observations the event backbone files", tags: [USAGE_API_TAG] }).input(RcSessionQuerySchema).output(UsageLiveOutputSchema).handler(({ input }) => {
         const sessions = deps.liveRateLimits(input.session);
         if (input.session !== void 0 && sessions.length === 0) {
           if (deps.list().some((session) => session.id === input.session)) {
@@ -9846,15 +9993,27 @@ function createControlApiRouter(deps) {
       })
     },
     frontdoor: {
-      status: authed.output(FrontDoorStatusOutputSchema).handler(() => deps.frontDoorStatus()),
-      sessions: authed.output(FrontDoorSessionsOutputSchema).handler(() => ({ sessions: deps.frontDoorStatus().sessions }))
+      status: authed.route({ method: "GET", path: "/rest/frontdoor/status", summary: "Read the front door's status", tags: [FRONTDOOR_API_TAG] }).output(FrontDoorStatusOutputSchema).handler(() => deps.frontDoorStatus()),
+      sessions: authed.route({ method: "GET", path: "/rest/frontdoor/sessions", summary: "Read the front door's session registry", tags: [FRONTDOOR_API_TAG] }).output(FrontDoorSessionsOutputSchema).handler(() => ({ sessions: deps.frontDoorStatus().sessions }))
     },
     check: {
       // The report's own JSON shape is the contract (the same one `check --json` prints and `checkReportSchema.ts` defines), so the procedure returns exactly that conversion.
-      run: authed.input(CheckRunInputSchema).output(CheckReportJsonSchema).handler(({ input }) => checkReportToJson(deps.checkReport(input.path, input.identity)))
+      run: authed.route({ method: "GET", path: "/rest/check", summary: "Run the check report for one directory", tags: [CHECK_API_TAG] }).input(CheckRunInputSchema).output(CheckReportJsonSchema).handler(({ input }) => checkReportToJson(deps.checkReport(input.path, input.identity)))
     },
     doctor: {
-      run: authed.output(DoctorRunOutputSchema).handler(() => deps.doctorReport())
+      run: authed.route({ method: "GET", path: "/rest/doctor", summary: "Run the doctor report", tags: [DOCTOR_API_TAG] }).output(DoctorRunOutputSchema).handler(() => deps.doctorReport())
+    },
+    pool: {
+      pick: authed.route({ method: "GET", path: "/rest/pool/pick", summary: "Rank one pool exactly as a launch from a directory would right now", tags: [POOL_API_TAG] }).input(PoolPickInputSchema).output(PoolPickReportSchema).handler(({ input }) => {
+        const report = deps.poolPick(input.pool, input.path);
+        if (report === void 0) {
+          const live = deps.poolNames();
+          throw new ORPCError3("NOT_FOUND", {
+            message: live.length === 0 ? `no pools are configured, so none is named ${input.pool}` : `no pool is named ${input.pool}; the live pools are ${live.map((name) => `"${name}"`).join(", ")}`
+          });
+        }
+        return report;
+      })
     }
   };
 }
@@ -9862,7 +10021,7 @@ function createDoorApiRouter(deps) {
   return { ...createRcApiRouter(deps), ...createControlApiRouter(deps), ...createEventsApiRouter(deps) };
 }
 function createDoorApiNodeHandler(deps) {
-  return doorApiNodeHandlerOf(createDoorApiRouter(deps));
+  return doorApiNodeHandlerOf(createDoorApiRouter(deps), deps.expectedToken);
 }
 function frontDoorApiClient(port, ca, token) {
   return createORPCClient2(frontDoorApiLink(port, ca, token));
@@ -11948,106 +12107,6 @@ function removeDirectoryRule(paths, rulePath) {
 import { randomUUID as randomUUID4 } from "node:crypto";
 import path30 from "node:path";
 
-// package.json
-var package_default = {
-  name: "agent-shim",
-  version: "8.28.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>",
-  repository: {
-    type: "git",
-    url: "git+https://github.com/ExaDev/agent-shim.git"
-  },
-  homepage: "https://github.com/ExaDev/agent-shim#readme",
-  bugs: "https://github.com/ExaDev/agent-shim/issues",
-  keywords: [
-    "claude-code",
-    "claude",
-    "cli"
-  ],
-  packageManager: "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
-  type: "module",
-  engines: {
-    node: "^22.18 || >=24"
-  },
-  bin: {
-    "agent-shim": "dist/cli.cjs",
-    "claude-use": "dist/cli.cjs"
-  },
-  files: [
-    "dist/cli.cjs",
-    "dist/index.mjs",
-    "dist/index.cjs",
-    "dist/types"
-  ],
-  scripts: {
-    prepare: "husky && node scripts/build.mts --bundle-only",
-    typecheck: "turbo run _typecheck",
-    _typecheck: "tsc --noEmit",
-    lint: "turbo run _lint",
-    _lint: "eslint . --cache --cache-location .eslintcache --max-warnings 0",
-    test: "turbo run _test",
-    _test: "vitest run",
-    "test:coverage": "turbo run _test:coverage",
-    "_test:coverage": "vitest run --coverage",
-    knip: "turbo run _knip",
-    _knip: "knip --cache",
-    build: "turbo run _build",
-    _build: "node scripts/build.mts",
-    "build:bundle": "node scripts/build.mts --bundle-only",
-    prepublishOnly: "pnpm build:bundle",
-    schema: "node scripts/gen-schema.mts"
-  },
-  dependencies: {
-    "@clack/prompts": "^1.8.0",
-    "@orpc/client": "1.15.4",
-    "@orpc/server": "1.15.4",
-    commander: "^15.0.0",
-    cosmiconfig: "^10.0.1",
-    picomatch: "^4.0.7",
-    undici: "7.29.1",
-    zod: "^4.6.1"
-  },
-  devDependencies: {
-    "@commitlint/cli": "^21.2.2",
-    "@commitlint/config-conventional": "^21.2.2",
-    "@exadev/eslint-config": "2.12.1",
-    "@semantic-release/changelog": "^7.0.0",
-    "@semantic-release/git": "^11.0.1",
-    "@semantic-release/npm": "^13.1.5",
-    "@types/node": "^26.5.1",
-    "@types/picomatch": "^4.0.3",
-    "@vitest/coverage-v8": "^4.1.11",
-    "conventional-changelog-conventionalcommits": "^10.4.0",
-    esbuild: "^0.28.2",
-    eslint: "^10.10.0",
-    globals: "^17.12.0",
-    husky: "^9.1.7",
-    jiti: "^2.7.0",
-    knip: "^6.35.1",
-    "lint-staged": "^17.5.0",
-    rollup: "4.64.0",
-    "rollup-plugin-dts": "6.5.1",
-    "semantic-release": "^25.0.9",
-    turbo: "^2.11.5",
-    typescript: "^6.0.3",
-    "typescript-eslint": "^8.70.0",
-    vitest: "^4.1.11"
-  },
-  main: "dist/index.cjs",
-  module: "dist/index.mjs",
-  types: "dist/types/index.d.ts",
-  exports: {
-    ".": {
-      types: "./dist/types/index.d.ts",
-      import: "./dist/index.mjs",
-      require: "./dist/index.cjs"
-    },
-    "./package.json": "./package.json"
-  }
-};
-
 // src/launcher/argv.ts
 var ConflictingIdentityError = class extends UsageError {
   constructor(positional, flag) {

package/dist/types/index.d.ts

@@ -2503,6 +2503,8 @@ interface PrePipelineApi {
  * Mounted on the provider listener beside the bespoke namespace, authenticated by the same per-generation owner-only control token as a Bearer credential: a fresh random value per door start, written owner-only under the front door's state directory, and checked in constant time like every other capability the door accepts. `rc.subscribe` streams the client attachment's fan-out: every event the door's held stream produced, SSE-framed by oRPC's event iterator, each carrying its sequence number as the SSE event id so a consumer's own reconnect can resume exactly as the door's does.
  *
  * This module also owns the mount's router-agnostic plumbing, which the control-plane routers (`controlApi.ts`) serve on the same prefix under the same token: the control-token middleware (`doorApiAuth`), the node-handler builder (`doorApiNodeHandlerOf`) and the TLS-pinned client link (`frontDoorApiLink`).
+ *
+ * Every procedure is route-annotated (method, path, summary, tags) under the mount's one REST namespace (`/rest/...`), so the mount serves the same operations twice over: as the oRPC RPC protocol the typed clients and the web client speak, and as plain REST for consumers with no TypeScript client (curl, scripts, other languages), with the OpenAPI document of the whole surface at `RC_OPENAPI_DOC_PATH` under the same token. The two share one router, one token middleware and one Zod schema source, so nothing can drift between them; an annotated (method, path) pair is served REST-shaped and everything else falls through to the RPC handler, and no RPC procedure path begins with `/rest`, so neither address space can ever capture the other.
  */
 /** The one path prefix the typed API is mounted under, answered before the routed pipeline like the bespoke control routes are. */
 declare const RC_ORPC_PATH_PREFIX = "/__agent-shim/orpc";
@@ -2751,9 +2753,9 @@ declare function createRcApiRouter(deps: RcApiDeps): {
 /** The typed API's router, as the CLI-side client's own type is derived from it. */
 type RcApiRouter = ReturnType<typeof createRcApiRouter>;
 /**
- * Builds the node handler that serves one router of the door's typed API under the mount's one prefix: the pre-pipeline surface the provider listener hands every request under `RC_ORPC_PATH_PREFIX`, answering with `matched: false` for a path under the prefix that names no procedure (which the listener itself answers as a 404). Request bodies are bounded by the same protocol cap the bespoke routes apply. Every router the mount serves (Remote Control and the control plane) goes through this one builder, so the prefix, the context and the cap are stated once.
+ * Builds the node handler that serves one router of the door's typed API under the mount's one prefix, twice over: the OpenAPI handler answers every route-annotated (method, path) pair as plain REST (every annotation under `/rest`, which no RPC procedure path begins with, so the RPC protocol's own POSTs always fall through untouched), and everything else falls to the RPC handler, which answers the oRPC protocol the typed clients and the web client speak. The OpenAPI document of the annotated routes is served at `RC_OPENAPI_DOC_PATH`, behind the same per-generation control token the procedures demand, so a consumer with no TypeScript client reads the whole surface from the mount itself. The pre-pipeline surface the provider listener hands every request under `RC_ORPC_PATH_PREFIX`, answering with `matched: false` for a path under the prefix that names no route and no procedure (which the listener itself answers as a 404). Request bodies are bounded by the same protocol cap the bespoke routes apply, on both handlers. Every router the mount serves (Remote Control and the control plane) goes through this one builder, so the prefix, the context and the cap are stated once.
  */
-declare function doorApiNodeHandlerOf(router: AnyRouter): PrePipelineApi;
+declare function doorApiNodeHandlerOf(router: AnyRouter, expectedToken: string): PrePipelineApi;
 /**
  * Builds the typed API's node handler for the Remote Control router alone: the pre-pipeline surface the provider listener hands every request under `RC_ORPC_PATH_PREFIX`.
  */
@@ -3913,6 +3915,7 @@ declare function formatFrontDoorStatus(status: FrontDoorStatus, caCertPath: stri
  * - `usage.*` reads the per-identity usage snapshots the door's own middleware writes, reads a provider's quota windows the way every in-process consumer does (`effectiveWindow`: a window past its reset is empty and carries no status), and reads the live rate-limit observations the event backbone files off the Remote Control client stream (`live`: per-session latest state, exactly as fresh as the last turn a session completed, never a timer's derivation of it).
  * - `frontdoor.*` returns what `agent-shim frontdoor status` returns: the supervisor state, its liveness, the session registry's launches and the headroom hop.
  * - `check.run` and `doctor.run` return the reports `agent-shim check` and `agent-shim doctor` print, as data, `check.run` parameterised by an absolute directory path.
+ * - `pool.pick` returns what `agent-shim pool pick` prints, the ranked pick for one pool exactly as a launch from the named absolute directory would make it right now, so a programmatic consumer can ask which identity to use without reading the door host's files.
  *
  * Read-only by design: identity, configuration-profile, provider, pool and directory-rule management stay CLI-side, and adding writes over this mount is a decision of its own rather than a gap here. `createDoorApiNodeHandler` mounts these routers and the door-wide `events.subscribe` router beside the Remote Control router on the one prefix the provider listener already serves, so a consumer dials one address with one token for the whole door.
  */
@@ -3938,6 +3941,10 @@ interface ControlApiDeps {
     readonly checkReport: (path: string, identity?: string) => CheckReport;
     /** The doctor report, as `collectDoctorReport` collects it. */
     readonly doctorReport: () => DoctorReport;
+    /** The ranked pick for one pool as a launch from one absolute directory would make it right now, exactly `pool pick`'s own product; undefined when the pool table names no such pool. */
+    readonly poolPick: (pool: string, directory: string) => PoolPickReport | undefined;
+    /** The pool table's live names, so an unknown pool is refused naming the real ones rather than answered as an empty ranking. */
+    readonly poolNames: () => readonly string[];
 }
 /** Builds the control-plane routers: one procedure per read, every one behind the control-token middleware. */
 declare function createControlApiRouter(deps: ControlApiDeps): {
@@ -4461,6 +4468,44 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
             }, zod_v4_core.$strict>>>;
         }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
     };
+    pool: {
+        pick: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<DoorApiContext & Record<never, never>, DoorApiContext, DoorApiContext>, any, zod.ZodObject<{
+            pool: zod.ZodString;
+            path: zod.ZodString;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            pool: zod.ZodString;
+            directory: zod.ZodString;
+            pick: zod.ZodOptional<zod.ZodString>;
+            candidates: zod.ZodArray<zod.ZodObject<{
+                identity: zod.ZodString;
+                class: zod.ZodEnum<{
+                    unknown: "unknown";
+                    scored: "scored";
+                    "pay-per-use": "pay-per-use";
+                    ineligible: "ineligible";
+                }>;
+                score: zod.ZodOptional<zod.ZodNumber>;
+                feasible: zod.ZodBoolean;
+                blockedUntil: zod.ZodOptional<zod.ZodISODateTime>;
+                plan: zod.ZodUnion<readonly [zod.ZodObject<{
+                    kind: zod.ZodLiteral<"subscription">;
+                    capacity: zod.ZodNumber;
+                    recognised: zod.ZodBoolean;
+                    tier: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>, zod.ZodObject<{
+                    kind: zod.ZodLiteral<"pay-per-use">;
+                    tier: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>]>;
+                reasons: zod.ZodArray<zod.ZodString>;
+            }, zod_v4_core.$strict>>;
+            missing: zod.ZodArray<zod.ZodString>;
+            earliestReturn: zod.ZodOptional<zod.ZodObject<{
+                identity: zod.ZodString;
+                at: zod.ZodISODateTime;
+            }, zod_v4_core.$strict>>;
+            stickyProblem: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+    };
 };
 /** The control-plane routers, as the merged mount's and the client's own types are derived from them. */
 type ControlApiRouter = ReturnType<typeof createControlApiRouter>;
@@ -4996,6 +5041,44 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
             }, zod_v4_core.$strict>>>;
         }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
     };
+    pool: {
+        pick: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<DoorApiContext & Record<never, never>, DoorApiContext, DoorApiContext>, any, zod.ZodObject<{
+            pool: zod.ZodString;
+            path: zod.ZodString;
+        }, zod_v4_core.$strict>, zod.ZodObject<{
+            pool: zod.ZodString;
+            directory: zod.ZodString;
+            pick: zod.ZodOptional<zod.ZodString>;
+            candidates: zod.ZodArray<zod.ZodObject<{
+                identity: zod.ZodString;
+                class: zod.ZodEnum<{
+                    unknown: "unknown";
+                    scored: "scored";
+                    "pay-per-use": "pay-per-use";
+                    ineligible: "ineligible";
+                }>;
+                score: zod.ZodOptional<zod.ZodNumber>;
+                feasible: zod.ZodBoolean;
+                blockedUntil: zod.ZodOptional<zod.ZodISODateTime>;
+                plan: zod.ZodUnion<readonly [zod.ZodObject<{
+                    kind: zod.ZodLiteral<"subscription">;
+                    capacity: zod.ZodNumber;
+                    recognised: zod.ZodBoolean;
+                    tier: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>, zod.ZodObject<{
+                    kind: zod.ZodLiteral<"pay-per-use">;
+                    tier: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>]>;
+                reasons: zod.ZodArray<zod.ZodString>;
+            }, zod_v4_core.$strict>>;
+            missing: zod.ZodArray<zod.ZodString>;
+            earliestReturn: zod.ZodOptional<zod.ZodObject<{
+                identity: zod.ZodString;
+                at: zod.ZodISODateTime;
+            }, zod_v4_core.$strict>>;
+            stickyProblem: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strict>, Record<never, never>, Record<never, never>>;
+    };
     rc: {
         list: _orpc_server.DecoratedProcedure<_orpc_server.MergedInitialContext<DoorApiContext & Record<never, never>, DoorApiContext, DoorApiContext>, any, Schema<unknown, unknown>, zod.ZodObject<{
             sessions: zod.ZodReadonly<zod.ZodArray<zod.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "8.28.0",
+  "version": "8.30.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>",
@@ -51,6 +51,7 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "@orpc/client": "1.15.4",
+    "@orpc/openapi": "1.15.4",
     "@orpc/server": "1.15.4",
     "commander": "^15.0.0",
     "cosmiconfig": "^10.0.1",