@directive-run/ai 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { G as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, S as SchemaValidator, T as ToolCallGuardrailData, A as AgentLike, M as Message, a as AdapterHooks, b as AgentRunner, c as ApprovalState, d as AgentState, R as RunOptions, e as RunResult, D as DebugEvent, B as BreakpointState, f as GoalResult } from './types-D5veI9su.cjs';
 export { g as AgentCircuitBreakerConfig, h as AgentCompleteEvent, i as AgentErrorEvent, j as AgentHealthState, k as AgentRetryConfig, l as AgentRetryEvent, m as AgentSelectionStrategy, n as AgentStartEvent, o as ApprovalRequest, p as ApprovalRequestEvent, q as ApprovalResponseEvent, r as BreakpointConfig, s as BreakpointContext, t as BreakpointHitEvent, u as BreakpointModifications, v as BreakpointRequest, w as BreakpointResumedEvent, x as BreakpointState, y as BreakpointType, C as Checkpoint, z as CheckpointContext, E as CheckpointDiff, F as CheckpointLocalState, H as CheckpointProgress, J as CheckpointRestoreEvent, K as CheckpointSaveEvent, L as CheckpointStore, N as ConstraintEvaluateEvent, P as CrossAgentDerivationFn, Q as CrossAgentSnapshot, U as DagCheckpointState, V as DagExecutionContext, W as DagNode, X as DagNodeStatus, Y as DagNodeUpdateEvent, Z as DagPattern, _ as DebateCheckpointState, $ as DebateRoundEvent, a0 as DebugEventBase, a1 as DebugEventType, a2 as DerivationUpdateEvent, a3 as GoalCheckpointConfig, a4 as GoalCheckpointState, a5 as GoalMetrics, a6 as GoalNode, a7 as GoalPattern, a8 as GoalStepMetrics, a9 as GuardrailCheckEvent, aa as GuardrailContext, ab as GuardrailError, ac as GuardrailErrorCode, ad as GuardrailResult, ae as GuardrailRetryConfig, af as GuardrailsConfig, ag as HandoffCompleteEvent, ah as HandoffStartEvent, ai as HealthMonitorConfig, aj as InMemoryCheckpointStore, ak as InMemoryCheckpointStoreOptions, al as MAX_BREAKPOINT_HISTORY, am as MultiAgentBreakpointType, an as MultiAgentCheckpointLocalState, ao as MultiAgentLifecycleHooks, ap as MultiAgentSelfHealingConfig, aq as NamedGuardrail, ar as OrchestratorConstraint, as as OrchestratorDebugConfig, at as OrchestratorLifecycleHooks, au as OrchestratorResolver, av as OrchestratorResolverContext, aw as OrchestratorState, ax as PatternCheckpointBase, ay as PatternCheckpointConfig, az as PatternCheckpointState, aA as PatternCompleteEvent, aB as PatternStartEvent, aC as RaceCancelledEvent, aD as RaceStartEvent, aE as RaceWinnerEvent, aF as ReflectCheckpointState, aG as ReflectionIterationEvent, aH as RejectedRequest, aI as RelaxationContext, aJ as RelaxationRecord, aK as RelaxationStrategy, aL as RelaxationTier, aM as RerouteDebugEvent, aN as RerouteEvent, aO as ResolverCompleteEvent, aP as ResolverErrorEvent, aQ as ResolverStartEvent, aR as SchemaValidationResult, aS as Scratchpad, aT as ScratchpadUpdateEvent, aU as SelfHealingConfig, aV as SequentialCheckpointState, aW as SingleAgentCheckpointLocalState, aX as StreamingCallbackRunner, aY as SupervisorCheckpointState, aZ as TaskCompleteEvent, a_ as TaskErrorEvent, a$ as TaskProgressEvent, b0 as TaskStartEvent, b1 as TokenUsage, b2 as ToolCall, b3 as createBreakpointId, b4 as createCheckpointId, b5 as createInitialBreakpointState, b6 as isGuardrailError, b7 as matchBreakpoint, b8 as validateCheckpoint } from './types-D5veI9su.cjs';
