@inixiative/agent-session 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
@@ -18,7 +18,7 @@
     "prepublishOnly": "bun run check",
     "measure:primed": "bun scripts/measure-primed.ts",
     "lint": "biome check .",
-    "prepare": "lefthook install"
+    "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi"
   },
   "keywords": [
     "claude-code",
@@ -34,9 +34,12 @@
     "eval"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@inixiative/json-rules": "^3.5.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.41",
+    "@inixiative/config": "^0.5.63",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/index.ts

@@ -86,16 +86,27 @@ export {
 } from './primed';
 export {
   assessCandidate,
+  type BillingMode,
   type CandidateRequest,
+  DEFAULT_STRATEGY,
   type ExclusionReason,
+  type OrderBy,
+  type OrderingSpec,
+  type OrderingTerm,
   type RankedCandidate,
   type RepositoryRoute,
-  type RoutingMode,
+  type ResolvedOrdering,
+  ROUTING_STRATEGIES,
+  type RoutingField,
   type RoutingRequest,
+  type RoutingStrategy,
   rankCandidates,
   rankSubscriptionAccounts,
   repositoryIdentity,
+  resolveOrdering,
+  type SortDir,
   type SubscriptionCandidate,
+  type UnknownUtilizationPolicy,
 } from './routing';
 // Transports: how a session reaches its model, with declared capabilities.
 export {

package/src/pool.ts

@@ -20,8 +20,9 @@ import { type LimitSnapshot, mergeLimits } from './limits';
 import { probeClaudeLimits, probeCodexLimits } from './limits-probe';
 import {
   type ExclusionReason,
+  type OrderingSpec,
   type RankedCandidate,
-  type RoutingMode,
+  type ResolvedOrdering,
   rankCandidates,
   type SubscriptionCandidate,
 } from './routing';
@@ -48,6 +49,8 @@ export interface InstanceConfig {
   readonly models?: Readonly<Record<string, readonly string[]>>;
   /** Concurrent leases. Default 1. */
   readonly concurrencyLimit?: number;
+  /** Lower serves first under a priority ordering. Default 0. */
+  readonly priority?: number;
   readonly enabled?: boolean;
   readonly authentication?: 'subscription' | 'api-key';
   /** Session config merged into every session opened on this instance (bin, spawn, SDK query…). */
@@ -60,7 +63,9 @@ export interface PoolRequest {
   readonly effort?: string;
   readonly organizationId?: string;
   readonly preferredInstanceId?: string;
-  readonly mode?: RoutingMode;
+  readonly ordering?: OrderingSpec;
+  /** Only the preferred instance may serve. Requires preferredInstanceId. */
+  readonly pinned?: boolean;
   /** Restrict to these transports (e.g. only resumable ones). */
   readonly transports?: readonly TransportKind[];
   readonly excludeInstanceIds?: readonly string[];
@@ -90,8 +95,8 @@ export type PoolEvent =
       readonly leaseId: string;
       readonly instanceId: string;
       readonly transport: PooledTransport;
-      readonly mode: RoutingMode;
-      readonly utilizationPercent: number;
+      readonly ordering: ResolvedOrdering;
+      readonly utilizationPercent: number | null;
       readonly rank: number;
     }
   | { readonly type: 'released'; readonly leaseId: string; readonly instanceId: string }
@@ -288,6 +293,7 @@ export class SubscriptionPool {
   rank(request: PoolRequest): {
     candidates: RankedCandidate[];
     excluded: Record<string, ExclusionReason>;
+    ordering: ResolvedOrdering;
   } {
     const now = this._now();
     const effort = request.effort ?? 'default';
@@ -304,6 +310,7 @@ export class SubscriptionPool {
         models: state.config.models ?? { [request.model]: [effort] },
         activeRuns: state.leases.size,
         concurrencyLimit: state.config.concurrencyLimit ?? 1,
+        priority: state.config.priority ?? 0,
         windows: (limits?.windows ?? []).map((w) => ({
           usedPercent: w.usedPercent,
           reservedPercent: reserved,
@@ -323,7 +330,8 @@ export class SubscriptionPool {
         effort,
         now,
         maximumObservationAgeMs: this._maxAge,
-        mode: request.mode,
+        ordering: request.ordering,
+        ...(request.pinned !== undefined ? { pinned: request.pinned } : {}),
         organizationId: request.organizationId,
         preferredId: request.preferredInstanceId,
       },
@@ -333,7 +341,7 @@ export class SubscriptionPool {
 
   /** Lease the best instance now, or throw PoolExhaustedError with every exclusion reason. */
   acquire(request: PoolRequest): Lease {
-    const { candidates, excluded } = this.rank(request);
+    const { candidates, excluded, ordering } = this.rank(request);
     const best = candidates[0];
     if (!best) {
       this._emit({ type: 'exhausted', runtime: request.runtime, model: request.model, excluded });
@@ -346,12 +354,7 @@ export class SubscriptionPool {
         excluded,
       );
     }
-    return this._lease(
-      this._state(best.accountId),
-      request.mode ?? 'quartile-balanced',
-      best.utilizationPercent,
-      0,
-    );
+    return this._lease(this._state(best.accountId), ordering, best.utilizationPercent, 0);
   }
 
   /** Refresh stale limits, lease an instance and open a session on it. The lease ends with the session. */
@@ -429,7 +432,7 @@ export class SubscriptionPool {
       );
     const allowed = new Set(shared.map((s) => s.config.id));
     await this._refreshStale(request, allowed);
-    const { candidates, excluded } = this.rank({
+    const { candidates, excluded, ordering } = this.rank({
       ...request,
       excludeInstanceIds: [
         ...(request.excludeInstanceIds ?? []),
@@ -451,12 +454,7 @@ export class SubscriptionPool {
       );
     binding.session?.kill();
     binding.lease?.release();
-    const lease = this._lease(
-      this._state(best.accountId),
-      request.mode ?? 'quartile-balanced',
-      best.utilizationPercent,
-      0,
-    );
+    const lease = this._lease(this._state(best.accountId), ordering, best.utilizationPercent, 0);
     try {
       const session = this._session(
         lease,
@@ -566,8 +564,8 @@ export class SubscriptionPool {
   }
   private _lease(
     state: InstanceState,
-    mode: RoutingMode,
-    utilizationPercent: number,
+    ordering: ResolvedOrdering,
+    utilizationPercent: number | null,
     rank: number,
   ): Lease {
     const leaseId = crypto.randomUUID();
@@ -593,7 +591,7 @@ export class SubscriptionPool {
       leaseId,
       instanceId: state.config.id,
       transport: state.config.transport,
-      mode,
+      ordering,
       utilizationPercent,
       rank,
     });

package/src/routing.ts

@@ -8,18 +8,84 @@
 // does not mint authority, read credentials or call a model, and a routing
 // preference never widens a grant (organization, runtime, model, billing).
 //
-// Strategies:
-//   quartile-balanced (default)  lowest usage quartile first; the preferred
-//                                (owning) instance wins within its quartile.
-//   owner-first                  the preferred instance while eligible, then
-//                                spillover by utilization.
-//   pinned                       the preferred instance only; otherwise none.
+// Ordering is an ordered list of terms over the fields projected onto each
+// eligible candidate, in `@inixiative/json-rules`' `OrderBy` vocabulary.
+// Named strategies are presets over that list; a caller may pass its own terms
+// instead. `id` is always the final term, so ranking is total and deterministic.
 //
-// Unknown, stale, future or reset-crossing limit observations exclude an
-// instance: routing never guesses capacity.
+// Eligibility is separate from ordering: `pinned` restricts which instances may
+// serve at all, and unknown, stale, future or reset-crossing limit observations
+// mean routing has no capacity reading for an instance. By default that excludes
+// it — routing never guesses capacity.
 // ---------------------------------------------------------------------------
 
-export type RoutingMode = 'quartile-balanced' | 'owner-first' | 'pinned';
+import type { OrderBy, SortDir } from '@inixiative/json-rules';
+import { orderRecords } from '@inixiative/json-rules';
+
+export type { OrderBy, SortDir };
+
+export type RoutingField = 'priority' | 'utilization' | 'quartile' | 'headroom' | 'preferred';
+
+export interface OrderingTerm {
+  readonly field: RoutingField;
+  readonly dir?: SortDir;
+}
+
+export type RoutingStrategy =
+  | 'quartile-balanced'
+  | 'owner-first'
+  | 'priority-balanced'
+  | 'priority-strict'
+  | 'least-used';
+
+export type OrderingSpec = RoutingStrategy | readonly OrderingTerm[];
+
+/** Every term carries a direction. Assignable to json-rules' `OrderBy`. */
+export type ResolvedOrdering = { field: RoutingField; dir: SortDir }[];
+
+/** The direction that puts the better candidate first when a term omits one. */
+const NATURAL_DIRECTION: Record<RoutingField, SortDir> = {
+  priority: 'asc',
+  utilization: 'asc',
+  quartile: 'asc',
+  headroom: 'desc',
+  preferred: 'desc',
+};
+
+export const ROUTING_STRATEGIES: Record<RoutingStrategy, readonly OrderingTerm[]> = {
+  'quartile-balanced': [{ field: 'quartile' }, { field: 'preferred' }, { field: 'utilization' }],
+  'owner-first': [{ field: 'preferred' }, { field: 'utilization' }],
+  // Load decides between tiers that differ by a quartile; priority decides within one.
+  'priority-balanced': [
+    { field: 'quartile' },
+    { field: 'priority' },
+    { field: 'preferred' },
+    { field: 'utilization' },
+  ],
+  // Priority dominates: a lower tier serves only once every higher one is excluded.
+  'priority-strict': [{ field: 'priority' }, { field: 'utilization' }],
+  'least-used': [{ field: 'utilization' }],
+};
+
+export const DEFAULT_STRATEGY: RoutingStrategy = 'quartile-balanced';
+
+const ROUTING_FIELDS = Object.keys(NATURAL_DIRECTION) as RoutingField[];
+
+/** Resolve a strategy name or explicit term list into terms, each with a direction. */
+export const resolveOrdering = (spec: OrderingSpec = DEFAULT_STRATEGY): ResolvedOrdering => {
+  if (typeof spec === 'string') {
+    const preset = ROUTING_STRATEGIES[spec];
+    if (!preset) throw Error(`Unknown routing strategy "${spec}"`);
+    return resolveOrdering(preset);
+  }
+  if (!spec.length) throw Error('Ordering requires at least one term');
+  return spec.map((term) => {
+    if (!ROUTING_FIELDS.includes(term.field)) throw Error(`Unknown ordering field "${term.field}"`);
+    if (term.dir !== undefined && term.dir !== 'asc' && term.dir !== 'desc')
+      throw Error(`Unknown sort direction "${term.dir}"`);
+    return { field: term.field, dir: term.dir ?? NATURAL_DIRECTION[term.field] };
+  });
+};
 
 export interface RepositoryRoute {
   repository: string;
@@ -37,6 +103,8 @@ export interface SubscriptionCandidate {
   models: Readonly<Record<string, readonly string[]>>;
   activeRuns: number;
   concurrencyLimit: number;
+  /** Lower serves first. Absent is 0, so prioritized and unprioritized instances order together. */
+  priority?: number;
   /** All provider enforcement windows, plus locally retained reservations. `resetsAt: Infinity` means none reported. */
   windows: readonly {
     usedPercent: number | null;
@@ -50,6 +118,26 @@ export interface SubscriptionCandidate {
   unavailableUntil?: number;
 }
 
+/**
+ * What to do with an instance routing has no usable capacity reading for.
+ *
+ * `exclude` (default) suits provider-enforced subscription windows, where an
+ * unread login may already be exhausted and sending work there fails the turn.
+ * `rank-last` suits capacity whose spend is bounded elsewhere (Kingdom gates on
+ * allocation policies), where a never-observed instance must stay usable.
+ */
+export type UnknownUtilizationPolicy = 'exclude' | 'rank-last';
+
+/**
+ * How an instance is paid for. Routing serves only `subscription` unless the
+ * caller widens it: spending real money is the caller's decision, never a
+ * routing default. Kingdom widens to `api-key`, where a run's spend is bounded
+ * by its allocation policies.
+ */
+export type BillingMode = 'subscription' | 'api-key';
+
+const DEFAULT_BILLING: readonly BillingMode[] = ['subscription'];
+
 export interface RoutingRequest {
   repository: string;
   organizationId?: string;
@@ -58,7 +146,10 @@ export interface RoutingRequest {
   effort: string;
   now: number;
   maximumObservationAgeMs: number;
-  mode?: RoutingMode;
+  ordering?: OrderingSpec;
+  pinned?: boolean;
+  unknownUtilization?: UnknownUtilizationPolicy;
+  allowedBilling?: readonly BillingMode[];
 }
 
 /** Repository resolution already done by the caller (or not needed). */
@@ -70,19 +161,27 @@ export interface CandidateRequest {
   effort: string;
   now: number;
   maximumObservationAgeMs: number;
-  mode?: RoutingMode;
+  ordering?: OrderingSpec;
+  /** Only the preferred instance may serve; others are excluded as `not-pinned`. */
+  pinned?: boolean;
+  unknownUtilization?: UnknownUtilizationPolicy;
+  /** Billing modes this request may use. Default: subscription only. */
+  allowedBilling?: readonly BillingMode[];
 }
 
 export interface RankedCandidate {
   accountId: string;
-  utilizationPercent: number;
-  quartile: number;
+  /** Null when no usable observation exists and the policy is `rank-last`. */
+  utilizationPercent: number | null;
+  quartile: number | null;
+  priority: number;
+  headroom: number;
   preferred: boolean;
 }
 
 export type ExclusionReason =
   | 'disabled'
-  | 'not-subscription'
+  | 'billing'
   | 'organization'
   | 'runtime'
   | 'model'
@@ -133,17 +232,19 @@ export function repositoryIdentity(remote: string): string {
 export function assessCandidate(
   request: CandidateRequest,
   account: SubscriptionCandidate,
-): { excluded: ExclusionReason } | { utilizationPercent: number } {
+): { excluded: ExclusionReason } | { utilizationPercent: number | null } {
   if (
     !account.id ||
     !Number.isSafeInteger(account.activeRuns) ||
     account.activeRuns < 0 ||
     !Number.isSafeInteger(account.concurrencyLimit) ||
-    account.concurrencyLimit < 1
+    account.concurrencyLimit < 1 ||
+    (account.priority !== undefined && !Number.isFinite(account.priority))
   )
     return { excluded: 'invalid' };
   if (!account.enabled) return { excluded: 'disabled' };
-  if (account.authentication !== 'subscription') return { excluded: 'not-subscription' };
+  if (!(request.allowedBilling ?? DEFAULT_BILLING).includes(account.authentication))
+    return { excluded: 'billing' };
   if (
     request.organizationId !== undefined &&
     !account.organizationIds.includes(request.organizationId)
@@ -151,13 +252,16 @@ export function assessCandidate(
     return { excluded: 'organization' };
   if (account.runtime !== request.runtime) return { excluded: 'runtime' };
   if (!account.models[request.model]?.includes(request.effort)) return { excluded: 'model' };
-  if (request.mode === 'pinned' && account.id !== request.preferredId)
-    return { excluded: 'not-pinned' };
+  if (request.pinned && account.id !== request.preferredId) return { excluded: 'not-pinned' };
   if (account.unavailableUntil !== undefined && account.unavailableUntil > request.now)
     return { excluded: 'unavailable' };
   if (account.activeRuns >= account.concurrencyLimit) return { excluded: 'occupied' };
   if (account.blocked) return { excluded: 'blocked' };
-  if (account.windows.length === 0) return { excluded: 'no-observation' };
+  const unreadable = request.unknownUtilization === 'rank-last' ? null : undefined;
+  if (account.windows.length === 0) {
+    if (unreadable === undefined) return { excluded: 'no-observation' };
+    return { utilizationPercent: null };
+  }
   const fractions: number[] = [];
   for (const window of account.windows) {
     if (
@@ -168,7 +272,7 @@ export function assessCandidate(
       !Number.isFinite(window.reservedPercent) ||
       window.reservedPercent < 0
     )
-      return { excluded: 'invalid' };
+      return unreadable === undefined ? { excluded: 'invalid' } : { utilizationPercent: null };
     // resetsAt === Infinity: the provider reported no reset for this window, so no reset can have crossed the observation.
     if (
       !Number.isFinite(window.observedAt) ||
@@ -177,28 +281,46 @@ export function assessCandidate(
       (window.resetsAt !== Number.POSITIVE_INFINITY &&
         (!Number.isFinite(window.resetsAt) || window.resetsAt <= request.now))
     )
-      return { excluded: 'stale-observation' };
+      return unreadable === undefined
+        ? { excluded: 'stale-observation' }
+        : { utilizationPercent: null };
     fractions.push(window.usedPercent + window.reservedPercent);
   }
   if (fractions.some((p) => p >= 100)) return { excluded: 'exhausted' };
   return { utilizationPercent: Math.max(...fractions) };
 }
 
+/** Term fields as own properties, so json-rules orders them by name. */
+const sortKey = (candidate: RankedCandidate, index: number) => ({
+  index,
+  priority: candidate.priority,
+  utilization: candidate.utilizationPercent,
+  quartile: candidate.quartile,
+  headroom: candidate.headroom,
+  preferred: Number(candidate.preferred),
+  id: candidate.accountId,
+});
+
 /** Rank eligible candidates deterministically (ties broken by id). */
 export function rankCandidates(
   request: CandidateRequest,
   accounts: readonly SubscriptionCandidate[],
-): { candidates: RankedCandidate[]; excluded: Record<string, ExclusionReason> } {
+): {
+  candidates: RankedCandidate[];
+  excluded: Record<string, ExclusionReason>;
+  ordering: ResolvedOrdering;
+} {
   if (
     !Number.isFinite(request.now) ||
     !Number.isFinite(request.maximumObservationAgeMs) ||
     request.maximumObservationAgeMs <= 0
   )
     throw Error('Invalid observation policy');
-  if (request.mode === 'pinned' && !request.preferredId)
+  if (request.pinned && !request.preferredId)
     throw Error('Pinned routing requires a preferred instance');
   if (new Set(accounts.map((a) => a.id)).size !== accounts.length)
     throw Error('Duplicate account identity');
+  const ordering = resolveOrdering(request.ordering);
   const excluded: Record<string, ExclusionReason> = {};
   const ranked = accounts.flatMap((account) => {
     const assessed = assessCandidate(request, account);
@@ -211,22 +333,15 @@ export function rankCandidates(
       {
         accountId: account.id,
         utilizationPercent,
-        quartile: Math.floor(utilizationPercent / 25),
+        quartile: utilizationPercent === null ? null : Math.floor(utilizationPercent / 25),
+        priority: account.priority ?? 0,
+        headroom: account.concurrencyLimit - account.activeRuns,
         preferred: account.id === request.preferredId,
       },
     ];
   });
-  ranked.sort((a, b) =>
-    request.mode === 'owner-first' || request.mode === 'pinned'
-      ? Number(b.preferred) - Number(a.preferred) ||
-        a.utilizationPercent - b.utilizationPercent ||
-        a.accountId.localeCompare(b.accountId)
-      : a.quartile - b.quartile ||
-        Number(b.preferred) - Number(a.preferred) ||
-        a.utilizationPercent - b.utilizationPercent ||
-        a.accountId.localeCompare(b.accountId),
-  );
-  return { candidates: ranked, excluded };
+  const ordered = orderRecords(ranked.map(sortKey), [...ordering, { field: 'id', dir: 'asc' }]);
+  return { candidates: ordered.map((key) => ranked[key.index]!), excluded, ordering };
 }
 
 /** The draft's repository-scoped entry point: resolve ownership, then rank. */
@@ -249,7 +364,7 @@ export function rankSubscriptionAccounts(
     throw Error('Incomplete repository routing rule');
   if (request.organizationId && request.organizationId !== route.organizationId)
     throw Error('Explicit organization conflicts with repository ownership');
-  const { candidates } = rankCandidates(
+  const { candidates, ordering } = rankCandidates(
     {
       organizationId: route.organizationId,
       preferredId: route.preferredAccountId,
@@ -258,7 +373,12 @@ export function rankSubscriptionAccounts(
       effort: request.effort,
       now: request.now,
       maximumObservationAgeMs: request.maximumObservationAgeMs,
-      mode: request.mode,
+      ordering: request.ordering,
+      ...(request.pinned !== undefined ? { pinned: request.pinned } : {}),
+      ...(request.unknownUtilization !== undefined
+        ? { unknownUtilization: request.unknownUtilization }
+        : {}),
+      ...(request.allowedBilling !== undefined ? { allowedBilling: request.allowedBilling } : {}),
     },
     accounts,
   );
@@ -267,7 +387,7 @@ export function rankSubscriptionAccounts(
     organizationId: route.organizationId,
     model: request.model,
     effort: request.effort,
-    mode: request.mode ?? 'quartile-balanced',
+    ordering,
     candidates,
   };
 }