page-agent/packages/llms

@page-agent/llms

LLM client with a reflection-before-action mental model for page-agent.

Why This Package Exists

The LLM module and the agent logic are inherently coupled. This package exists not to decouple them, but to define the interface contract between the LLM and the agent.

The core abstraction is the MacroToolInput — a structured output format that forces the model to reflect before acting.

The Reflection-Before-Action Model

Every tool call must first output its reasoning state before the actual action:

interface MacroToolInput {
  // Reflection (mandatory before any action)
  evaluation_previous_goal?: string  // How well did the previous action work?
  memory?: string                     // Key information to remember
  next_goal?: string                  // What to accomplish next

  // Action (the actual operation)
  action: Record<string, any>
}

This design ensures that:

1. The model evaluates its previous action before deciding the next step
2. Working memory is explicitly maintained across conversation turns
3. Goals are clearly stated, making the agent's reasoning transparent and debuggable

Key Components

Export	Description
LLM	Main LLM client class with retry logic
MacroToolInput	The reflection-before-action input schema
AgentBrain	Agent's thinking state (eval, memory, goal)
LLMConfig	Configuration for LLM connection
parseLLMConfig	Parse and apply defaults to config