@inixiative/agent-session 0.2.0 → 0.3.0

package/src/primed.ts

@@ -0,0 +1,284 @@
+// ---------------------------------------------------------------------------
+// Primed decision sessions — one live, warm session per middleware role
+// ---------------------------------------------------------------------------
+//
+// Each key (Foundry: `${threadId}:aux:${role}`) owns one long-lived session,
+// primed once with its stable context: role instructions plus owned content.
+// That primed state is the cached prefix. Every decision runs on a fresh branch
+// of the primed state and is then discarded, so one cycle never sees another's
+// turns. A key is re-primed only when its prime hash changes, after eviction,
+// or after its process is lost; those are the only cold paths.
+//
+// Decisions are text-only: the launch policy removes tool surfaces, and any
+// tool, command or approval activity is a violation that fails the decision.
+// ---------------------------------------------------------------------------
+
+import { createHash } from 'node:crypto';
+import type { SessionTokens } from './harness-session';
+import type { LimitSnapshot } from './limits';
+
+export interface PrimeSpec {
+  /** Session identity. One live primed session per key. */
+  readonly key: string;
+  /** Role instructions (developer/system role). */
+  readonly instructions: string;
+  /** Stable owned context (layer content), primed as data in the user role. May be empty. */
+  readonly context?: string;
+  /** Content hash of instructions and context. Re-primes when it changes. Default: sha256 of both. */
+  readonly hash?: string;
+}
+
+export interface DecisionAdmission {
+  readonly admissionId: string;
+  readonly key: string;
+  readonly runtime: 'codex' | 'claude';
+  /** Native identity of the branch the decision will run on, when known before the write. */
+  readonly threadId?: string;
+}
+
+export interface DecisionRequest {
+  /** The per-cycle input, run on top of the primed state. */
+  readonly input: string;
+  readonly timeoutMs?: number;
+  /** Required registration before the native write; a rejection means nothing was dispatched. */
+  readonly onAdmission?: (admission: DecisionAdmission) => void | Promise<void>;
+  /** JSON Schema constraining the final message (Codex only). */
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
+  /** Cancel: refused before dispatch, or the running turn is interrupted and settled. */
+  readonly signal?: AbortSignal;
+}
+
+export interface DecisionResult {
+  readonly key: string;
+  readonly admissionId: string;
+  readonly content: string;
+  readonly tokens?: SessionTokens;
+  /** Model the runtime reported serving the session. */
+  readonly model?: string;
+  readonly threadId?: string;
+  readonly turnId?: string;
+  /** `warm`: forked from the key's primed state; `cold`: ran inline (no primed session for this context yet). */
+  readonly prime: 'warm' | 'cold';
+  /** A second branch was started for this slow decision; the result is the first to finish. */
+  readonly hedged?: boolean;
+  /** The runtime fell back from websockets to HTTPS during this decision's turn. */
+  readonly transportFallback?: boolean;
+  readonly timing: {
+    readonly waitMs: number;
+    readonly primeMs: number;
+    readonly branchMs: number;
+    readonly turnMs: number;
+  };
+}
+
+export type DecisionFailure =
+  | 'closed'
+  | 'busy'
+  | 'admission'
+  | 'rate-limited'
+  | 'auth'
+  | 'timeout'
+  | 'aborted'
+  | 'violation'
+  | 'transport'
+  | 'native-failed'
+  | 'prime-failed';
+
+/**
+ * `dispatch: "not-dispatched"`: no model input was written for this decision.
+ * `settled: false`: a native turn may still be running; its process is being recycled.
+ */
+export class DecisionError extends Error {
+  constructor(
+    message: string,
+    readonly reason: DecisionFailure,
+    readonly dispatch: 'not-dispatched' | 'attempted',
+    readonly settled: boolean,
+    readonly admissionId?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'DecisionError';
+  }
+  /** A second branch was started for this decision before it failed; both were stopped. */
+  hedged?: boolean;
+}
+
+export type PrimedEvent =
+  | { readonly type: 'process-started'; readonly generation: number; readonly ms: number }
+  | { readonly type: 'process-recycled'; readonly generation: number; readonly reason: string }
+  | { readonly type: 'primed'; readonly key: string; readonly hash: string; readonly ms: number }
+  | {
+      readonly type: 'evicted';
+      readonly key: string;
+      readonly reason: 'idle' | 'capacity' | 'reprime' | 'requested' | 'process-lost' | 'close';
+    }
+  | {
+      readonly type: 'decision';
+      readonly key: string;
+      readonly prime: 'warm' | 'cold';
+      readonly ms: number;
+      readonly cacheRead?: number;
+      readonly input?: number;
+    }
+  | { readonly type: 'limits'; readonly limits: LimitSnapshot }
+  | { readonly type: 'violation'; readonly key: string; readonly detail: string }
+  | { readonly type: 'hedged'; readonly key: string; readonly afterMs: number }
+  | { readonly type: 'transport-fallback'; readonly key: string };
+
+export interface PrimedSnapshot {
+  readonly runtime: 'codex' | 'claude';
+  readonly closed: boolean;
+  readonly generation: number;
+  readonly processAlive: boolean;
+  readonly sessions: number;
+  readonly active: number;
+  readonly waiting: number;
+  readonly limits?: LimitSnapshot;
+}
+
+export interface PrimedSessions {
+  readonly runtime: 'codex' | 'claude';
+  decide(spec: PrimeSpec, request: DecisionRequest): Promise<DecisionResult>;
+  /** Drop a key's primed session; the next decision re-primes it. */
+  evict(key: string): Promise<void>;
+  limits(): LimitSnapshot | undefined;
+  snapshot(): PrimedSnapshot;
+  close(): Promise<void>;
+}
+
+export function primeHash(spec: PrimeSpec): string {
+  return (
+    spec.hash ??
+    createHash('sha256')
+      .update(spec.instructions)
+      .update('\0')
+      .update(spec.context ?? '')
+      .digest('hex')
+  );
+}
+
+/** FIFO counting semaphore with deadline-bounded waits. */
+export class Slots {
+  private _active = 0;
+  private _waiters: Array<{
+    grant(): void;
+    fail(error: Error): void;
+    timer: ReturnType<typeof setTimeout>;
+  }> = [];
+  constructor(private readonly _limit: number) {
+    if (!Number.isSafeInteger(_limit) || _limit < 1)
+      throw Error('Concurrency limit must be a positive integer');
+  }
+  get active() {
+    return this._active;
+  }
+  get waiting() {
+    return this._waiters.length;
+  }
+  acquire(deadline: number, signal?: AbortSignal): Promise<() => void> {
+    if (signal?.aborted)
+      return Promise.reject(
+        new DecisionError('Decision aborted before dispatch', 'aborted', 'not-dispatched', true),
+      );
+    const release = () => {
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const next = this._waiters.shift();
+        if (next) {
+          clearTimeout(next.timer);
+          next.grant();
+        } else this._active--;
+      };
+    };
+    if (this._active < this._limit) {
+      this._active++;
+      return Promise.resolve(release());
+    }
+    return new Promise((resolve, reject) => {
+      const leave = (error: DecisionError) => {
+        const index = this._waiters.indexOf(waiter);
+        signal?.removeEventListener('abort', onAbort);
+        if (index >= 0) {
+          this._waiters.splice(index, 1);
+          clearTimeout(waiter.timer);
+          reject(error);
+        }
+      };
+      const onAbort = () =>
+        leave(
+          new DecisionError('Decision aborted before dispatch', 'aborted', 'not-dispatched', true),
+        );
+      const waiter = {
+        grant: () => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve(release());
+        },
+        fail: (error: Error) => {
+          signal?.removeEventListener('abort', onAbort);
+          reject(error);
+        },
+        timer: setTimeout(
+          () =>
+            leave(
+              new DecisionError(
+                'Decision expired waiting for a session slot',
+                'busy',
+                'not-dispatched',
+                true,
+              ),
+            ),
+          Math.max(0, deadline - Date.now()),
+        ),
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this._waiters.push(waiter);
+    });
+  }
+  /** A slot only if one is free now (never queues). */
+  tryAcquire(): (() => void) | undefined {
+    if (this._active >= this._limit || this._waiters.length) return undefined;
+    this._active++;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const next = this._waiters.shift();
+      if (next) {
+        clearTimeout(next.timer);
+        next.grant();
+      } else this._active--;
+    };
+  }
+
+  /** Reject every waiter (close). Held slots are released by their owners. */
+  drain(error: Error): void {
+    for (const waiter of this._waiters.splice(0)) {
+      clearTimeout(waiter.timer);
+      waiter.fail(error);
+    }
+  }
+}
+
+/** Per-key serialization: a key's decisions run one at a time, in order. */
+export class KeyedQueue {
+  private _tails = new Map<string, Promise<void>>();
+  run<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const prior = this._tails.get(key) ?? Promise.resolve();
+    const result = prior.then(task, task);
+    const tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    this._tails.set(key, tail);
+    void tail.then(() => {
+      if (this._tails.get(key) === tail) this._tails.delete(key);
+    });
+    return result;
+  }
+  get size() {
+    return this._tails.size;
+  }
+}

