agent-shim 8.30.0 → 8.32.0

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   CredentialSourceSchema: () => CredentialSourceSchema,
   DOOR_EVENT_BUFFER_EVENTS: () => DOOR_EVENT_BUFFER_EVENTS,
   DOOR_EVENT_SOURCE_RC: () => DOOR_EVENT_SOURCE_RC,
+  DOOR_HEALTH_EVENT_SOURCE: () => DOOR_HEALTH_EVENT_SOURCE,
   DirectoryRuleAlreadyExistsError: () => DirectoryRuleAlreadyExistsError,
   DirectoryRuleMissingTargetError: () => DirectoryRuleMissingTargetError,
   DirectoryRuleNotFoundError: () => DirectoryRuleNotFoundError,
@@ -57,6 +58,7 @@ __export(index_exports, {
   DoctorRunOutputSchema: () => DoctorRunOutputSchema,
   DoorEventSchema: () => DoorEventSchema,
   DoorEventSourceQuerySchema: () => DoorEventSourceQuerySchema,
+  DoorHealthEventSchema: () => DoorHealthEventSchema,
   EXIT_FAILURE: () => EXIT_FAILURE,
   EXIT_USAGE: () => EXIT_USAGE,
   EffectiveWindowSchema: () => EffectiveWindowSchema,
@@ -93,6 +95,8 @@ __export(index_exports, {
   ProviderKindMismatchError: () => ProviderKindMismatchError,
   ProviderNotFoundError: () => ProviderNotFoundError,
   ProviderSchema: () => ProviderSchema,
+  QUOTA_EXPIRING_EVENT_SOURCE: () => QUOTA_EXPIRING_EVENT_SOURCE,
+  QuotaExpiringEventSchema: () => QuotaExpiringEventSchema,
   RC_CONTEXT_USAGE_DETAILS: () => RC_CONTEXT_USAGE_DETAILS,
   RC_IDLE_EXPIRY_MS: () => RC_IDLE_EXPIRY_MS,
   RC_ORPC_PATH_PREFIX: () => RC_ORPC_PATH_PREFIX,
@@ -120,6 +124,7 @@ __export(index_exports, {
   RcRateLimitWindowSchema: () => RcRateLimitWindowSchema,
   RcStreamEnvelopeSchema: () => RcStreamEnvelopeSchema,
   RcStreamEventSchema: () => RcStreamEventSchema,
+  USAGE_EVENT_SOURCE: () => USAGE_EVENT_SOURCE,
   UsageError: () => UsageError,
   UsageListOutputSchema: () => UsageListOutputSchema,
   UsageLiveOutputSchema: () => UsageLiveOutputSchema,
@@ -165,10 +170,12 @@ __export(index_exports, {
   createDoorApiNodeHandler: () => createDoorApiNodeHandler,
   createDoorApiRouter: () => createDoorApiRouter,
   createDoorEventHub: () => createDoorEventHub,
+  createDoorHealthPublisher: () => createDoorHealthPublisher,
   createEventsApiRouter: () => createEventsApiRouter,
   createLaunchEventPublisher: () => createLaunchEventPublisher,
   createLeafCache: () => createLeafCache,
   createProfile: () => createProfile,
+  createQuotaExpiringPublisher: () => createQuotaExpiringPublisher,
   createRcApiNodeHandler: () => createRcApiNodeHandler,
   createRcApiRouter: () => createRcApiRouter,
   createRcControlHandler: () => createRcControlHandler,
@@ -3034,6 +3041,7 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
   try {
     http3 = await ports.startProviderListener(lastPort);
   } catch (error) {
+    ports.doorHealth.listenerFailed("provider", error instanceof Error ? error.message : String(error));
     return fail(`could not start the provider listener: ${error instanceof Error ? error.message : String(error)}`);
   }
   if (previousSticky !== void 0 && http3.port !== previousSticky) {
@@ -3046,6 +3054,7 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     connect3 = await ports.startConnectListener(lastConnectPort);
   } catch (error) {
     await http3.close();
+    ports.doorHealth.listenerFailed("connect", error instanceof Error ? error.message : String(error));
     return fail(`could not start the CONNECT surface: ${error instanceof Error ? error.message : String(error)}`);
   }
   if (previousStickyConnect !== void 0 && connect3.port !== previousStickyConnect) {
@@ -3059,6 +3068,7 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
   } catch (error) {
     await connect3.close();
     await http3.close();
+    ports.doorHealth.listenerFailed("direct", error instanceof Error ? error.message : String(error));
     return fail(`could not start the direct listener: ${error instanceof Error ? error.message : String(error)}`);
   }
   if (previousStickyDirect !== void 0 && direct.port !== previousStickyDirect) {
@@ -3066,6 +3076,7 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
   }
   lastDirectPort = direct.port;
   writeFrontDoorState(fs12, paths.frontdoorStateFile, { protocol: FRONT_DOOR_PROTOCOL, supervisorPid: ports.ownPid, port: http3.port, connectPort: connect3.port, directPort: direct.port, ...sticky() });
+  ports.doorHealth.generation({ providerPort: http3.port, connectPort: connect3.port, directPort: direct.port });
   fs12.removeRecursive(paths.frontdoorLockFile);
   ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http3.port)}, CONNECT surface on 127.0.0.1:${String(connect3.port)}`);
   let idleSince;
@@ -3078,11 +3089,13 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     const listed = listFrontDoorSessions(fs12, paths.frontdoorSessionsDir);
     const pruned = pruneDeadFrontDoorSessions(fs12, paths.frontdoorSessionsDir, ports.isRunning);
     ports.observeLaunchRegistry(listed, pruned);
+    ports.checkQuotaExpiry();
     const prunedPids = new Set(pruned);
     if (listed.filter((session) => !prunedPids.has(session.pid)).length === 0) {
       idleSince ??= ports.now();
       if (ports.now() - idleSince >= idleShutdownMinutes * MS_PER_MINUTE) {
         ports.log(`agent-shim frontdoor supervisor: no sessions for ${String(idleShutdownMinutes)} minute(s); closing the front door and exiting`);
+        ports.doorHealth.idleShutdown();
         await direct.close();
         await connect3.close();
         await http3.close();
@@ -5342,7 +5355,7 @@ var import_undici = require("undici");
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.30.0",
+  version: "8.32.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>",
@@ -6524,10 +6537,10 @@ function windowBlockedUntil(windows) {
   const resets = windows.flatMap((window) => window.status === "rejected" && window.resetsAtMs !== void 0 ? [window.resetsAtMs] : []);
   return resets.length === 0 ? void 0 : Math.max(...resets);
 }
-function fiveHourBurn(records) {
+function windowBurn(records, which) {
   const points = [];
   for (const record of records) {
-    const window = record.rateLimitHeaders === void 0 ? void 0 : parseUnifiedRateLimit(record.rateLimitHeaders)?.fiveHour;
+    const window = record.rateLimitHeaders === void 0 ? void 0 : parseUnifiedRateLimit(record.rateLimitHeaders)?.[which];
     if (window?.utilization !== void 0 && window.resetsAt !== void 0) {
       points.push({ resetsAt: window.resetsAt, point: { atMs: Date.parse(record.at), utilization: window.utilization } });
     }
@@ -6621,11 +6634,16 @@ function assessIdentity(member, nowMs) {
   const score = remaining * plan.capacity / (untilResetMs / MS_PER_HOUR);
   const fiveRemaining = five?.utilization === void 0 ? void 0 : Math.max(0, 1 - five.utilization);
   const fiveUntil = five?.resetsAtMs === void 0 ? FIVE_HOUR_WINDOW_MS : Math.max(five.resetsAtMs - nowMs, MS_PER_SECOND4);
-  const burn = fiveHourBurn(member.records);
+  const burn = windowBurn(member.records, "fiveHour");
+  const sevenRemaining = seven?.utilization === void 0 ? void 0 : Math.max(0, 1 - seven.utilization);
+  const sevenUntil = seven?.resetsAtMs === void 0 ? SEVEN_DAY_WINDOW_MS : Math.max(seven.resetsAtMs - nowMs, MS_PER_SECOND4);
+  const sevenDayBurn = windowBurn(member.records, "sevenDay");
   return {
     candidate: { ...base, class: "scored", score, reasons: [...windowReasons.map((reason, index) => index === windowReasons.length - 1 ? `${reason}${observedAgo}` : reason), ...planReasons] },
     ...fiveRemaining === void 0 ? {} : { fiveHour: { remaining: fiveRemaining, untilResetMs: fiveUntil } },
-    ...burn === void 0 ? {} : { burn }
+    ...burn === void 0 ? {} : { burn },
+    ...sevenRemaining === void 0 ? {} : { sevenDay: { remaining: sevenRemaining, untilResetMs: sevenUntil } },
+    ...sevenDayBurn === void 0 ? {} : { sevenDayBurn }
   };
 }
 function rankPool(input) {
@@ -6636,14 +6654,27 @@ function rankPool(input) {
   const candidates = assessments.map((assessment) => {
     const { candidate, fiveHour, burn } = assessment;
     const pace = burn ?? (sharedDemand === void 0 ? void 0 : sharedDemand / capacityOf(candidate.plan));
-    if (candidate.class !== "scored" || fiveHour === void 0 || pace === void 0) {
+    const { sevenDay, sevenDayBurn } = assessment;
+    if (candidate.class !== "scored") {
       return { ...candidate, feasible: true };
     }
-    const runsDryInMs = fiveHour.remaining / pace;
-    if (runsDryInMs >= fiveHour.untilResetMs) {
+    const drySpots = [];
+    if (fiveHour !== void 0 && pace !== void 0) {
+      const runsDryInMs = fiveHour.remaining / pace;
+      if (runsDryInMs < fiveHour.untilResetMs) {
+        drySpots.push(`5h window would run dry in ${formatAge(runsDryInMs)}, before it resets in ${formatAge(fiveHour.untilResetMs)}`);
+      }
+    }
+    if (sevenDay !== void 0 && sevenDayBurn !== void 0) {
+      const runsDryInMs = sevenDay.remaining / sevenDayBurn;
+      if (runsDryInMs < sevenDay.untilResetMs) {
+        drySpots.push(`7d window would run dry in ${formatAge(runsDryInMs)}, before it resets in ${formatAge(sevenDay.untilResetMs)}`);
+      }
+    }
+    if (drySpots.length === 0) {
       return { ...candidate, feasible: true };
     }
-    return { ...candidate, feasible: false, reasons: [`5h window would run dry in ${formatAge(runsDryInMs)}, before it resets in ${formatAge(fiveHour.untilResetMs)}`, ...candidate.reasons] };
+    return { ...candidate, feasible: false, reasons: [...drySpots, ...candidate.reasons] };
   });
   const ordered = input.preference === "listed" ? [...candidates] : [...candidates].sort(
     (left, right) => CLASS_ORDER[left.class] - CLASS_ORDER[right.class] || Number(right.feasible) - Number(left.feasible) || (right.score ?? 0) - (left.score ?? 0) || left.identity.localeCompare(right.identity)
@@ -6651,7 +6682,8 @@ function rankPool(input) {
   const sticky = input.sticky;
   const stickyIndex = sticky === void 0 ? -1 : ordered.findIndex((candidate) => candidate.identity === sticky.identity);
   const stickyCandidate = ordered[stickyIndex];
-  if (sticky !== void 0 && stickyCandidate?.class === "scored" && stickyCandidate.feasible) {
+  const keepSticky = stickyCandidate?.class === "scored" && stickyCandidate.feasible;
+  if (sticky !== void 0 && keepSticky) {
     const ageMs = nowMs - Date.parse(sticky.at);
     const warm = ageMs <= PROMPT_CACHE_TTL_MS;
     if (input.resuming || warm) {
@@ -6660,12 +6692,14 @@ function rankPool(input) {
       ordered.unshift({ ...stickyCandidate, reasons: [why, ...stickyCandidate.reasons] });
     }
   }
+  const movedOff = sticky !== void 0 && input.resuming && !keepSticky ? { identity: sticky.identity, reason: stickyCandidate?.reasons[0] ?? "no longer among the pool's members" } : void 0;
   const pick = ordered.find((candidate) => candidate.class !== "ineligible");
   const returns = ordered.flatMap((candidate) => candidate.blockedUntilMs === void 0 ? [] : [{ identity: candidate.identity, atMs: candidate.blockedUntilMs }]);
   const earliestReturn = returns.length === 0 ? void 0 : returns.reduce((soonest, entry) => entry.atMs < soonest.atMs ? entry : soonest);
   return {
     candidates: ordered,
-    ...pick === void 0 ? { ...earliestReturn === void 0 ? {} : { earliestReturn } } : { pick }
+    ...pick === void 0 ? { ...earliestReturn === void 0 ? {} : { earliestReturn } } : { pick },
+    ...movedOff === void 0 || pick === void 0 ? {} : { movedOff }
   };
 }
 
@@ -6923,6 +6957,7 @@ function collectPoolPick(params) {
     candidates: ranking.candidates.map(candidateView),
     missing: missing.map(({ identity }) => identity),
     ...ranking.earliestReturn === void 0 ? {} : { earliestReturn: { identity: ranking.earliestReturn.identity, at: new Date(ranking.earliestReturn.atMs).toISOString() } },
+    ...ranking.movedOff === void 0 ? {} : { movedOff: ranking.movedOff },
     ...sticky.problem === void 0 ? {} : { stickyProblem: sticky.problem }
   };
 }
@@ -9194,6 +9229,8 @@ var PoolPickReportSchema = import_zod13.z.strictObject({
   missing: import_zod13.z.array(import_zod13.z.string()),
   /** When nothing can be picked, the soonest any member returns. */
   earliestReturn: import_zod13.z.strictObject({ identity: import_zod13.z.string(), at: import_zod13.z.iso.datetime() }).optional(),
+  /** The member a resumed conversation started on but moved off, and why, when the ranking could not keep it. */
+  movedOff: import_zod13.z.strictObject({ identity: import_zod13.z.string(), reason: import_zod13.z.string() }).optional(),
   /** Why the last-pick record could not be read, when that is the case. */
   stickyProblem: import_zod13.z.string().optional()
 });
@@ -10204,6 +10241,9 @@ var import_server3 = require("@orpc/server");
 var import_zod20 = require("zod");
 var DOOR_EVENT_SOURCE_RC = "rc";
 var LAUNCH_EVENT_SOURCE = "launch";
+var USAGE_EVENT_SOURCE = "usage";
+var DOOR_HEALTH_EVENT_SOURCE = "door";
+var QUOTA_EXPIRING_EVENT_SOURCE = "quota-expiring";
 var DoorEventSchema = import_zod20.z.strictObject({
   source: import_zod20.z.string().min(1),
   /** A positive integer because the backbone's counters start at one and only ever increase. */
@@ -10219,6 +10259,20 @@ var LaunchLifecycleEventSchema = import_zod20.z.strictObject({
   startedAt: import_zod20.z.number(),
   observedAt: import_zod20.z.number()
 });
+var DoorHealthEventSchema = import_zod20.z.discriminatedUnion("kind", [
+  import_zod20.z.strictObject({ kind: import_zod20.z.literal("generation"), pid: import_zod20.z.number().int().positive(), providerPort: import_zod20.z.number().int().positive(), connectPort: import_zod20.z.number().int().positive(), directPort: import_zod20.z.number().int().positive(), observedAt: import_zod20.z.number() }),
+  import_zod20.z.strictObject({ kind: import_zod20.z.literal("listenerFailed"), pid: import_zod20.z.number().int().positive(), listener: import_zod20.z.enum(["provider", "connect", "direct"]), message: import_zod20.z.string(), observedAt: import_zod20.z.number() }),
+  import_zod20.z.strictObject({ kind: import_zod20.z.literal("idleShutdown"), pid: import_zod20.z.number().int().positive(), observedAt: import_zod20.z.number() })
+]);
+var QuotaExpiringEventSchema = import_zod20.z.strictObject({
+  identity: import_zod20.z.string().min(1),
+  provider: import_zod20.z.string().min(1),
+  window: import_zod20.z.enum(["fiveHour", "sevenDay"]),
+  /** The fraction of the window already used when it was seen expiring, always below one because a fully used window has nothing left to spend. */
+  utilization: import_zod20.z.number().min(0).max(1),
+  resetsAt: import_zod20.z.iso.datetime(),
+  observedAt: import_zod20.z.number()
+});
 
 // src/frontdoor/eventsApi.ts
 var EVENTS_API_TAG = "events";
@@ -10527,6 +10581,81 @@ function createLaunchEventPublisher(hub, now) {
   };
 }
 
+// src/frontdoor/doorHealthEvents.ts
+function createDoorHealthPublisher(hub, now, pid) {
+  const publisher = hub.publisher(DOOR_HEALTH_EVENT_SOURCE);
+  return {
+    generation: (ports) => {
+      publisher.publish({ kind: "generation", pid, providerPort: ports.providerPort, connectPort: ports.connectPort, directPort: ports.directPort, observedAt: now() });
+    },
+    listenerFailed: (listener, message) => {
+      publisher.publish({ kind: "listenerFailed", pid, listener, message, observedAt: now() });
+    },
+    idleShutdown: () => {
+      publisher.publish({ kind: "idleShutdown", pid, observedAt: now() });
+    }
+  };
+}
+
+// src/frontdoor/quotaExpiringEvents.ts
+var MS_PER_HOUR2 = 36e5;
+var MS_PER_DAY2 = 864e5;
+var FIVE_HOUR_WINDOW_HOURS = 5;
+var SEVEN_DAY_WINDOW_DAYS = 7;
+var FIVE_HOUR_WINDOW_MS2 = FIVE_HOUR_WINDOW_HOURS * MS_PER_HOUR2;
+var SEVEN_DAY_WINDOW_MS2 = SEVEN_DAY_WINDOW_DAYS * MS_PER_DAY2;
+var FINAL_SPAN_DENOMINATOR = 30;
+var QUOTA_EXPIRING_WINDOW_FRACTION = 1 / FINAL_SPAN_DENOMINATOR;
+function createQuotaExpiringPublisher(hub, deps) {
+  const publisher = hub.publisher(QUOTA_EXPIRING_EVENT_SOURCE);
+  const latest = /* @__PURE__ */ new Map();
+  for (const snapshot of deps.seed) {
+    latest.set(snapshot.identity, snapshot);
+  }
+  hub.subscribe([USAGE_EVENT_SOURCE], (event) => {
+    const snapshot = UsageSnapshotSchema.parse(event.payload);
+    latest.set(snapshot.identity, snapshot);
+  });
+  const announced = /* @__PURE__ */ new Set();
+  const windowsOf = (snapshot) => {
+    const views = [];
+    for (const provider of Object.keys(snapshot.providers).sort()) {
+      const unified = snapshot.providers[provider]?.rateLimit?.unified;
+      const fiveHour = unified?.fiveHour;
+      if (fiveHour?.utilization !== void 0 && fiveHour.resetsAt !== void 0) {
+        views.push({ provider, view: { window: "fiveHour", spanMs: FIVE_HOUR_WINDOW_MS2, utilization: fiveHour.utilization, resetsAtMs: Date.parse(fiveHour.resetsAt) } });
+      }
+      const sevenDay = unified?.sevenDay;
+      if (sevenDay?.utilization !== void 0 && sevenDay.resetsAt !== void 0) {
+        views.push({ provider, view: { window: "sevenDay", spanMs: SEVEN_DAY_WINDOW_MS2, utilization: sevenDay.utilization, resetsAtMs: Date.parse(sevenDay.resetsAt) } });
+      }
+    }
+    return views;
+  };
+  return {
+    check: () => {
+      const now = deps.now();
+      for (const identity of [...latest.keys()].sort()) {
+        const snapshot = latest.get(identity);
+        if (snapshot === void 0) {
+          continue;
+        }
+        for (const { provider, view } of windowsOf(snapshot)) {
+          if (view.utilization >= 1 || view.resetsAtMs <= now || view.resetsAtMs - now >= view.spanMs * QUOTA_EXPIRING_WINDOW_FRACTION) {
+            continue;
+          }
+          const key = `${identity}:${provider}:${view.window}:${String(view.resetsAtMs)}`;
+          if (announced.has(key)) {
+            continue;
+          }
+          announced.add(key);
+          publisher.publish({ identity, provider, window: view.window, utilization: view.utilization, resetsAt: new Date(view.resetsAtMs).toISOString(), observedAt: now });
+        }
+      }
+    }
+  };
+}
+
 // src/frontdoor/rcLiveUsage.ts
 var RC_RATE_LIMIT_EVENT_TYPE = "rate_limit_event";
 function isRecord5(value) {
@@ -12848,10 +12977,11 @@ function resolvePoolLaunch(params) {
     if (graph.ranking.candidates.length === 0) {
       return { ok: false, message: `agent-shim: no member of pool "${poolName}" is an existing identity.` };
     }
-    const { pick, earliestReturn } = graph.ranking;
+    const { pick, earliestReturn, movedOff } = graph.ranking;
     if (pick !== void 0) {
       recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick.identity, nowMs);
-      return { ok: true, identity: pick.identity, explanation: `pool ${poolName}: ${pick.reasons.slice(0, REASONS_LOGGED).join("; ")}` };
+      const move = movedOff === void 0 ? "" : `moved off ${movedOff.identity} (${movedOff.reason}); `;
+      return { ok: true, identity: pick.identity, explanation: `pool ${poolName}: ${move}${pick.reasons.slice(0, REASONS_LOGGED).join("; ")}` };
     }
     if (earliestReturn === void 0) {
       return { ok: false, message: `agent-shim: no member of pool "${poolName}" can be picked.` };
@@ -13520,6 +13650,7 @@ function prepareClaudeLaunch(options) {
   CredentialSourceSchema,
   DOOR_EVENT_BUFFER_EVENTS,
   DOOR_EVENT_SOURCE_RC,
+  DOOR_HEALTH_EVENT_SOURCE,
   DirectoryRuleAlreadyExistsError,
   DirectoryRuleMissingTargetError,
   DirectoryRuleNotFoundError,
@@ -13529,6 +13660,7 @@ function prepareClaudeLaunch(options) {
   DoctorRunOutputSchema,
   DoorEventSchema,
   DoorEventSourceQuerySchema,
+  DoorHealthEventSchema,
   EXIT_FAILURE,
   EXIT_USAGE,
   EffectiveWindowSchema,
@@ -13565,6 +13697,8 @@ function prepareClaudeLaunch(options) {
   ProviderKindMismatchError,
   ProviderNotFoundError,
   ProviderSchema,
+  QUOTA_EXPIRING_EVENT_SOURCE,
+  QuotaExpiringEventSchema,
   RC_CONTEXT_USAGE_DETAILS,
   RC_IDLE_EXPIRY_MS,
   RC_ORPC_PATH_PREFIX,
@@ -13592,6 +13726,7 @@ function prepareClaudeLaunch(options) {
   RcRateLimitWindowSchema,
   RcStreamEnvelopeSchema,
   RcStreamEventSchema,
+  USAGE_EVENT_SOURCE,
   UsageError,
   UsageListOutputSchema,
   UsageLiveOutputSchema,
@@ -13637,10 +13772,12 @@ function prepareClaudeLaunch(options) {
   createDoorApiNodeHandler,
   createDoorApiRouter,
   createDoorEventHub,
+  createDoorHealthPublisher,
   createEventsApiRouter,
   createLaunchEventPublisher,
   createLeafCache,
   createProfile,
+  createQuotaExpiringPublisher,
   createRcApiNodeHandler,
   createRcApiRouter,
   createRcControlHandler,