Interface: LoopBuilder<TIn, TOut, THandle, TActStepId>

Defined in: builders/loop-builder.ts:23

Fluent builder for an iterative action-and-evaluation refinement loop (P.loop(id)).

Pairs a write-capable .act(stepId, actor) agent with a read-only adversarial .evaluate(stepId, evaluator, options) agent and enforces .returnOutputFrom(actStepId).

Extends

• AstBuilder<LoopNode<TIn, TOut, THandle, TActStepId>>

Type Parameters

Type Parameter	Default type	Description
TIn	unknown	Validated loop input payload type.
TOut	unknown	Validated loop output payload type.
THandle	unknown	Runtime handle type of the active isolation scope.
TActStepId extends string	string	Literal string type of the action step ID constrained by .returnOutputFrom(actStepId).

Methods

act()

act<TNewActStepId, TActIn, TActOut, TActHandle>(stepId, actor): LoopBuilder<TActIn, TActOut, [unknown] extends [THandle] ? TActHandle : THandle, TNewActStepId>;

Defined in: builders/loop-builder.ts:129

Binds the write-capable action step executed on each loop iteration.

Narrows TActStepId to TNewActStepId, updates roleKey to actor.roleKey, sets inputSchema and outputSchema from actor, inherits extractPartitions from actor when not already configured via .partitions(), and defaults returnOutputFromStepId to stepId.

Type Parameters

Type Parameter	Default type	Description
TNewActStepId extends string	-	Literal step identifier string of the action step.
TActIn	TIn	Validated action step input payload type.
TActOut	TOut	Validated action step output payload type.
TActHandle	THandle	Runtime handle type of the action agent's isolation scope.

Parameters

Parameter	Type	Description
stepId	TNewActStepId	Action step identifier.
actor	MaybeBuilder<AgentNode<TActIn, TActOut, TActHandle>>	Action agent AST node or builder.

Returns

LoopBuilder<TActIn, TActOut, [unknown] extends [THandle] ? TActHandle : THandle, TNewActStepId>

New immutable loop builder narrowed to TNewActStepId.

---

distillLessonsInto()

distillLessonsInto(lessons): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:108

Binds an optional LessonsNode receiving contrastive loop recovery pairs and active evaluator violations.

Triggers contrastive distillation when a rejected iteration is followed by an accepted iteration.

Parameters

Parameter	Type	Description
lessons	MaybeBuilder<LessonsNode<unknown>>	Target LessonsNode or builder.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

evaluate()

evaluate<TEvalIn, TEvalOut, TReceipt>(
   stepId, 
   evaluator, 
   options
): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:159

Binds the read-only adversarial evaluation step executed after .act() passes beforeStop.

Evaluates (loopInput, actOutput, scopeReceipt) and either accepts the output or injects feedback.

Type Parameters

Type Parameter	Default type	Description
TEvalIn	-	Evaluator agent input payload type.
TEvalOut	-	Evaluator agent output payload type.
TReceipt	ExtractEvalScopeReceipt<TEvalIn>	Inspected scope receipt type.

Parameters

Parameter	Type	Description
stepId	string	Evaluation step identifier.
evaluator	MaybeBuilder<AgentNode<TEvalIn, TEvalOut, THandle>>	Read-only evaluator agent.
options	LoopEvaluateOptions<TIn, TOut, TEvalIn, TEvalOut, TReceipt>	Input mapper, acceptance predicate, and feedback formatter.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

input()

input<TNewIn>(schema): LoopBuilder<TNewIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:45

Binds the Zod validation schema for the loop's input payload.

Preserves all previously configured extractPartitions, actStep, and evaluateStep bindings.

Type Parameters

Type Parameter	Description
TNewIn	Validated loop input payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewIn>	Zod schema validating loop input.

Returns

LoopBuilder<TNewIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

maxIterations()

maxIterations(count): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:86

Sets the maximum number of .act() -> .evaluate() iterations before failing the loop.

Throws immediately at builder call time if count < 1 or is not an integer.

Parameters

Parameter	Type	Description
count	number	Positive integer iteration limit.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

output()

output<TNewOut>(schema): LoopBuilder<TIn, TNewOut, THandle, TActStepId>;

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

Binds the Zod validation schema for the loop's output payload.

Preserves all previously configured actStep and evaluateStep bindings.

Type Parameters

Type Parameter	Description
TNewOut	Validated loop output payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewOut>	Zod schema validating loop output.

Returns

LoopBuilder<TIn, TNewOut, THandle, TActStepId>

New immutable loop builder.

---

partitions()

partitions(extractor): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:73

Binds an optional synchronous partition extractor mapping TIn to active partition IDs.

Populates ResolutionContext.activePartitions across iterations of the loop.

Parameters

Parameter	Type	Description
extractor	(input) => readonly string[]	Partition ID extractor callback.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

preserveActorSession()

preserveActorSession(preserve): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:97

Configures whether rejected iterations resume the .act() actor's existing conversation transcript.

Defaults to true so evaluator rejection feedback is appended in-place onto the .act() session.

Parameters

Parameter	Type	Description
preserve	boolean	True to append evaluator feedback onto the existing .act() session.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

returnOutputFrom()

returnOutputFrom(actStepId): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:174

Constrains and records the action step ID from which the loop projects its final accepted output.

Throws immediately if actStepId does not match the configured .act(stepId, ...) identifier.

Parameters

Parameter	Type	Description
actStepId	TActStepId	Literal action step ID matching .act(stepId, ...).

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

New immutable loop builder.

---

toAST()

toAST(): LoopNode;

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

LoopNode

Deeply frozen passive AST node.

Inherited from

AstBuilder.toAST

---

withPolicy()

withPolicy(newPolicy): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:185

Clones the loop with newPolicy applied to the inner .act() actor while preserving .onInterrupt() handlers and .evaluate()'s policy.

Throws if called before .act(stepId, actor) has been configured.

Parameters

Parameter	Type	Description
newPolicy	MaybeBuilder<PolicyNode<THandle>>	Replacement policy for the .act() actor.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

Cloned immutable loop builder.

---

withTools()

withTools(...extraTools): LoopBuilder<TIn, TOut, THandle, TActStepId>;

Defined in: builders/loop-builder.ts:198

Clones the loop with additional tools mounted on the inner .act() actor and updates roleKey canonically.

Throws if called before .act(stepId, actor) has been configured.

Parameters

Parameter	Type	Description
...extraTools	readonly ( | MaybeBuilder<BuiltInToolASTNode<THandle>> | readonly MaybeBuilder<BuiltInToolASTNode<THandle>>[])[]	Additional tools for the .act() actor.

Returns

LoopBuilder<TIn, TOut, THandle, TActStepId>

Cloned immutable loop builder.

Properties

Property	Modifier	Type	Description	Defined in
id	readonly	string	Unique identifier of the loop definition.	builders/loop-builder.ts:30
roleKey	readonly	string	Canonical role key of the inner .act() actor (actStep.actor.roleKey).	builders/loop-builder.ts:32