Class: PoolManager

Defined in: runtime/pools/pool-manager.ts:25

Runtime capacity pool scheduler managing run-sticky account seat affinity, HTTP 429 rate-limit failover, and empirical 'escalate-on-retry' model selection (SPEC.md §3.2).

Ensures that all turns and child forks within a runId stick to the same account seat until rate-limited (429), while escalating model tiers on retries or low empirical completion rates.

Constructors

Constructor

new PoolManager(): PoolManager;

Returns

PoolManager

Methods

recordModelOutcome()

recordModelOutcome(
   poolId, 
   candidateId, 
   succeeded
): void;

Defined in: runtime/pools/pool-manager.ts:148

Records a completed or failed execution outcome for candidateId in poolId.

Updates sampleCount and successCount used by 'escalate-on-retry' (minSuccessRate / minSamples).

Parameters

Parameter	Type	Description
poolId	string	Identifier of the model pool.
candidateId	string	Identifier of the model candidate (model.modelId or model.alias).
succeeded	boolean	True when the model execution completed and passed evaluation.

Returns

void

---

recordRateLimit429()

recordRateLimit429(
   poolId, 
   candidateId, 
   resetAtMs
): void;

Defined in: runtime/pools/pool-manager.ts:128

Records an HTTP 429 rate-limit cooldown until resetAtMs for candidateId in poolId.

Automatically evicts any run-sticky seat affinity pointing to candidateId so subsequent turns fail over to another seat or fallbackItem.

Parameters

Parameter	Type	Description
poolId	string	Identifier of the capacity pool.
candidateId	string	Identifier of the rate-limited seat or model (seat.id or model.modelId).
resetAtMs	number	Epoch timestamp in milliseconds when the rate limit resets.

Returns

void

---

releaseRunSeats()

releaseRunSeats(runId): void;

Defined in: runtime/pools/pool-manager.ts:164

Releases all sticky seat bindings associated with runId across all managed pools.

Invoked when a flow run reaches a terminal exit state.

Parameters

Parameter	Type	Description
runId	string	Completed or terminated flow run identifier.

Returns

void

---

selectModel()

selectModel<TModel>(
   modelOrPool, 
   runId, 
   options?
): TModel;

Defined in: runtime/pools/pool-manager.ts:91

Resolves a single ModelASTNode or selects a candidate from a model PoolNode for runId.

Evaluates 'escalate-on-retry', standard, or custom pool strategies using retryAttempt and empirical completion rates tracked per model candidate.

Type Parameters

Type Parameter	Description
TModel extends ModelASTNode	Model AST node type.

Parameters

Parameter	Type	Default value	Description
modelOrPool	TModel | PoolNode<TModel>	undefined	Direct model node or model pool node.
runId	string	undefined	Active flow run identifier.
options?	| number | PoolModelSelectionOptions	0	Retry attempt number or selection options.

Returns

TModel

Selected model AST node.

---

selectSeat()

selectSeat<TSeat>(
   pool, 
   runId, 
   nowMs?
): TSeat;

Defined in: runtime/pools/pool-manager.ts:43

Selects an account seat from pool for runId, preserving run-sticky seat affinity when healthy.

Reuses the seat previously bound to runId unless that seat is currently rate-limited past nowMs, in which case it fails over via pool.strategy or pool.fallbackItem.

Type Parameters

Type Parameter	Description
TSeat extends AccountSeatASTNode	Account seat AST node type.

Parameters

Parameter	Type	Description
pool	PoolNode<TSeat>	Account seat pool AST node.
runId	string	Active flow run identifier for seat affinity.
nowMs?	number	Optional epoch timestamp in milliseconds (defaults to Date.now()).

Returns

TSeat

Selected account seat AST node.