@inixiative/agent-session 0.4.0 → 0.5.2

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.4.0",
+  "version": "0.5.2",
   "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",
   "types": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./routing": "./src/routing.ts"
   },
   "files": [
     "src"
@@ -35,11 +36,11 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.4.1"
+    "@inixiative/json-rules": "^3.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.62",
+    "@inixiative/config": "^0.5.64",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/index.ts

@@ -86,6 +86,7 @@ export {
 } from './primed';
 export {
   assessCandidate,
+  type BillingMode,
   type CandidateRequest,
   DEFAULT_STRATEGY,
   type ExclusionReason,

package/src/pool.ts

@@ -19,12 +19,14 @@ import type { HarnessSession } from './harness-session';
 import { type LimitSnapshot, mergeLimits } from './limits';
 import { probeClaudeLimits, probeCodexLimits } from './limits-probe';
 import {
+  type BillingMode,
   type ExclusionReason,
   type OrderingSpec,
   type RankedCandidate,
   type ResolvedOrdering,
   rankCandidates,
   type SubscriptionCandidate,
+  type UnknownUtilizationPolicy,
 } from './routing';
 import { TRANSPORTS, type TransportKind } from './transport';
 import { createSession } from './transports';
@@ -66,6 +68,9 @@ export interface PoolRequest {
   readonly ordering?: OrderingSpec;
   /** Only the preferred instance may serve. Requires preferredInstanceId. */
   readonly pinned?: boolean;
+  /** Billing modes this request may use. Default: subscription only. */
+  readonly allowedBilling?: readonly BillingMode[];
+  readonly unknownUtilization?: UnknownUtilizationPolicy;
   /** Restrict to these transports (e.g. only resumable ones). */
   readonly transports?: readonly TransportKind[];
   readonly excludeInstanceIds?: readonly string[];
@@ -228,6 +233,8 @@ export class SubscriptionPool {
       const limit = config.concurrencyLimit ?? 1;
       if (!Number.isSafeInteger(limit) || limit < 1)
         throw Error(`Instance ${config.id}: concurrencyLimit must be a positive integer`);
+      if (config.priority !== undefined && !Number.isSafeInteger(config.priority))
+        throw Error(`Instance ${config.id}: priority must be a safe integer`);
       this._instances.set(config.id, {
         config,
         runtime,
@@ -332,6 +339,10 @@ export class SubscriptionPool {
         maximumObservationAgeMs: this._maxAge,
         ordering: request.ordering,
         ...(request.pinned !== undefined ? { pinned: request.pinned } : {}),
+        ...(request.allowedBilling !== undefined ? { allowedBilling: request.allowedBilling } : {}),
+        ...(request.unknownUtilization !== undefined
+          ? { unknownUtilization: request.unknownUtilization }
+          : {}),
         organizationId: request.organizationId,
         preferredId: request.preferredInstanceId,
       },

package/src/routing.ts

@@ -20,6 +20,7 @@
 // ---------------------------------------------------------------------------
 
 import type { OrderBy, SortDir } from '@inixiative/json-rules';
+import { orderRecords } from '@inixiative/json-rules';
 
 export type { OrderBy, SortDir };
 
@@ -73,9 +74,8 @@ 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 (!Object.hasOwn(ROUTING_STRATEGIES, spec)) throw Error(`Unknown routing strategy "${spec}"`);
+    return resolveOrdering(ROUTING_STRATEGIES[spec]);
   }
   if (!spec.length) throw Error('Ordering requires at least one term');
   return spec.map((term) => {
@@ -127,6 +127,16 @@ export interface SubscriptionCandidate {
  */
 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;
@@ -138,6 +148,7 @@ export interface RoutingRequest {
   ordering?: OrderingSpec;
   pinned?: boolean;
   unknownUtilization?: UnknownUtilizationPolicy;
+  allowedBilling?: readonly BillingMode[];
 }
 
 /** Repository resolution already done by the caller (or not needed). */
@@ -153,6 +164,8 @@ export interface CandidateRequest {
   /** 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 {
@@ -167,7 +180,7 @@ export interface RankedCandidate {
 
 export type ExclusionReason =
   | 'disabled'
-  | 'not-subscription'
+  | 'billing'
   | 'organization'
   | 'runtime'
   | 'model'
@@ -214,7 +227,7 @@ export function repositoryIdentity(remote: string): string {
   return `${url.hostname.toLowerCase()}/${normalized}`;
 }
 
-/** Why one candidate is ineligible, or undefined with its utilization when eligible. */
+/** Why one candidate is ineligible, or its utilization when eligible. */
 export function assessCandidate(
   request: CandidateRequest,
   account: SubscriptionCandidate,
@@ -229,7 +242,8 @@ export function assessCandidate(
   )
     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)
@@ -242,13 +256,13 @@ export function assessCandidate(
     return { excluded: 'unavailable' };
   if (account.activeRuns >= account.concurrencyLimit) return { excluded: 'occupied' };
   if (account.blocked) return { excluded: 'blocked' };
-  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[] = [];
+  const rankLast = request.unknownUtilization === 'rank-last';
+  if (account.windows.length === 0)
+    return rankLast ? { utilizationPercent: null } : { excluded: 'no-observation' };
+  const readable: number[] = [];
+  let unreadable = false;
   for (const window of account.windows) {
+    // Corrupt is not unknown: a structurally impossible reading is never routable under any policy.
     if (
       window.usedPercent === null ||
       !Number.isFinite(window.usedPercent) ||
@@ -257,7 +271,7 @@ export function assessCandidate(
       !Number.isFinite(window.reservedPercent) ||
       window.reservedPercent < 0
     )
-      return unreadable === undefined ? { excluded: 'invalid' } : { utilizationPercent: null };
+      return { excluded: 'invalid' };
     // resetsAt === Infinity: the provider reported no reset for this window, so no reset can have crossed the observation.
     if (
       !Number.isFinite(window.observedAt) ||
@@ -265,30 +279,29 @@ export function assessCandidate(
       request.now - window.observedAt > request.maximumObservationAgeMs ||
       (window.resetsAt !== Number.POSITIVE_INFINITY &&
         (!Number.isFinite(window.resetsAt) || window.resetsAt <= request.now))
-    )
-      return unreadable === undefined
-        ? { excluded: 'stale-observation' }
-        : { utilizationPercent: null };
-    fractions.push(window.usedPercent + window.reservedPercent);
+    ) {
+      if (!rankLast) return { excluded: 'stale-observation' };
+      unreadable = true;
+      continue;
+    }
+    readable.push(window.usedPercent + window.reservedPercent);
   }
-  if (fractions.some((p) => p >= 100)) return { excluded: 'exhausted' };
-  return { utilizationPercent: Math.max(...fractions) };
+  // A window that is readable and full exhausts the instance even when another is not.
+  if (readable.some((p) => p >= 100)) return { excluded: 'exhausted' };
+  if (unreadable || !readable.length) return { utilizationPercent: null };
+  return { utilizationPercent: Math.max(...readable) };
 }
 
-const FIELD_VALUE: Record<RoutingField, (candidate: RankedCandidate) => number | null> = {
-  priority: (c) => c.priority,
-  utilization: (c) => c.utilizationPercent,
-  quartile: (c) => c.quartile,
-  headroom: (c) => c.headroom,
-  preferred: (c) => Number(c.preferred),
-};
-
-/** Nulls last in either direction: an unknown reading never outranks a known one. */
-const compare = (a: number | null, b: number | null, dir: SortDir): number => {
-  if (a === null) return b === null ? 0 : 1;
-  if (b === null) return -1;
-  return dir === 'desc' ? b - a : a - b;
-};
+/** 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(
@@ -307,6 +320,8 @@ export function rankCandidates(
     throw Error('Invalid observation policy');
   if (request.pinned && !request.preferredId)
     throw Error('Pinned routing requires a preferred instance');
+  if (request.allowedBilling?.length === 0)
+    throw Error('Ordering requires at least one billing mode');
   if (new Set(accounts.map((a) => a.id)).size !== accounts.length)
     throw Error('Duplicate account identity');
   const ordering = resolveOrdering(request.ordering);
@@ -329,14 +344,8 @@ export function rankCandidates(
       },
     ];
   });
-  ranked.sort((a, b) => {
-    for (const { field, dir } of ordering) {
-      const order = compare(FIELD_VALUE[field](a), FIELD_VALUE[field](b), dir);
-      if (order !== 0) return order;
-    }
-    return a.accountId.localeCompare(b.accountId);
-  });
-  return { candidates: ranked, excluded, ordering };
+  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. */
@@ -373,6 +382,7 @@ export function rankSubscriptionAccounts(
       ...(request.unknownUtilization !== undefined
         ? { unknownUtilization: request.unknownUtilization }
         : {}),
+      ...(request.allowedBilling !== undefined ? { allowedBilling: request.allowedBilling } : {}),
     },
     accounts,
   );