-import { E as ExecutionPattern, S as SerializedPattern, A as AgentHealthMetrics, D as DebugTimeline, H as HealthMonitor } from './multi-agent-orchestrator-YFs28JsF.cjs';
-export { a as AgentMemory, b as AgentMemoryConfig, c as AgentOrchestrator, d as AgentRegistration, e as AgentRegistry, B as BackpressureStrategy, f as DebateConfig, g as DebatePattern, h as DebateResult, i as DebugTimelineListener, j as DebugTimelineOptions, k as DoneChunk, l as ErrorChunk, G as GuardrailTriggeredChunk, m as HandoffRequest, n as HandoffResult, o as HealthCircuitState, M as MemoryManageResult, p as MemoryState, q as MemoryStrategy, r as MemoryStrategyConfig, s as MemoryStrategyResult, t as MergedTaggedStreamResult, u as MessageChunk, v as MessageSummarizer, w as MultiAgentOrchestrator, x as MultiAgentOrchestratorOptions, y as MultiAgentRunCallOptions, z as MultiAgentState, C as MultiplexedStreamChunk, F as MultiplexedStreamResult, O as OrchestratorOptions, I as OrchestratorStreamChunk, J as OrchestratorStreamResult, P as ParallelPattern, K as ProgressChunk, R as RacePattern, L as RaceResult, N as RaceSuccessEntry, Q as ReflectIterationRecord, T as ReflectPattern, U as ReflectionConfig, V as ReflectionContext, W as ReflectionEvaluation, X as ReflectionEvaluator, Y as ReflectionExhaustedError, Z as RunAgentRequirement, _ as RunCallOptions, $ as SafeParseResult, a0 as SafeParseable, a1 as Semaphore, a2 as SequentialPattern, a3 as SerializedDagNode, a4 as SerializedGoalNode, a5 as SpawnOnConditionOptions, a6 as SpawnPoolConfig, a7 as StreamChunk, a8 as StreamRunOptions, a9 as StreamRunner, aa as StreamingGuardrail, ab as StreamingGuardrailResult, ac as StreamingRunResult, ad as StructuredOutputConfig, ae as StructuredOutputError, af as SupervisorPattern, ag as TaskContext, ah as TaskRegistration, ai as TokenChunk, aj as ToolEndChunk, ak as ToolStartChunk, al as adaptOutputGuardrail, am as aggregateTokens, an as allReadyStrategy, ao as capabilityRoute, ap as collectOutputs, aq as collectTokens, ar as combineStreamingGuardrails, as as composePatterns, at as concatResults, au as costEfficientStrategy, av as createAgentMemory, aw as createAgentOrchestrator, ax as createDebugTimeline, ay as createDebugTimelinePlugin, az as createHealthMonitor, aA as createHybridStrategy, aB as createKeyPointsSummarizer, aC as createLLMSummarizer, aD as createLengthStreamingGuardrail, aE as createMultiAgentOrchestrator, aF as createPatternStreamingGuardrail, aG as createSlidingWindowStrategy, aH as createStreamingRunner, aI as createTokenBasedStrategy, aJ as createToxicityStreamingGuardrail, aK as createTruncationSummarizer, aL as dag, aM as debate, aN as derivedConstraint, aO as diffCheckpoints, aP as extractJsonFromOutput, aQ as filterStream, aR as findAgentsByCapability, aS as forkFromCheckpoint, aT as getCheckpointProgress, aU as getPatternStep, aV as goal, aW as highestImpactStrategy, aX as mapStream, aY as mergeTaggedStreams, aZ as parallel, a_ as patternFromJSON, a$ as patternToJSON, b0 as pickBestResult, b1 as race, b2 as reflect, b3 as runAgentRequirement, b4 as runDebate, b5 as selectAgent, b6 as sequential, b7 as spawnOnCondition, b8 as spawnPool, b9 as supervisor, ba as tapStream, bb as withReflection, bc as withStructuredOutput } from './multi-agent-orchestrator-YFs28JsF.cjs';
+import { E as ExecutionPattern, S as SerializedPattern, A as AgentHealthMetrics, D as DebugTimeline, H as HealthMonitor } from './multi-agent-orchestrator-CFOzWVNd.cjs';
+export { a as AgentMemory, b as AgentMemoryConfig, c as AgentOrchestrator, d as AgentRegistration, e as AgentRegistry, B as BackpressureStrategy, f as DebateConfig, g as DebatePattern, h as DebateResult, i as DebugTimelineListener, j as DebugTimelineOptions, k as DoneChunk, l as ErrorChunk, G as GuardrailTriggeredChunk, m as HandoffRequest, n as HandoffResult, o as HealthCircuitState, M as MemoryManageResult, p as MemoryState, q as MemoryStrategy, r as MemoryStrategyConfig, s as MemoryStrategyResult, t as MergedTaggedStreamResult, u as MessageChunk, v as MessageSummarizer, w as MultiAgentOrchestrator, x as MultiAgentOrchestratorOptions, y as MultiAgentRunCallOptions, z as MultiAgentState, C as MultiplexedStreamChunk, F as MultiplexedStreamResult, O as OrchestratorOptions, I as OrchestratorStreamChunk, J as OrchestratorStreamResult, P as ParallelPattern, K as ProgressChunk, R as RacePattern, L as RaceResult, N as RaceSuccessEntry, Q as ReflectIterationRecord, T as ReflectPattern, U as ReflectionConfig, V as ReflectionContext, W as ReflectionEvaluation, X as ReflectionEvaluator, Y as ReflectionExhaustedError, Z as RunAgentRequirement, _ as RunCallOptions, $ as SafeParseResult, a0 as SafeParseable, a1 as Semaphore, a2 as SequentialPattern, a3 as SerializedDagNode, a4 as SerializedGoalNode, a5 as SpawnOnConditionOptions, a6 as SpawnPoolConfig, a7 as StreamChunk, a8 as StreamRunOptions, a9 as StreamRunner, aa as StreamingGuardrail, ab as StreamingGuardrailResult, ac as StreamingRunResult, ad as StructuredOutputConfig, ae as StructuredOutputError, af as SupervisorPattern, ag as TaskContext, ah as TaskRegistration, ai as TokenChunk, aj as ToolEndChunk, ak as ToolStartChunk, al as adaptOutputGuardrail, am as aggregateTokens, an as allReadyStrategy, ao as capabilityRoute, ap as collectOutputs, aq as collectTokens, ar as combineStreamingGuardrails, as as composePatterns, at as concatResults, au as costEfficientStrategy, av as createAgentMemory, aw as createAgentOrchestrator, ax as createDebugTimeline, ay as createDebugTimelinePlugin, az as createHealthMonitor, aA as createHybridStrategy, aB as createKeyPointsSummarizer, aC as createLLMSummarizer, aD as createLengthStreamingGuardrail, aE as createMultiAgentOrchestrator, aF as createPatternStreamingGuardrail, aG as createSlidingWindowStrategy, aH as createStreamingRunner, aI as createTokenBasedStrategy, aJ as createToxicityStreamingGuardrail, aK as createTruncationSummarizer, aL as dag, aM as debate, aN as derivedConstraint, aO as diffCheckpoints, aP as extractJsonFromOutput, aQ as filterStream, aR as findAgentsByCapability, aS as forkFromCheckpoint, aT as getCheckpointProgress, aU as getPatternStep, aV as goal, aW as highestImpactStrategy, aX as mapStream, aY as mergeTaggedStreams, aZ as parallel, a_ as patternFromJSON, a$ as patternToJSON, b0 as pickBestResult, b1 as race, b2 as reflect, b3 as runAgentRequirement, b4 as runDebate, b5 as selectAgent, b6 as sequential, b7 as spawnOnCondition, b8 as spawnPool, b9 as supervisor, ba as tapStream, bb as withReflection, bc as withStructuredOutput } from './multi-agent-orchestrator-CFOzWVNd.cjs';
 export { AggregatedMetric, AlertConfig, AlertEvent, CircuitBreaker, CircuitBreakerConfig, CircuitBreakerOpenError, CircuitBreakerStats, CircuitState, DashboardData, MetricDataPoint, MetricType, OTLPExporter, OTLPExporterConfig, ObservabilityConfig, ObservabilityInstance, TraceSpan, createAgentMetrics, createCircuitBreaker, createOTLPExporter, createObservability } from '@directive-run/core/plugins';
 import { ModuleSchema, Plugin } from '@directive-run/core';
 import { E as Embedding, a as EmbedderFn } from './semantic-cache-F0psCRuz.cjs';
