graphlit-client/dist/helpers/turn-evaluator.d.ts

Graphlit API Client for TypeScript

import type { TurnResult, ContextWindowUsage } from "../types/agent.js";
import type { ExtractCompletion, ToolDefinitionInput } from "../generated/graphql-types.js";
/** Budget configuration for the multi-turn harness. */
export interface BudgetConfig {
    maxTurns: number;
    maxWallClockMs: number;
    maxToolCalls: number;
    windDownTurns: number;
    initialPrompt: string;
}
/** Input for buildTurnInstructions. */
export interface TurnInstructionConfig {
    turnNumber: number;
    turnsRemaining: number;
    isWindingDown: boolean;
    isStuckIntervention?: string;
    contextWindowPercent?: number;
    originalTaskSummary?: string;
    needsSummarization?: boolean;
}
/** Signature for the extractText callback used by classifyComplexity. */
export type ExtractFn = (prompt: string, text: string, tools: ToolDefinitionInput[]) => Promise<Array<ExtractCompletion | null> | null | undefined>;
/**
 * Manages budget enforcement, wind-down protocol, instruction building,
 * and adaptive budget adjustment for the multi-turn agent harness.
 */
export declare class TurnEvaluator {
    private maxTurns;
    private maxWallClockMs;
    private maxToolCalls;
    private readonly windDownTurns;
    private readonly initialPrompt;
    private extensionGranted;
    constructor(config: BudgetConfig);
    /**
     * Uses an LLM to classify the complexity of the initial prompt and returns
     * a budget multiplier (1.0–3.0). Falls back to 1.0 on any error.
     */
    classifyComplexity(prompt: string, extractFn: ExtractFn): Promise<{
        multiplier: number;
        reason: string;
    }>;
    /** Apply a multiplier to all budget limits. */
    adjustBudget(multiplier: number): void;
    /** Current adjusted maxTurns. */
    get adjustedMaxTurns(): number;
    /** Current adjusted maxWallClockMs. */
    get adjustedMaxWallClockMs(): number;
    /** Current adjusted maxToolCalls. */
    get adjustedMaxToolCalls(): number;
    /** Returns true when the agent should begin winding down. */
    shouldWindDown(turn: number, elapsedMs: number, totalToolCalls: number, contextWindow?: ContextWindowUsage): boolean;
    /**
     * One-time budget extension if the agent is making steady progress.
     * Grants windDownTurns * 2 additional turns.
     */
    shouldGrantExtension(turnResults: TurnResult[], contextPercent?: number): {
        grant: boolean;
        extraTurns: number;
    };
    /**
     * Build the `instructions` parameter for a turn. Returns undefined for
     * normal continuation turns (enables bare fast-path).
     */
    buildTurnInstructions(config: TurnInstructionConfig): string | undefined;
    /** Returns true if any hard budget limit has been exhausted. */
    isBudgetExhausted(turn: number, elapsedMs: number, totalToolCalls: number): boolean;
}