Built-in Middleware Catalog

function humanInTheLoopMiddleware(
  config: HumanInTheLoopMiddlewareConfig
): AgentMiddleware;

interface HumanInTheLoopMiddlewareConfig {
  interruptOn?: InterruptOnConfig;
  reviewConfig?: ReviewConfig;
}

type InterruptOnConfig =
  | "tools"
  | "tool_results"
  | ((state: State, toolCalls?: ToolCall[]) => boolean);

interface ReviewConfig {
  descriptionFactory?: DescriptionFactory;
}

type DescriptionFactory = (
  action: Action,
  state: State
) => string | Promise<string>;

function summarizationMiddleware(
  config: SummarizationMiddlewareConfig
): AgentMiddleware;

interface SummarizationMiddlewareConfig {
  model?: string | ChatModel;
  threshold?: number; // Token threshold to trigger summarization
  tokenCounter?: TokenCounter; // Custom token counting function
  systemPrompt?: string; // Custom summarization prompt
}

type TokenCounter = (messages: BaseMessage[]) => number | Promise<number>;

function dynamicSystemPromptMiddleware(
  config: DynamicSystemPromptMiddlewareConfig
): AgentMiddleware;

interface DynamicSystemPromptMiddlewareConfig {
  promptFactory: (state: State, context: any) => string | Promise<string>;
}

function llmToolSelectorMiddleware(
  config: LLMToolSelectorConfig
): AgentMiddleware;

interface LLMToolSelectorConfig {
  model?: string | ChatModel;
  maxTools?: number; // Maximum number of tools to select
  systemPrompt?: string; // Custom selection prompt
}

function piiMiddleware(
  config: PIIMiddlewareConfig
): AgentMiddleware;

interface PIIMiddlewareConfig {
  detectors?: PIIDetector[]; // Custom PII detectors
  builtInTypes?: BuiltInPIIType[]; // Built-in detector types to use
  strategy?: PIIStrategy; // How to handle detected PII
  redactionRules?: RedactionRuleConfig[]; // Custom redaction rules
}

type BuiltInPIIType =
  | "email"
  | "credit_card"
  | "ip"
  | "mac_address"
  | "url";

type PIIStrategy =
  | "redact" // Replace with [REDACTED]
  | "mask" // Replace with asterisks
  | "hash" // Replace with hash
  | "remove" // Remove from message
  | "block" // Block message entirely
  | ((match: PIIMatch) => string); // Custom strategy

interface PIIMatch {
  type: string;
  value: string;
  start: number;
  end: number;
}

type PIIDetector = (text: string) => PIIMatch[] | Promise<PIIMatch[]>;

interface RedactionRuleConfig {
  type: string;
  pattern?: RegExp;
  strategy?: PIIStrategy;
}

interface ResolvedRedactionRule {
  type: string;
  detector: PIIDetector;
  strategy: (match: PIIMatch) => string;
}

function detectEmail(text: string): PIIMatch[];
function detectCreditCard(text: string): PIIMatch[];
function detectIP(text: string): PIIMatch[];
function detectMacAddress(text: string): PIIMatch[];
function detectUrl(text: string): PIIMatch[];
function applyStrategy(match: PIIMatch, strategy: PIIStrategy): string;
function resolveRedactionRule(config: RedactionRuleConfig): ResolvedRedactionRule;

class PIIDetectionError extends Error {
  name: "PIIDetectionError";
  cause?: Error;
}

function piiRedactionMiddleware(
  config: PIIRedactionMiddlewareConfig
): AgentMiddleware;

interface PIIRedactionMiddlewareConfig {
  types?: BuiltInPIIType[]; // Types of PII to redact
  customPatterns?: Array<{
    name: string;
    pattern: RegExp;
  }>;
}

function contextEditingMiddleware(
  config: ContextEditingMiddlewareConfig
): AgentMiddleware;

interface ContextEditingMiddlewareConfig {
  edits: ContextEdit[];
}

interface ContextEdit {
  apply(state: State): State | Promise<State>;
}

class ClearToolUsesEdit implements ContextEdit {
  constructor(config: ClearToolUsesEditConfig);
  apply(state: State): State;
}

interface ClearToolUsesEditConfig {
  keepLast?: number; // Keep last N tool uses
}

function toolCallLimitMiddleware(
  config: ToolCallLimitConfig
): AgentMiddleware;

interface ToolCallLimitConfig {
  /**
   * Maximum tool calls per thread (at least one of threadLimit or runLimit must be specified)
   */
  threadLimit?: number;

  /**
   * Maximum tool calls per run (at least one of threadLimit or runLimit must be specified)
   */
  runLimit?: number;

  /**
   * Custom error message (optional)
   */
  errorMessage?: string;
}

class ToolCallLimitExceededError extends Error {
  name: "ToolCallLimitExceededError";
  limit: number;
  actualCalls: number;
}

function todoListMiddleware(
  options?: TodoListMiddlewareOptions
): AgentMiddleware;

interface TodoListMiddlewareOptions {
  systemPrompt?: string;
}

const TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT: string;

function modelCallLimitMiddleware(
  config: ModelCallLimitMiddlewareConfig
): AgentMiddleware;

interface ModelCallLimitMiddlewareConfig {
  maxCalls: number;
  errorMessage?: string;
}

function modelFallbackMiddleware(
  config?: ModelFallbackMiddlewareConfig
): AgentMiddleware;

interface ModelFallbackMiddlewareConfig {
  fallbackModels?: Array<string | ChatModel>;
  maxAttempts?: number;
}

function modelRetryMiddleware(
  config: ModelRetryMiddlewareConfig
): AgentMiddleware;

interface ModelRetryMiddlewareConfig {
  maxRetries?: number;
  initialDelay?: number; // milliseconds
  maxDelay?: number; // milliseconds
  backoffMultiplier?: number;
  retryableErrors?: Array<string | RegExp>; // Error patterns to retry
}

function toolRetryMiddleware(
  config: ToolRetryMiddlewareConfig
): AgentMiddleware;

interface ToolRetryMiddlewareConfig {
  maxRetries?: number;
  initialDelay?: number; // milliseconds
  maxDelay?: number; // milliseconds
  backoffMultiplier?: number;
  retryableErrors?: Array<string | RegExp>; // Error patterns to retry
  retryableTools?: string[]; // Tool names to retry (empty = all)
}

function toolEmulatorMiddleware(
  options: ToolEmulatorOptions
): AgentMiddleware;

interface ToolEmulatorOptions {
  emulations: Record<
    string, // Tool name
    (args: Record<string, any>) => string | Promise<string> // Emulation function
  >;
}

function openAIModerationMiddleware(
  options: OpenAIModerationMiddlewareOptions
): AgentMiddleware;

interface OpenAIModerationMiddlewareOptions {
  apiKey?: string; // OpenAI API key (defaults to OPENAI_API_KEY env var)
  moderateInput?: boolean; // Moderate user input
  moderateOutput?: boolean; // Moderate AI output
  throwOnFlagged?: boolean; // Throw error if content is flagged
  onFlagged?: (result: ModerationResult) => void | Promise<void>;
}

function anthropicPromptCachingMiddleware(
  config?: PromptCachingMiddlewareConfig
): AgentMiddleware;

interface PromptCachingMiddlewareConfig {
  cacheSystemPrompt?: boolean; // Cache system prompt
  cacheTools?: boolean; // Cache tool definitions
  minTokens?: number; // Minimum tokens to cache
}

/**
 * Approximate token counting utility for managing context windows
 * @param messages - Array of messages to count tokens for
 * @returns Approximate token count
 */
function countTokensApproximately(messages: BaseMessage[]): number;