@ai-sdk-tool/harness Core
Relevant source files
The following files were used as context for generating this wiki page:
The @ai-sdk-tool/harness package serves as the model-agnostic backbone of the plugsuits project. It provides a lightweight, reusable agent framework built on the Vercel AI SDK, designed to decouple core agent logic from specific UI implementations or model providers. Its primary purpose is to manage the agent loop, conversation history, session lifecycles, and tool orchestration.
As the foundational layer of the monorepo, it enables higher-level packages like @ai-sdk-tool/tui (Terminal UI) and @ai-sdk-tool/headless (JSONL event streaming) to function without duplicating low-level coordination logic. It handles critical tasks such as context compaction to prevent token limit overflows and manages complex message sequences involving tool calls and results.
Sources: packages/harness/README.md:3-8, AGENTS.md:13-15, AGENTS.md:124-126
Core Architecture and Loop Management
The harness is centered around a model-agnostic iteration loop. It wraps the Vercel AI SDK's streamText functionality into an Agent abstraction that can be executed repeatedly until a specific finish condition is met.
Agent Loop Execution
The runAgentLoop function manages the lifecycle of an agent's turn. It iterates through model calls, handling tool executions and state updates until the model provides a stop reason or an external abort signal is received.
The diagram shows the iterative process where the loop continues as long as tool calls are requested or the continuation predicate returns true.
Sources: packages/harness/README.md:39-44, AGENTS.md:54-56, AGENTS.md:65
Core Components
| Component | Description |
|---|---|
createAgent | Factory function that wraps Vercel AI SDK streamText into a manageable Agent instance. |
runAgentLoop | Primary execution engine that runs the agent until termination conditions are met. |
CheckpointHistory | Manages conversation history, providing features like compaction, checkpointing, and automatic cleanup of invalid sequences. |
SessionManager | Handles UUID-based session lifecycles for consistent event and path stamping. |
SkillsEngine | Discovers and loads "skills" (extended tool/instruction sets) from bundled, global, or project-specific directories. |
Sources: packages/harness/README.md:10-18, AGENTS.md:66-73
Context and History Management
The harness implements a sophisticated history management system designed to handle long-running conversations within finite context windows.
CheckpointHistory and Compaction
CheckpointHistory tracks messages and manages "compaction"—a process where older conversation parts are summarized to free up token space. It includes a speculativeStartRatio to begin background summarization before limits are actually hit.
This sequence illustrates how the history manager interacts with a summarizer to maintain context continuity while reducing token count.
Sources: packages/harness/README.md:76-88, packages/harness/CHANGELOG.md:82-90, packages/harness/src/compaction-prompts.test.ts:114-125
Summarization Logic
The system uses specialized prompts to ensure summaries retain technical details, user intents, and pending tasks. It supports "iterative compaction," where previous summaries are passed back into the model to maintain long-term memory.
| Feature | Description |
|---|---|
DEFAULT_SUMMARIZATION_PROMPT | Standard prompt for general conversation compression. |
ITERATIVE_SUMMARIZATION_PROMPT | Optimized for updating existing summaries with new context. |
| Task-Aware Compaction | Extracts user turn intent before summarizing to prevent loss of immediate goals. |
| Token Estimation | Includes CJK-aware estimation (~1.5 chars/token) and image/tool call overhead tracking. |
Sources: packages/harness/CHANGELOG.md:46-55, packages/harness/CHANGELOG.md:82-87, packages/harness/src/compaction-prompts.test.ts:140-155
Command and Skill Orchestration
The harness provides a global registry for slash commands and a discovery mechanism for agent "skills."
Command Registry
Commands are registered globally and can be invoked in both TUI and headless environments. The registry supports aliases and can resolve skill-based commands dynamically.
// Example Command Registration
registerCommand({
name: "model",
description: "Switch the active model",
aliases: ["m"],
execute: async ({ args }) => {
// Implementation details
return { success: true, message: `Switched to ${args[0]}` };
},
});
Sources: packages/harness/README.md:143-165, AGENTS.md:59-60
Skills Engine
The SkillsEngine looks for skill definitions (Metadata + Instructions/Tools) across five distinct locations:
- Bundled: Shipped with the agent package.
- Global Skills: User-wide directory (e.g.,
~/.agent/skills). - Global Commands: User-wide slash commands.
- Project Skills: Local project directory.
- Project Commands: Local project slash commands.
Sources: packages/harness/README.md:112-120, AGENTS.md:118-120
Integration and Utility Systems
Session and Path Management
The SessionManager provides unique identifiers for each agent run, while createAgentPaths ensures consistent directory structures for configurations and TODO tracking.
Sources: packages/harness/README.md:92-104, packages/harness/README.md:204-215
Middleware and Tool Repair
- Middleware:
buildMiddlewareChainallows developers to inject logic (logging, token counting, caching) into the model call pipeline. - Repair Escalation:
experimental_repairToolCallprovides a callback mechanism to handle malformed tool calls, allowing models to attempt auto-correction before failing.
Sources: packages/harness/README.md:188-198, packages/harness/README.md:255-263, README.md:23-24
Conclusion
The @ai-sdk-tool/harness Core provides the essential infrastructure for robust AI agents. By abstracting loop management, context compaction, and tool orchestration, it allows developers to focus on specific agent behaviors (like code editing in cea) while ensuring reliable performance and memory management across different LLM providers.