Interface: PoolBuilder<TItem>

Defined in: builders/pool-builder.ts:17

Fluent builder for capacity and model pools (P.pool(id)).

Aggregates ordered candidate items (AccountSeatASTNode or ModelASTNode) with a selection strategy and optional fallback item.

Extends

• AstBuilder<PoolNode<TItem>>

Type Parameters

Type Parameter	Default type	Description
TItem extends ASTNode	ASTNode	Pool candidate AST node type.

Methods

fallback()

fallback(item): PoolBuilder<TItem>;

Defined in: builders/pool-builder.ts:90

Configures a fallback item used when all primary candidates in the pool are rate-limited or exhausted.

Extracts the underlying AST node from item and stores it on PoolNode.fallbackItem.

Parameters

Parameter	Type	Description
item	MaybeBuilder<TItem>	Fallback candidate AST node or builder.

Returns

PoolBuilder<TItem>

New immutable pool builder.

---

strategy()

Call Signature

strategy(configure): PoolBuilder<TItem>;

Defined in: builders/pool-builder.ts:46

Configures the pool's selection strategy via a fluent PoolStrategyBuilder configurator callback.

Enables fluent configuration of .escalateOnRetry(options?) on $.

Parameters

Parameter	Type	Description
configure	($) => MaybeBuilder<PoolStrategyNode<TItem>>	Fluent strategy configurator callback.

Returns

PoolBuilder<TItem>

New immutable pool builder.

Call Signature

strategy(selectFn): PoolBuilder<TItem>;

Defined in: builders/pool-builder.ts:60

Configures the pool's selection strategy via a custom synchronous candidate selector function.

Receives candidate states (readonly PoolCandidateState<TItem>[]) and PoolSelectionContext (containing attempt, runId, and stepExecId) to pick a candidate item.

Parameters

Parameter	Type	Description
selectFn	PoolSelectorFn<TItem>	Custom synchronous selector function.

Returns

PoolBuilder<TItem>

New immutable pool builder.

Call Signature

strategy(strategyInput): PoolBuilder<TItem>;

Defined in: builders/pool-builder.ts:71

Configures the pool's selection strategy via a built-in strategy name, custom selector function, strategy node, or fluent configurator callback.

Defaults to 'round-robin' when .strategy(...) is not explicitly called.

Parameters

Parameter	Type	Description
strategyInput	| "soonest-reset" | "round-robin" | "least-used" | PoolStrategyNode<TItem> | PoolSelectorFn<TItem> | (($) => MaybeBuilder<PoolStrategyNode<TItem>>)	Strategy specification.

Returns

PoolBuilder<TItem>

New immutable pool builder.

---

toAST()

toAST(): PoolNode;

Defined in: ast/ast-builder.ts:20

Compiles the current builder configuration into a deeply frozen passive AST node.

Validates required builder invariants at compilation time and returns an immutable plain-object AST representation containing zero execution methods.

Returns

PoolNode

Deeply frozen passive AST node.

Inherited from

AstBuilder.toAST

---

with()

with<TNextItem>(...items): PoolBuilder<TNextItem>;

Defined in: builders/pool-builder.ts:33

Populates the pool with candidate items (AccountSeatASTNode or ModelASTNode).

Replaces the candidate list and narrows the pool's item type parameter to TNextItem.

Type Parameters

Type Parameter	Description
TNextItem extends ASTNode	Candidate AST node type.

Parameters

Parameter	Type	Description
...items	readonly MaybeBuilder<TNextItem>[]	Candidate AST nodes or builders.

Returns

PoolBuilder<TNextItem>

New immutable pool builder typed to TNextItem.

Properties

Property	Modifier	Type	Description	Defined in
id	readonly	string	Unique identifier of the pool.	builders/pool-builder.ts:20