Headless Runtime (@ai-sdk-tool/headless)
Relevant source files
The following files were used as context for generating this wiki page:
The Headless Runtime is a specialized module within the plugsuits monorepo designed for non-interactive agent execution. It provides a mechanism for JSONL (JSON Lines) event streaming, enabling AI agents to be integrated into CI/CD pipelines, automated benchmarks, and other programmatic environments where a Terminal User Interface (TUI) is not required. Sources: AGENTS.md:12, README.md:21-22
The module decouples the core agent logic from the presentation layer, allowing the same agent implementation to function across different runtimes. In headless mode, the runtime emits structured events such as user, tool_call, tool_result, assistant, and error for external consumption. Sources: AGENTS.md:131-132, packages/cea/src/AGENTS.md:24-25
Architecture and Core Components
The Headless Runtime operates as an event-driven loop that interfaces with the @ai-sdk-tool/harness for core agent logic and message history management. It is primarily responsible for translating agent actions and model responses into a stream of structured data. Sources: AGENTS.md:28, packages/headless/CHANGELOG.md:31-33
Key Components
| Component | Role | Location |
|---|---|---|
runHeadless | The primary execution loop that manages agent iterations and event flow. | packages/headless/src/runner.ts |
emitEvent | Utility for writing structured TrajectoryEvent objects as JSONL strings to stdout. | packages/headless/src/emit.ts |
TrajectoryEvent | A union type defining the schema for all emitted events. | packages/headless/src/types.ts |
registerSignalHandlers | Manages system signals (SIGINT, SIGTERM) to ensure clean shutdowns. | packages/headless/src/signals.ts |
Sources: AGENTS.md:46-59, packages/cea/src/AGENTS.md:25
Event Processing Flow
The following diagram illustrates how the Headless Runtime processes a task from initialization to completion, emphasizing the emission of JSONL events at each step.
The flow starts with an initial user message and iterates through tool calls and assistant responses until the agent decides to stop or reaches a maximum iteration limit. Sources: AGENTS.md:46, packages/cea/src/AGENTS.md:25-27, packages/minimal-agent/index.ts:133-149
Event Streaming and JSONL
Headless mode is characterized by its use of JSONL for communication. This format ensures that each event is a standalone JSON object followed by a newline, making it easy to parse in real-time. Sources: AGENTS.md:12, README.md:65
Trajectory Event Types
The runtime emits a specific set of events that capture the "trajectory" of the agent's problem-solving process:
user: Represents input from the human user or the starting instruction.tool_call: Details a specific tool the agent has decided to invoke, including input parameters.tool_result: Contains the output or error returned by a tool execution.assistant: The text or reasoning output generated by the LLM.error: Signals runtime failures or exceptions encountered during the loop.
Sources: AGENTS.md:131-132, packages/cea/src/AGENTS.md:25
Stream Processing Invariants
Recent updates to the stream processor have refined event emission to avoid "no text output" fallbacks. Tool-call-only steps now emit an empty string instead of placeholders, ensuring downstream consumers (like benchmark scorers) do not receive corrupted response strings. Sources: packages/headless/CHANGELOG.md:5-7
Integration with Middleware and Compaction
The Headless Runtime supports advanced features such as context compaction and TODO continuation through callbacks and middleware integration. Sources: packages/headless/CHANGELOG.md:12-15
Task-Aware Compaction
In the @ai-sdk-tool/cea implementation, the headless runner utilizes a "task-aware" 2-step compaction process. Before summarizing history, the runtime extracts the current turn's task intent. This ensures that even when the context window is tight, the agent does not lose track of the specific work context or intent of the current user message. Sources: packages/headless/CHANGELOG.md:14-16
Lifecycle Sequence
The sequence below shows the interaction between the Headless runner, the Agent, and the History management during a single turn.
Turn boundaries are explicitly tracked via notifyNewUserTurn(), which is critical for the compaction logic to identify where new context begins. Sources: packages/headless/CHANGELOG.md:16-17, packages/minimal-agent/index.ts:153-159
Configuration and Usage
The headless entry point is typically invoked via the CLI with a prompt argument, which automatically triggers the headless runner. Sources: packages/minimal-agent/index.ts:121-124
Example Headless Invocation
pnpm run headless -- "Fix the type error in src/index.ts"
Sources: README.md:63
Runner Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
agent | Agent | The agent instance providing the stream method. |
initialUserMessage | Message | The starting prompt for the headless session. |
messageHistory | CheckpointHistory | Managed history for tokens and compaction. |
maxIterations | number | Safety cap on the number of tool/response cycles. |
onTurnComplete | Function | Callback used to extract facts or update state after a cycle. |
Sources: packages/minimal-agent/index.ts:133-149, AGENTS.md:58-59
Conclusion
The Headless Runtime (@ai-sdk-tool/headless) provides a robust, scriptable interface for the plugsuits agent ecosystem. By standardizing on JSONL event trajectories, it enables high-fidelity monitoring and automation of code-editing tasks without the overhead of a terminal environment. Its integration with the CheckpointHistory system ensures it can handle complex, long-running tasks within the token limits of modern LLMs. Sources: README.md:21-22, packages/headless/CHANGELOG.md:12-17