agent-shim 8.18.0 → 8.20.0

package/dist/types/index.d.ts

@@ -354,9 +354,25 @@ declare const ConfigProfileSchema: z.ZodObject<{
 type ConfigProfile = z.infer<typeof ConfigProfileSchema>;
 /** A pool's own name: the identity alphabet minus `@`, since a pool is never an email address. */
 declare const PoolNameSchema: z.ZodString;
-/** A named, explicit set of identities to choose among at launch. Never implicit: a pool lists its members, so an identity that bills a client is only ever picked when someone put it there. */
+/** How a pool chooses the member a launch runs as: "score" by remaining quota, "listed" in the order the pool names its members. */
+declare const PoolPreferenceSchema: z.ZodEnum<{
+    score: "score";
+    listed: "listed";
+}>;
+type PoolPreference = z.infer<typeof PoolPreferenceSchema>;
+/**
+ * A named, explicit set of identities to choose among at launch. Never implicit: a pool lists its members, so an identity that bills a client is only ever picked when someone put it there.
+ *
+ * A member entry may name another pool (`pool:<name>`), which is ranked with its own preference and contributes its pick at the entry's position; see `PoolMemberSchema`. The graph must stay acyclic, which `pool add`/`pool set` enforce and `doctor` re-checks.
+ *
+ * `preference` decides how the member is chosen, and an absent field means "score". "score" ranks members by plan-size-weighted remaining quota per hour until reset, so the quota closest to expiring is spent first (use-it-or-lose-it). "listed" ranks members strictly in the order the pool lists them, skipping only a member that is currently refused, so a pool can pin one identity first and fall back to the others only while that one is refused.
+ */
 declare const PoolSchema: z.ZodObject<{
     identities: z.ZodArray<z.ZodString>;
+    preference: z.ZodOptional<z.ZodEnum<{
+        score: "score";
+        listed: "listed";
+    }>>;
 }, z.core.$strict>;
 type Pool = z.infer<typeof PoolSchema>;
 /** One directory rule in `~/.agent-shim/directory-rules.json`, scoped to an explicit absolute (or `~`-rooted) path. */
@@ -588,6 +604,10 @@ declare const GlobalConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
     pools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         identities: z.ZodArray<z.ZodString>;
+        preference: z.ZodOptional<z.ZodEnum<{
+            score: "score";
+            listed: "listed";
+        }>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 type GlobalConfig = z.infer<typeof GlobalConfigSchema>;
@@ -3978,13 +3998,13 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
-                    pool: "pool";
-                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
                     "path-resolution": "path-resolution";
                     "legacy-name": "legacy-name";
+                    pool: "pool";
+                    keychain: "keychain";
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
@@ -4455,13 +4475,13 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
-                    pool: "pool";
-                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
                     "path-resolution": "path-resolution";
                     "legacy-name": "legacy-name";
+                    pool: "pool";
+                    keychain: "keychain";
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
@@ -4749,13 +4769,13 @@ declare const DoctorFindingSchema: z.ZodObject<{
         "config-profile": "config-profile";
         identity: "identity";
         provider: "provider";
-        pool: "pool";
-        keychain: "keychain";
         "ambient-credential": "ambient-credential";
         "binary-discovery": "binary-discovery";
         "claude-shim": "claude-shim";
         "path-resolution": "path-resolution";
         "legacy-name": "legacy-name";
+        pool: "pool";
+        keychain: "keychain";
         "directory-rules": "directory-rules";
         "categories-local": "categories-local";
         "active-identity": "active-identity";
@@ -4778,13 +4798,13 @@ declare const DoctorRunOutputSchema: z.ZodObject<{
             "config-profile": "config-profile";
             identity: "identity";
             provider: "provider";
-            pool: "pool";
-            keychain: "keychain";
             "ambient-credential": "ambient-credential";
             "binary-discovery": "binary-discovery";
             "claude-shim": "claude-shim";
             "path-resolution": "path-resolution";
             "legacy-name": "legacy-name";
+            pool: "pool";
+            keychain: "keychain";
             "directory-rules": "directory-rules";
             "categories-local": "categories-local";
             "active-identity": "active-identity";
@@ -5058,6 +5078,21 @@ declare function planOf(account: AccountMetadata | undefined): PlanClass;
 
 /** Anthropic's longest prompt-cache lifetime (the one-hour tier): a conversation resumed within it still has a warm cache on the account that served it, and the cache is per organisation, so it is lost by switching. */
 declare const PROMPT_CACHE_TTL_MS: number;
+/**
+ * Stands for a nested `pool:<name>` member entry rather than a direct identity. `pick` carries the nested pool's own pick (its identity and reasons), which the outer ranking re-ranks from that identity's snapshot like any member; `refused` marks an entry whose every member is refused, so the entry itself is ineligible, carrying the nested pool's earliest return.
+ */
+type NestedContribution = {
+    readonly kind: "pick";
+    readonly pool: string;
+    readonly reasons: readonly string[];
+} | {
+    readonly kind: "refused";
+    readonly pool: string;
+    readonly earliestReturn?: {
+        readonly identity: string;
+        readonly atMs: number;
+    };
+};
 /** The state a member's ranking was built from. */
 interface PoolMember {
     readonly identity: string;
@@ -5068,6 +5103,8 @@ interface PoolMember {
     readonly account?: AccountMetadata;
     /** The member's usage-log records from the current five-hour window on. */
     readonly records: readonly UsageRecord[];
+    /** Present when this member stands for a nested `pool:<name>` entry rather than a direct identity. */
+    readonly nested?: NestedContribution;
 }
 /** The member last picked for this directory, kept so a conversation stays on the account whose prompt cache is warm. */
 interface StickyPick {
@@ -5080,6 +5117,8 @@ interface RankPoolInput {
     readonly sticky?: StickyPick;
     /** True when the launch continues or resumes a conversation, which belongs on the account it started on whatever the cache lifetime. */
     readonly resuming: boolean;
+    /** How members are ordered: "score" (the default when absent) by the use-it-or-lose-it ranking, "listed" strictly in `members` order. */
+    readonly preference?: "score" | "listed";
 }
 /** In pick order. `scored` has usable quota data; `unknown` has none (never recorded, or unreadable); `pay-per-use` bills by use instead of drawing on a plan; `ineligible` is refused right now. */
 type CandidateClass = "scored" | "unknown" | "pay-per-use" | "ineligible";
@@ -5111,18 +5150,20 @@ interface PoolRanking {
  * Ranks `members` for a launch.
  *
  * A member is `ineligible` while a window of its plan, or a refusal it last hit, still binds; it is `unknown` without recorded quota, `pay-per-use` when its usage bills by use, and otherwise `scored`. Scored members order by how much plan-size-weighted quota would expire unused per hour of runway, with any whose five-hour window would run dry at the observed pace (their own, or the person's pace on another member rescaled by plan size) placed behind those that would not. The member last picked for this directory then moves to the front if it is still usable and either the launch resumes a conversation or its prompt cache is still warm.
+ *
+ * How members are ordered depends on `preference`. The default, "score", is the order above: class first, then feasibility, then score, with ties by name. "listed" keeps the order of `members`, which callers build in pool member order, so member order, not class, decides: an `unknown` (no usage recorded) or `pay-per-use` member can be picked before a later `scored` one, which is the list owner's stated preference, and a `scored` member that is not feasible keeps its place and its reason line rather than being demoted. In both modes the pick is the first non-`ineligible` candidate, `earliestReturn` still reports the soonest returning refused member, and the sticky-pick promotion applies unchanged.
  */
 declare function rankPool(input: RankPoolInput): PoolRanking;
 
 /**
- * Ranks a pool exactly as a launch from `directory` would right now, without recording a pick. Shares `rankPoolFromStore` with the launcher, so what this prints is what a launch does.
+ * Ranks a pool exactly as a launch from `directory` would right now, without recording a pick. Shares `rankPoolGraph` with the launcher, so what this prints is what a launch does.
  */
 declare function collectPoolPick(params: Readonly<{
     paths: LayoutPaths;
     fs: FsPort;
     usageFs: FarmFs;
     poolName: string;
-    pool: Pool;
+    pools: Readonly<Record<string, Pool>>;
     directory: string;
     nowMs: number;
 }>): PoolPickReport;
@@ -5492,10 +5533,10 @@ declare class PoolNotFoundError extends CliError {
 declare function readPools(paths: LayoutPaths): Readonly<Record<string, Pool>>;
 /** The pool named `name`; throws `PoolNotFoundError` when none is defined. */
 declare function requirePool(paths: LayoutPaths, name: string): Pool;
-/** Defines a new pool. Throws `InvalidPoolNameError` for a name `PoolNameSchema` rejects and `PoolAlreadyExistsError` for one already defined. */
-declare function addPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
-/** Replaces an existing pool's members. Throws `PoolNotFoundError` when it is not defined. */
-declare function setPool(paths: LayoutPaths, name: string, identities: readonly string[]): Pool;
+/** Defines a new pool. Throws `InvalidPoolNameError` for a name `PoolNameSchema` rejects, `PoolAlreadyExistsError` for one already defined, and `UsageError` for a nested member that names an undefined pool or a cycle. */
+declare function addPool(paths: LayoutPaths, name: string, identities: readonly string[], preference?: PoolPreference): Pool;
+/** Replaces an existing pool's members and preference. Throws `PoolNotFoundError` when it is not defined, and `UsageError` for a nested member that names an undefined pool or a cycle. */
+declare function setPool(paths: LayoutPaths, name: string, identities: readonly string[], preference?: PoolPreference): Pool;
 /** Removes a pool. Throws `PoolNotFoundError` when it is not defined. Anything that selected it (an active-identity file, a directory rule) is left for `doctor` to report, as with a removed identity. */
 declare function removePool(paths: LayoutPaths, name: string): void;
 
@@ -5687,4 +5728,4 @@ interface PrepareClaudeLaunchOptions {
 declare function prepareClaudeLaunch(options: PrepareClaudeLaunchOptions): LaunchPlan;
 
 export { AMBIENT_CREDENTIAL_VARS, CHECK_CREDENTIAL_APPLIES, CONNECT_INTERCEPT_HOST, CONNECT_INTERCEPT_HOSTS, CONNECT_LIMITS, CONTROL_PATH_PREFIX, CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, CheckReportJsonSchema, CheckRunInputSchema, CliError, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DOOR_EVENT_BUFFER_EVENTS, DOOR_EVENT_SOURCE_RC, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, DirectoryRuleSchema, DirectoryRulesSchema, DoctorFindingSchema, DoctorRunOutputSchema, DoorEventSchema, DoorEventSourceQuerySchema, EXIT_FAILURE, EXIT_USAGE, EffectiveWindowSchema, EntryValueSchema, FARM_MANIFEST_FILENAME, FrontDoorSessionStatusSchema, FrontDoorSessionsOutputSchema, FrontDoorStartError, FrontDoorStateSchema, FrontDoorStatusOutputSchema, GlobalConfigSchema, HeadroomSocketTargetSchema, HeadroomStartError, IdentityAlreadyExistsError, IdentityNotFoundError, IdentitySchema, InvalidCategoryNameError, InvalidIdentityNameError, InvalidProviderNameError, LAUNCH_EVENT_SOURCE, LaunchLifecycleEventSchema, LaunchRefusedError, LegacyProviderFileError, PROMPT_CACHE_TTL_MS, PlanClassSchema, PoolNameSchema, PoolNotFoundError, PoolPickReportSchema, PoolSchema, PortableConfigSchema, ProfileAlreadyExistsError, ProfileNotFoundError, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, ProviderSchema, RC_IDLE_EXPIRY_MS, RC_ORPC_PATH_PREFIX, RC_PENDING_DEADLINE_MS, RC_PERMISSION_MODES, RC_REQUEST_PARSE_CAP_BYTES, RC_SELF_HOST_ENV, RC_SELF_HOST_KEEPALIVE_MS, RC_SELF_HOST_RECORD_DIR, RC_SELF_HOST_RECORD_FILE, RC_SELF_HOST_RETENTION_MS, RC_SELF_HOST_SCOPE_LIST, RC_SELF_HOST_WORKER_JWT_TTL_SECONDS, RC_SESSIONS_PATH_PREFIX, RC_STREAM_BACKOFF_MS, ROUTED_PATH_PREFIX, RcPermissionModeSchema, RcStreamEnvelopeSchema, RcStreamEventSchema, UsageError, UsageListOutputSchema, UsageSnapshotError, UsageSnapshotSchema, UsageWindowsInputSchema, UsageWindowsOutputSchema, WhenSchema, addDirectoryRule, addIdentity, addPool, addProvider, answerRcControlRequest, buildEntryFacts, buildLayoutPaths, buildRcControlResponsePayload, buildRcEventWriteBody, buildRcInterruptPayload, buildRcSetModelPayload, buildRcSetPermissionModePayload, buildRcUserMessagePayload, carryOver, checkReportHasWarnings, checkReportToJson, collectCheckReport, collectDoctorReport, collectFrontDoorStatus, collectPoolPick, createControlApiRouter, createDoorApiNodeHandler, createDoorApiRouter, createDoorEventHub, createEventsApiRouter, createLaunchEventPublisher, createLeafCache, createProfile, createRcApiNodeHandler, createRcApiRouter, createRcControlHandler, createRcCredentialStore, createRcEventFanout, createRcSelfHostSurface, createRcSessionTracker, createRcStreamHub, createSseParser, describeProviderEndpoint, detectAmbientCredential, doorApiAuth, doorApiNodeHandlerOf, effectiveWindow, ensureCa, ensureFrontDoor, ensureHeadroom, evaluateAmbientCredentialGuard, evaluateWhen, formatAmbientCredentialGuardMessage, formatCheckReport, formatDoctorReport, formatFrontDoorStatus, forwardableHeaders, frontDoorApiClient, frontDoorApiLink, frontDoorRcApiClient, frontDoorRcControl, generateCa, headroomSocketTarget, identityExists, injectRcUserMessage, interruptRcSession, isIdentityDirectoryName, isInterceptedHost, isRcPermissionMode, lateRcEventDial, lateRcStreamDial, listDirectoryRules, listIdentities, listProfiles, listProviders, listUsageSnapshots, matchBranch, mintLeaf, mintRcSelfHostCredential, observingRoutedRoute, parseConnectTarget, parseRcStreamEnvelope, planOf, prepareClaudeLaunch, prepareLaunch, profileExists, providerExists, rankPool, rcEventWriteResultFromAnswer, rcFanoutOnDoorHub, rcObserverAsPassthrough, rcSelfHostFromEnv, readActiveIdentity, readDirectoryRules, readFarmManifest, readGlobalConfig, readIdentity, readPools, readProfile, readProvider, readRcSelfHostRecord, readUsageSnapshot, realConnectCertStore, realConnectEffects, realRcControlTransport, realRcEventDial, realRcStreamDial, recoverFarm, recoveryDiagnostics, removeDirectoryRule, removeIdentity, removePool, removeProfile, removeProvider, requirePool, resolveAgentShimHome, resolveClaudeHome, resolveDecisions, resolveLayoutPaths, resolveSupervisorConfig, resyncFarm, runCheck, runDoctor, runFrontDoorSupervisor, runLauncher, runSupervisor, servedByPipeline, setAllowAmbientCredential, setDefaultConfigProfile, setGlobalDefaultProfile, setIdentityCredential, setPool, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, setRcSessionModel, setRcSessionPermissionMode, snapshotPath, spawnClaude, startConnectServer, topLevelNames, updateDirectoryRule, updateProvider, useIdentity, writeDirectoryRules };
-export type { AddDirectoryRuleOptions, AddProviderInput, AmbientCredentialDetection, AmbientCredentialGuardResult, AmbientCredentialVar, BuildEntryFactsParams, CaMaterial, Candidate, CarryOverParams, CarryOverResult, CategoryMap, CheckReport, CheckReportJson, CollectCheckReportParams, CollectDoctorReportParams, CompiledRule, ConditionContext, ConfigProfile, ConnectCertStore, ConnectEffects, ConnectLimits, ConnectLocalSurface, ConnectServerConfig, ConnectServerHandle, ConnectTarget, ControlApiClient, ControlApiDeps, ControlApiRouter, Credential, CredentialSource, Decision, Diagnostic, DirectoryRule, DirectoryRules, DoctorReport, DoorApiClient, DoorApiContext, DoorApiDeps, DoorApiRouter, DoorEvent, DoorEventHub, DoorEventPublisher, DoorEventStream, DoorEventsApiDeps, EffectiveWindow, EliminatedRule, EnsureFrontDoorPorts, EnsureHeadroomPorts, EntryFact, EntryFacts, EntryValue, EvaluateAmbientCredentialGuardParams, FlattenedCascade, FrontDoorRcControl, FrontDoorSessionStatus, FrontDoorStatus, FrontDoorSupervisorPorts, GlobalConfig, HeadroomSupervisorConfig, Identity, IdentityCredentialChange, IdentityListEntry, IdentityListing, InjectedCredential, LaunchEventPublisher, LaunchLifecycleEvent, LaunchPlan, Layer, LayerId, LayoutPaths, LeafCert, PlanClass, Pool, PoolMember, PoolPickReport, PoolRanking, PortableConfig, PrepareClaudeLaunchOptions, PrepareLaunchParams, ProfileListEntry, Provider, ProviderListEntry, RankPoolInput, RcAnswerDecision, RcAnswerDeps, RcApiClient, RcApiDeps, RcApiRouter, RcControlAnswer, RcControlHandlerDeps, RcControlRequestDeps, RcControlTransport, RcCredentialStore, RcDialAnswer, RcDialTarget, RcEventDial, RcEventFanout, RcEventWriteResult, RcExchangeObserver, RcInjectDeps, RcObservedCredential, RcObservedRequest, RcPendingRequestSummary, RcPermissionMode, RcPresenceAnswer, RcSelfHostCredentialRecord, RcSelfHostDeps, RcSelfHostMintResult, RcSelfHostSurface, RcSessionStatus, RcSessionSummary, RcSessionTracker, RcSessionTrackerDeps, RcStreamAnswer, RcStreamDial, RcStreamEnvelope, RcStreamEvent, RcStreamHub, RcStreamHubDeps, RcWorkerFact, RcWriteHeaders, RecoverFarmParams, RecoveryResult, ResolveDecisionsInput, ResolvedState, ResyncFarmParams, ResyncFarmResult, RunCheckParams, RunDoctorParams, RunFrontDoorSupervisorOptions, RunLauncherParams, RunSupervisorOptions, SpawnClaudeParams, SseParsedEvent, StickyPick, SupervisorPorts, UnreadableIdentityListEntry, UpdateDirectoryRuleOptions, UpdateProviderInput, UsageReadFs, UsageSnapshot, WhenCondition, WhenEvaluation };
+export type { AddDirectoryRuleOptions, AddProviderInput, AmbientCredentialDetection, AmbientCredentialGuardResult, AmbientCredentialVar, BuildEntryFactsParams, CaMaterial, Candidate, CarryOverParams, CarryOverResult, CategoryMap, CheckReport, CheckReportJson, CollectCheckReportParams, CollectDoctorReportParams, CompiledRule, ConditionContext, ConfigProfile, ConnectCertStore, ConnectEffects, ConnectLimits, ConnectLocalSurface, ConnectServerConfig, ConnectServerHandle, ConnectTarget, ControlApiClient, ControlApiDeps, ControlApiRouter, Credential, CredentialSource, Decision, Diagnostic, DirectoryRule, DirectoryRules, DoctorReport, DoorApiClient, DoorApiContext, DoorApiDeps, DoorApiRouter, DoorEvent, DoorEventHub, DoorEventPublisher, DoorEventStream, DoorEventsApiDeps, EffectiveWindow, EliminatedRule, EnsureFrontDoorPorts, EnsureHeadroomPorts, EntryFact, EntryFacts, EntryValue, EvaluateAmbientCredentialGuardParams, FlattenedCascade, FrontDoorRcControl, FrontDoorSessionStatus, FrontDoorStatus, FrontDoorSupervisorPorts, GlobalConfig, HeadroomSupervisorConfig, Identity, IdentityCredentialChange, IdentityListEntry, IdentityListing, InjectedCredential, LaunchEventPublisher, LaunchLifecycleEvent, LaunchPlan, Layer, LayerId, LayoutPaths, LeafCert, NestedContribution, PlanClass, Pool, PoolMember, PoolPickReport, PoolRanking, PortableConfig, PrepareClaudeLaunchOptions, PrepareLaunchParams, ProfileListEntry, Provider, ProviderListEntry, RankPoolInput, RcAnswerDecision, RcAnswerDeps, RcApiClient, RcApiDeps, RcApiRouter, RcControlAnswer, RcControlHandlerDeps, RcControlRequestDeps, RcControlTransport, RcCredentialStore, RcDialAnswer, RcDialTarget, RcEventDial, RcEventFanout, RcEventWriteResult, RcExchangeObserver, RcInjectDeps, RcObservedCredential, RcObservedRequest, RcPendingRequestSummary, RcPermissionMode, RcPresenceAnswer, RcSelfHostCredentialRecord, RcSelfHostDeps, RcSelfHostMintResult, RcSelfHostSurface, RcSessionStatus, RcSessionSummary, RcSessionTracker, RcSessionTrackerDeps, RcStreamAnswer, RcStreamDial, RcStreamEnvelope, RcStreamEvent, RcStreamHub, RcStreamHubDeps, RcWorkerFact, RcWriteHeaders, RecoverFarmParams, RecoveryResult, ResolveDecisionsInput, ResolvedState, ResyncFarmParams, ResyncFarmResult, RunCheckParams, RunDoctorParams, RunFrontDoorSupervisorOptions, RunLauncherParams, RunSupervisorOptions, SpawnClaudeParams, SseParsedEvent, StickyPick, SupervisorPorts, UnreadableIdentityListEntry, UpdateDirectoryRuleOptions, UpdateProviderInput, UsageReadFs, UsageSnapshot, WhenCondition, WhenEvaluation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "8.18.0",
+  "version": "8.20.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>",
@@ -79,7 +79,7 @@
     "rollup": "4.64.0",
     "rollup-plugin-dts": "6.5.1",
     "semantic-release": "^25.0.9",
-    "turbo": "^2.10.12",
+    "turbo": "^2.11.5",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.0",
     "vitest": "^4.1.11"