What Does the agent-runtime Package Do in Freebuff?

The @codebuff/agent-runtime package is the execution engine that powers Freebuff's LLM agents, handling everything from prompt construction and token budgeting to tool dispatching and output validation in a continuous loop.

The agent-runtime package in the Freebuff repository implements the core execution loop for autonomous LLM-driven workers. It serves as the bridge between static agent definitions and dynamic conversation management, enabling agents to process user instructions, invoke tools, and maintain state across multiple turns. According to the Freebuff source code, this package provides the plug-and-play runtime that can execute any agent definition while managing state across steps.

Core Architecture of the agent-runtime Package

The package orchestrates eight distinct phases in src/run-programmatic-step.ts, beginning with template initialization and ending with schema-validated output. It loads agent templates from src/templates/agent-registry.ts to build system prompts and prepares the initial state, including messageHistory, systemPrompt, and toolDefinitions. The runtime then enters a deterministic cycle: token budgeting, LLM streaming, tool execution, and context compaction, continuing until the agent signals completion via task_completed or end_turn tags.

Key Components

Template and Prompt Management

Agent behavior is defined by templates stored in src/templates/agent-registry.ts. The runtime constructs prompts by combining system instructions, optional step prompts, and user input. When a template defines a stepPrompt, runAgentStep appends it to the message history before each LLM call, allowing dynamic prompting strategies per step.

Token Budgeting and Context Pruning

Accurate token counting occurs in src/util/token-counter.ts, which handles both message content and Zod-derived JSON schemas using gpt-tokenizer. The recountContextTokens function ensures requests stay within model limits, while maybeCompactHistory in src/compact-history.ts summarizes old messages when conversations exceed the budget. This prevents context window overflows during long-running agent sessions.

Tool Execution Pipeline

The src/tools/tool-executor.ts module dispatches parsed tool calls to concrete handlers like read-files, write-file, or web-search. Each handler receives parsed arguments and returns structured results that feed back into the agent's messageHistory. The runtime supports custom tool registration through additionalToolDefinitions merged at initialization.

Streaming and Response Processing

Located in src/run-agent-step.ts, the getAgentStreamFromTemplate function manages LLM streaming, while processStream extracts tool calls and content chunks. The runtime handles

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}