@@ -12,7 +12,12 @@ export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as Cac
  */
 
 /**
- * Create a PII detection guardrail.
+ * Create a PII detection guardrail that scans input text for personally identifiable
+ * information. Blocks input when PII is detected, or optionally redacts matches and
+ * passes the sanitized text through.
+ *
+ * @param options - Configuration for PII detection: `patterns` sets the RegExp list (defaults to SSN, credit card, email), `redact` replaces matches instead of blocking, `redactReplacement` sets the replacement string (defaults to `"[REDACTED]"`).
+ * @returns An input guardrail that blocks or redacts PII in user input.
  *
  * @example
  * ```typescript
@@ -24,6 +29,8 @@ export { B as BatchedEmbedder, C as CacheEntry, b as CacheLookupResult, c as Cac
  *   redact: true,
  * });
  * ```
+ *
+ * @public
  */
 declare function createPIIGuardrail(options: {
     patterns?: RegExp[];
@@ -31,7 +38,12 @@ declare function createPIIGuardrail(options: {
     redactReplacement?: string;
 }): GuardrailFn<InputGuardrailData>;
 /**
- * Create a content moderation guardrail.
+ * Create a content moderation guardrail that delegates to a user-supplied check function.
+ * Works on both input and output data — the guardrail extracts the text content
+ * automatically and passes it to {@link options.checkFn}.
+ *
+ * @param options - Configuration for content moderation: `checkFn` returns `true` when content should be flagged (supports async), `message` sets the rejection reason (defaults to `"Content flagged by moderation"`).
+ * @returns A guardrail that blocks content flagged by the check function.
  *
  * @example
  * ```typescript
@@ -42,6 +54,8 @@ declare function createPIIGuardrail(options: {
  *   },
  * });
  * ```
+ *
+ * @public
  */
 declare function createModerationGuardrail(options: {
     checkFn: (text: string) => boolean | Promise<boolean>;
@@ -52,15 +66,44 @@ interface RateLimitGuardrail extends GuardrailFn<InputGuardrailData> {
     reset(): void;
 }
 /**
- * Create a rate limit guardrail based on token usage.
- * Returns a guardrail function with an additional `reset()` method for testing.
+ * Create a rate limit guardrail that tracks token and request counts over a sliding
+ * one-minute window. Returns a {@link RateLimitGuardrail} — a guardrail function with
+ * an additional `reset()` method for testing.
+ *
+ * @param options - Configuration for rate limiting: `maxTokensPerMinute` caps tokens in the sliding window (defaults to `100000`), `maxRequestsPerMinute` caps requests (defaults to `60`).
+ * @returns A rate limit guardrail with an attached `reset()` method.
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimitGuardrail({
+ *   maxTokensPerMinute: 50000,
+ *   maxRequestsPerMinute: 30,
+ * });
+ * ```
+ *
+ * @public
  */
 declare function createRateLimitGuardrail(options: {
     maxTokensPerMinute?: number;
     maxRequestsPerMinute?: number;
 }): RateLimitGuardrail;
 /**
- * Create a tool allowlist/denylist guardrail.
+ * Create a tool-call guardrail that restricts which tools an agent may invoke.
+ * Supports allowlist mode, denylist mode, or both — when both are provided, a tool
+ * must appear in the allowlist and not appear in the denylist.
+ *
+ * @param options - Configuration for tool filtering: `allowlist` sets permitted tool names, `denylist` sets blocked tool names, `caseSensitive` controls case matching (defaults to `false`).
+ * @returns A tool-call guardrail that enforces the allowlist/denylist rules.
+ *
+ * @example
+ * ```typescript
+ * const toolGuardrail = createToolGuardrail({
+ *   allowlist: ["search", "calculate"],
+ *   denylist: ["delete_account"],
+ * });
+ * ```
+ *
+ * @public
  */
 declare function createToolGuardrail(options: {
     allowlist?: string[];
@@ -69,14 +112,48 @@ declare function createToolGuardrail(options: {
     caseSensitive?: boolean;
 }): GuardrailFn<ToolCallGuardrailData>;
 /**
- * Create an output schema validation guardrail.
+ * Create an output guardrail that validates agent output against a schema using
+ * a user-supplied {@link SchemaValidator}. Compatible with any validation library
+ * (Zod, Valibot, ArkType, etc.) via the adapter pattern.
+ *
+ * @param options - Configuration for schema validation: `validate` checks the output against the expected schema, `errorPrefix` is prepended to error messages (defaults to `"Output schema validation failed"`).
+ * @returns An output guardrail that rejects output failing schema validation.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const schemaGuardrail = createOutputSchemaGuardrail({
+ *   validate: (value) => {
+ *     const result = z.object({ answer: z.string() }).safeParse(value);
+ *     return { valid: result.success, errors: result.error?.issues.map(i => i.message) };
+ *   },
+ * });
+ * ```
+ *
+ * @public
  */
 declare function createOutputSchemaGuardrail<T = unknown>(options: {
     validate: SchemaValidator<T>;
     errorPrefix?: string;
 }): GuardrailFn<OutputGuardrailData>;
 /**
- * Create a simple type check guardrail for common output types.
+ * Create an output guardrail that performs lightweight runtime type checks without
+ * requiring a schema library. Supports `"string"`, `"number"`, `"boolean"`, `"object"`,
+ * and `"array"` with optional size and field constraints.
+ *
+ * @param options - Configuration for type checking: `type` sets the expected JS type, `requiredFields` lists object keys that must exist, `minLength`/`maxLength` constrain array size, `minStringLength`/`maxStringLength` constrain string length.
+ * @returns An output guardrail that rejects output not matching the expected type or constraints.
+ *
+ * @example
+ * ```typescript
+ * const typeGuardrail = createOutputTypeGuardrail({
+ *   type: "object",
+ *   requiredFields: ["id", "name"],
+ * });
+ * ```
+ *
+ * @public
  */
 declare function createOutputTypeGuardrail(options: {
     type: "string" | "number" | "boolean" | "object" | "array";
@@ -87,14 +164,21 @@ declare function createOutputTypeGuardrail(options: {
     maxStringLength?: number;
 }): GuardrailFn<OutputGuardrailData>;
 /**
- * Create a length guardrail that limits output size.
+ * Create an output guardrail that enforces maximum length constraints on agent output,
+ * measured in characters or estimated tokens.
+ *
+ * @param options - Configuration for length limits: `maxCharacters` caps character count, `maxTokens` caps estimated token count, `estimateTokens` provides a custom token estimator (defaults to `Math.ceil(text.length / 4)`).
+ * @returns An output guardrail that rejects output exceeding the configured length limits.
  *
  * @example
  * ```typescript
  * const lengthGuardrail = createLengthGuardrail({
  *   maxCharacters: 5000,
+ *   maxTokens: 1200,
  * });
  * ```
+ *
+ * @public
  */
 declare function createLengthGuardrail(options: {
     /** Maximum characters in output */
@@ -105,7 +189,15 @@ declare function createLengthGuardrail(options: {
     estimateTokens?: (text: string) => number;
 }): GuardrailFn<OutputGuardrailData>;
 /**
- * Create a content filter guardrail that blocks output matching specific patterns.
+ * Create an output guardrail that blocks content matching any of the provided patterns.
+ * String patterns are escaped and compiled to RegExp; RegExp patterns are used as-is.
+ *
+ * @remarks
+ * A warning is logged when `blockedPatterns` is empty, since an empty list means no
+ * content will ever be filtered.
+ *
+ * @param options - Configuration for content filtering: `blockedPatterns` lists strings or RegExps to match against output, `caseSensitive` controls case matching for string patterns (defaults to `false`).
+ * @returns An output guardrail that rejects output containing any blocked pattern.
  *
  * @example
  * ```typescript
@@ -117,6 +209,8 @@ declare function createLengthGuardrail(options: {
  *   ],
  * });
  * ```
+ *
+ * @public
  */
 declare function createContentFilterGuardrail(options: {
     /** Patterns to block — strings or RegExp */
@@ -129,21 +223,39 @@ declare function createContentFilterGuardrail(options: {
  * Agent utilities — createRunner, estimateCost, state queries, URL validation.
  */
 
-/** Check if agent is currently running. */
+/**
+ * Check whether an agent is currently executing a run.
+ *
+ * @param state - The current {@link AgentState} to inspect.
+ * @returns `true` when the agent status is `"running"`.
+ */
 declare function isAgentRunning(state: AgentState): boolean;
-/** Check if there are pending approvals. */
+/**
+ * Check whether there are tool-call approvals waiting for user confirmation.
+ *
+ * @param state - The current {@link ApprovalState} to inspect.
+ * @returns `true` when one or more approvals are pending.
+ */
 declare function hasPendingApprovals(state: ApprovalState): boolean;
 /**
- * Get total cost estimate based on token usage.
+ * Estimate the dollar cost of an agent run based on total token usage.
  *
- * @param tokenUsage - Total token count
- * @param ratePerMillionTokens - Cost per million tokens (required, no default to avoid stale pricing)
- * @returns Estimated cost in dollars
+ * @remarks
+ * No default rate is provided — callers must supply the current per-million-token
+ * price to avoid silently using stale pricing.
+ *
+ * @param tokenUsage - Total number of tokens consumed (input + output).
+ * @param ratePerMillionTokens - Cost in dollars per one million tokens.
+ * @returns Estimated cost in dollars.
  */
 declare function estimateCost(tokenUsage: number, ratePerMillionTokens: number): number;
 /**
- * Validate that a baseURL uses http or https.
- * Throws immediately at adapter creation time (not at call time) to catch config errors early.
+ * Validate that a base URL uses the `http:` or `https:` protocol.
+ * Throws immediately at adapter creation time (not at call time) to surface
+ * configuration errors before any LLM requests are made.
+ *
+ * @param baseURL - The base URL string to validate.
+ * @throws When the URL is malformed or uses a protocol other than `http:` or `https:`.
  */
 declare function validateBaseURL(baseURL: string): void;
 /** Parsed response from an LLM provider */
@@ -168,14 +280,21 @@ interface CreateRunnerOptions {
     hooks?: AdapterHooks;
 }
 /**
- * Create an AgentRunner from buildRequest/parseResponse helpers.
- * Reduces ~50 lines of fetch boilerplate to ~20 lines of configuration.
+ * Create an {@link AgentRunner} from `buildRequest`/`parseResponse` helpers, reducing
+ * ~50 lines of fetch boilerplate to ~20 lines of configuration.
  *
+ * @remarks
  * Supports lifecycle hooks for observability:
  * - `onBeforeCall` fires before each API request
  * - `onAfterCall` fires after a successful response (includes token breakdown)
  * - `onError` fires when the request fails
  *
+ * Output parsing defaults to `JSON.parse` with a string fallback. Supply a custom
+ * `parseOutput` to override (e.g. for structured output schemas).
+ *
+ * @param options - Configuration for the runner, including request building, response parsing, and hooks.
+ * @returns An {@link AgentRunner} function that performs LLM calls via fetch.
+ *
  * @example
  * ```typescript
  * const runClaude = createRunner({
@@ -209,6 +328,8 @@ interface CreateRunnerOptions {
  *   },
  * });
  * ```
+ *
+ * @public
  */
 declare function createRunner(options: CreateRunnerOptions): AgentRunner;
 
@@ -281,7 +402,7 @@ interface MermaidOptions {
  * //   fetch[fetcher] --> report[reporter]
  * ```
  *
- * @throws {Error} If pattern type is not one of the 8 known types.
+ * @throws If pattern type is not one of the 8 known types.
  */
 declare function patternToMermaid(pattern: ExecutionPattern<unknown> | SerializedPattern, options?: MermaidOptions): string;
 
@@ -3634,9 +3755,12 @@ interface EvalCostOptions {
 /**
  * Evaluate cost efficiency — scores based on token usage relative to a budget.
  *
- * Score = 1.0 when tokens <= maxTokensPerRun * 0.5
- * Score = 0.0 when tokens >= maxTokensPerRun * 2
+ * Score = 1.0 when tokens \<= maxTokensPerRun * 0.5,
+ * Score = 0.0 when tokens \>= maxTokensPerRun * 2.
  * Linear interpolation between.
+ *
+ * @param options - Cost evaluation options including `maxTokensPerRun`.
+ * @returns An eval criterion that scores token usage against the budget.
  */
 declare function evalCost(options: EvalCostOptions): EvalCriterion;
 /** Options for latency evaluation */
@@ -3647,9 +3771,12 @@ interface EvalLatencyOptions {
 /**
  * Evaluate latency — scores based on agent run duration.
  *
- * Score = 1.0 when duration <= maxMs * 0.5
- * Score = 0.0 when duration >= maxMs * 2
+ * Score = 1.0 when duration \<= maxMs * 0.5,
+ * Score = 0.0 when duration \>= maxMs * 2.
  * Linear interpolation between.
+ *
+ * @param options - Latency evaluation options including `maxMs`.
+ * @returns An eval criterion that scores run duration against the limit.
  */
 declare function evalLatency(options: EvalLatencyOptions): EvalCriterion;
 /** Options for output length evaluation */
@@ -3710,6 +3837,12 @@ interface EvalJudgeOptions {
     /** Timeout for the judge call in ms. Default: 30_000 */
     timeoutMs?: number;
 }
+/**
+ * Evaluate output quality by delegating to a judge agent that scores from 0.0 to 1.0.
+ *
+ * @param options - Judge evaluation options including `runner`, `judge` agent, and optional `promptTemplate`.
+ * @returns An eval criterion that runs a judge agent and returns its score.
+ */
 declare function evalJudge(options: EvalJudgeOptions): EvalCriterion;
 /**
  * Evaluate exact or substring match against expected output.
@@ -3720,6 +3853,12 @@ interface EvalMatchOptions {
     /** Case-insensitive matching. Default: true */
     caseInsensitive?: boolean;
 }
+/**
+ * Evaluate exact or substring match against expected output.
+ *
+ * @param options - Match evaluation options including `mode` and `caseInsensitive`.
+ * @returns An eval criterion that checks output against the expected value.
+ */
 declare function evalMatch(options?: EvalMatchOptions): EvalCriterion;
 /** Options for LLM-based semantic evaluation criteria */
 interface EvalSemanticOptions {