# What Does the agent-runtime Package Do in Freebuff?

> Discover the @codebuff/agent-runtime package, Freebuff's LLM agent execution engine. It handles prompt construction, token budgeting, tool dispatching, and output validation in a continuous loop.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: internals
- Published: 2026-09-01

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/src/run-agent-step.ts), the `getAgentStreamFromTemplate` function manages LLM streaming, while `processStream` extracts tool calls and content chunks. The runtime handles