package/src/retained-evidence.ts

@@ -4,7 +4,7 @@
 const owned = new WeakSet<object>();
 
 export function retainEvidence<T>(value: T): T {
-  if (value === null || typeof value !== "object" || owned.has(value)) return value;
+  if (value === null || typeof value !== 'object' || owned.has(value)) return value;
   const copy = structuredClone(value);
   const pending: object[] = [copy];
   while (pending.length) {
@@ -12,7 +12,7 @@ export function retainEvidence<T>(value: T): T {
     if (owned.has(item)) continue;
     owned.add(item);
     for (const nested of Object.values(item)) {
-      if (nested !== null && typeof nested === "object") pending.push(nested);
+      if (nested !== null && typeof nested === 'object') pending.push(nested);
     }
     Object.freeze(item);
   }

package/src/routing.ts

@@ -0,0 +1,273 @@
+// ---------------------------------------------------------------------------
+// Deterministic subscription routing
+// ---------------------------------------------------------------------------
+//
+// Ported from Foundry's draft account-routing policy (foundry-jev-routing
+// a60c664, `docs/signet-routing-strategy.md`). Pure functions: invoked only
+// after the caller resolves which instances it is authorized to use. Routing
+// 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.
+//
+// Unknown, stale, future or reset-crossing limit observations exclude an
+// instance: routing never guesses capacity.
+// ---------------------------------------------------------------------------
+
+export type RoutingMode = 'quartile-balanced' | 'owner-first' | 'pinned';
+
+export interface RepositoryRoute {
+  repository: string;
+  organizationId: string;
+  preferredAccountId: string;
+}
+
+export interface SubscriptionCandidate {
+  id: string;
+  organizationIds: readonly string[];
+  runtime: 'codex' | 'claude';
+  authentication: 'subscription' | 'api-key';
+  enabled: boolean;
+  /** model → supported efforts. */
+  models: Readonly<Record<string, readonly string[]>>;
+  activeRuns: number;
+  concurrencyLimit: number;
+  /** All provider enforcement windows, plus locally retained reservations. `resetsAt: Infinity` means none reported. */
+  windows: readonly {
+    usedPercent: number | null;
+    reservedPercent: number;
+    observedAt: number;
+    resetsAt: number;
+  }[];
+  /** The provider reports ordinary usage blocked now. */
+  blocked?: boolean;
+  /** Excluded until this time after local failures (epoch ms). */
+  unavailableUntil?: number;
+}
+
+export interface RoutingRequest {
+  repository: string;
+  organizationId?: string;
+  runtime: 'codex' | 'claude';
+  model: string;
+  effort: string;
+  now: number;
+  maximumObservationAgeMs: number;
+  mode?: RoutingMode;
+}
+
+/** Repository resolution already done by the caller (or not needed). */
+export interface CandidateRequest {
+  organizationId?: string;
+  preferredId?: string;
+  runtime: 'codex' | 'claude';
+  model: string;
+  effort: string;
+  now: number;
+  maximumObservationAgeMs: number;
+  mode?: RoutingMode;
+}
+
+export interface RankedCandidate {
+  accountId: string;
+  utilizationPercent: number;
+  quartile: number;
+  preferred: boolean;
+}
+
+export type ExclusionReason =
+  | 'disabled'
+  | 'not-subscription'
+  | 'organization'
+  | 'runtime'
+  | 'model'
+  | 'occupied'
+  | 'invalid'
+  | 'no-observation'
+  | 'stale-observation'
+  | 'exhausted'
+  | 'blocked'
+  | 'unavailable'
+  | 'not-pinned';
+
+/** Only repository identities, never local paths or URL credentials. GitHub's
+ * scp-style git user is transport syntax, not a credential or organization grant. */
+export function repositoryIdentity(remote: string): string {
+  const scp = /^git@([a-zA-Z0-9.-]+):([^?#\s]+)$/.exec(remote);
+  let url: URL;
+  try {
+    url = new URL(scp ? `ssh://git@${scp[1]}/${scp[2]}` : remote);
+  } catch {
+    throw Error('Repository must be an HTTPS or SSH remote');
+  }
+  if (
+    !['https:', 'ssh:'].includes(url.protocol) ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.port ||
+    (url.username && !(url.protocol === 'ssh:' && url.username === 'git'))
+  )
+    throw Error('Unsupported repository remote');
+  if (/%|\\|\s/.test(url.pathname)) throw Error('Ambiguous repository path');
+  const path = url.pathname
+    .replace(/^\//, '')
+    .replace(/\/$/, '')
+    .replace(/\.git$/, '');
+  if (
+    !path ||
+    path.split('/').length < 2 ||
+    path.split('/').some((p) => !p || p === '.' || p === '..')
+  )
+    throw Error('Repository must include its namespace');
+  const normalized = url.hostname === 'github.com' ? path.toLowerCase() : path;
+  return `${url.hostname.toLowerCase()}/${normalized}`;
+}
+
+/** Why one candidate is ineligible, or undefined with its utilization when eligible. */
+export function assessCandidate(
+  request: CandidateRequest,
+  account: SubscriptionCandidate,
+): { excluded: ExclusionReason } | { utilizationPercent: number } {
+  if (
+    !account.id ||
+    !Number.isSafeInteger(account.activeRuns) ||
+    account.activeRuns < 0 ||
+    !Number.isSafeInteger(account.concurrencyLimit) ||
+    account.concurrencyLimit < 1
+  )
+    return { excluded: 'invalid' };
+  if (!account.enabled) return { excluded: 'disabled' };
+  if (account.authentication !== 'subscription') return { excluded: 'not-subscription' };
+  if (
+    request.organizationId !== undefined &&
+    !account.organizationIds.includes(request.organizationId)
+  )
+    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 (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 fractions: number[] = [];
+  for (const window of account.windows) {
+    if (
+      window.usedPercent === null ||
+      !Number.isFinite(window.usedPercent) ||
+      window.usedPercent < 0 ||
+      window.usedPercent > 100 ||
+      !Number.isFinite(window.reservedPercent) ||
+      window.reservedPercent < 0
+    )
+      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) ||
+      window.observedAt > request.now ||
+      request.now - window.observedAt > request.maximumObservationAgeMs ||
+      (window.resetsAt !== Number.POSITIVE_INFINITY &&
+        (!Number.isFinite(window.resetsAt) || window.resetsAt <= request.now))
+    )
+      return { excluded: 'stale-observation' };
+    fractions.push(window.usedPercent + window.reservedPercent);
+  }
+  if (fractions.some((p) => p >= 100)) return { excluded: 'exhausted' };
+  return { utilizationPercent: Math.max(...fractions) };
+}
+
+/** Rank eligible candidates deterministically (ties broken by id). */
+export function rankCandidates(
+  request: CandidateRequest,
+  accounts: readonly SubscriptionCandidate[],
+): { candidates: RankedCandidate[]; excluded: Record<string, ExclusionReason> } {
+  if (
+    !Number.isFinite(request.now) ||
+    !Number.isFinite(request.maximumObservationAgeMs) ||
+    request.maximumObservationAgeMs <= 0
+  )
+    throw Error('Invalid observation policy');
+  if (request.mode === '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 excluded: Record<string, ExclusionReason> = {};
+  const ranked = accounts.flatMap((account) => {
+    const assessed = assessCandidate(request, account);
+    if ('excluded' in assessed) {
+      excluded[account.id] = assessed.excluded;
+      return [];
+    }
+    const { utilizationPercent } = assessed;
+    return [
+      {
+        accountId: account.id,
+        utilizationPercent,
+        quartile: Math.floor(utilizationPercent / 25),
+        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 };
+}
+
+/** The draft's repository-scoped entry point: resolve ownership, then rank. */
+export function rankSubscriptionAccounts(
+  request: RoutingRequest,
+  routes: readonly RepositoryRoute[],
+  accounts: readonly SubscriptionCandidate[],
+) {
+  if (
+    !Number.isFinite(request.now) ||
+    !Number.isFinite(request.maximumObservationAgeMs) ||
+    request.maximumObservationAgeMs <= 0
+  )
+    throw Error('Invalid observation policy');
+  const repository = repositoryIdentity(request.repository);
+  const matches = routes.filter((r) => repositoryIdentity(r.repository) === repository);
+  if (matches.length !== 1) throw Error('Repository ownership is missing or ambiguous');
+  const route = matches[0]!;
+  if (!route.organizationId || !route.preferredAccountId)
+    throw Error('Incomplete repository routing rule');
+  if (request.organizationId && request.organizationId !== route.organizationId)
+    throw Error('Explicit organization conflicts with repository ownership');
+  const { candidates } = rankCandidates(
+    {
+      organizationId: route.organizationId,
+      preferredId: route.preferredAccountId,
+      runtime: request.runtime,
+      model: request.model,
+      effort: request.effort,
+      now: request.now,
+      maximumObservationAgeMs: request.maximumObservationAgeMs,
+      mode: request.mode,
+    },
+    accounts,
+  );
+  return {
+    repository,
+    organizationId: route.organizationId,
+    model: request.model,
+    effort: request.effort,
+    mode: request.mode ?? 'quartile-balanced',
+    candidates,
+  };
+}