Core Concepts

Default Harness

The default harness is eve's built-in agent loop. It manages model calls, compaction, and tool execution. See Built-in tools for its model-facing defaults and opt-ins, and Execution model and durability for how turns checkpoint and resume.

Compaction

Compaction keeps a long session from overflowing the model's context window. The harness compacts when the conversation, plus the compaction prompt's estimated size, reaches compaction.threshold of the window. It then summarizes the older turns into a checkpoint and keeps going. Omit compaction.threshold to compact at 0.9. Tune it under compaction in agent.ts:

agent/agent.ts
export default defineAgent({
  model: "anthropic/claude-opus-5.5",
  compaction: {
    threshold: 0.75,
  },
});

When history passes the threshold, eve summarizes the older turns. eve measures the space against the provider's last reported input token count, plus an estimate for new messages.

The summary prompt asks the compaction model to separate completed progress and decisions from remaining work. It also asks the model to keep the constraints, preferences, data, and references needed to continue. A later compaction passes the previous summary in full and replaces it with an updated one. Omit compaction.model to summarize with the active turn model.

After compacting, the harness keeps the most recent messages word for word next to the summary. It keeps up to 20,000 tokens or half the threshold, whichever is smaller, and shortens their tool results to 2,000 characters. The summarizer reads the kept messages too, so nothing a compaction drops is lost. A compaction that keeps recent messages must bring the input down to half the model's context window, so the next one is far off. eve checks this on its character estimate, scaled by the ratio of the provider's last reported input tokens to that estimate. When the kept messages don't fit under that, the harness keeps only their text, and then only the summary, which only has to fit under the threshold. If the first model call after a compaction is already over the threshold, the next compaction skips the option that fell short. The current user message is always kept. When that message alone exceeds the budget, the harness keeps its start and end with a note at the cut. It summarizes the middle with the older turns.

If the agent's instructions, tools, memory, and context leave the conversation no room under the threshold, eve logs a warning and compacts against the model's context window instead. Compaction then runs only when the request is over the window. When eve doesn't know the model's context window, it sends the request as it is. To keep the headroom the threshold gives, raise compaction.threshold or shorten the agent's instructions, tools, or memory.

If the instructions, tools, memory, and context alone don't fit the model's context window, eve doesn't call the provider. The turn fails with COMPACTION_FAILED, and the session can receive another message.

If the provider rejects a request as longer than the model's context window, the turn fails with MODEL_CALL_FAILED and a hint. The session can receive another message, and the turn's input stays in history.

The summary call retries transient provider errors like any model call. If it fails for another reason, the turn fails with MODEL_CALL_FAILED and the history stays uncompacted. After a transient error such as a 429, the session waits for the next message.

Memory stays outside history, so the summarizer never sees it. eve asks providers to capture before compaction rewrites history, and what earlier turns recalled follows the checkpoint.

Clients and channels can request compaction between turns with ClientSession.compact(), a channel route's compact(address), or attachSession(sessionId).compact(). The request doesn't append a user message. If a turn is running, eve queues the request until that turn ends. On the stream, manual and automatic compaction are the same context change: context.started and context.settled with kind: "compaction".

After either kind of compaction, eve moves the idle session to a fresh workflow run on the same deployment. This keeps a long session's run history from growing. See Execution model and durability.

To discard model-message history instead of summarizing it, call clear() on any of those handles. Clearing keeps the session identity, system prompt, configured tools and skills, defineState values, limits, and sandbox. It removes recalled memory, but doesn't delete data from a memory provider's external store. On the stream, clear is a context change with kind: "clear": context.started, then context.settled.