Ch5. agent.ts, Models, Compaction

Usage limits in 0.82.0: sessionUsage

Replace maxInputTokensPerSession, maxOutputTokensPerSession, and maxTokenCostUsdPerSession with limits.sessionUsage. Returning true stops the next model call.

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5.5",
  limits: {
    sessionUsage: ({ window }) =>
      window.inputTokens - window.cacheReadTokens >= 200_000 ||
      window.outputTokens >= 20_000 ||
      (window.costUsd ?? 0) >= 1.5,
  },
});

• total is cumulative; window starts after the last approved Continue. Continue resets only the window.
• Input includes cache usage. Subtract cacheReadTokens for new input. Optional costUsd is Gateway-reported model token cost; it excludes tools and infrastructure.
• The call crossing a threshold may finish. These thresholds are not exact billing caps; use external spend controls as well.
• Interactive runs pause at turn.waiting for Continue/Stop. Stop cancels the active turn and delegation tree, leaving the session resumable. Runs without human input fail with SESSION_USAGE_LIMIT_REACHED.
• Children use their own policy or the root policy, not an allocated share of the parent's remaining budget. Test aggregation timing and cancellation exceptions.

Agent config: limits.

agent/agent.ts configures runtime behavior. In small demos it often only selects a model. In enterprise systems it decides model routing, output contracts, long-session memory behavior, and unstable feature adoption.

Basic Form

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5.5",
});

The official agent.ts docs clarify two important rules:

Model IDs below are routing examples. Pin the model and options you have evaluated; framework and scaffold defaults can change.

Model Routing Strategy

For enterprise teams, Gateway-routed models are usually the default because usage, fallback, cost, and policy can be centralized. Direct provider models are still valid when specific provider options or self-host constraints require them.

Model Selection Matrix

The goal is not "the smartest model." The goal is the model with the lowest failure cost for the capability surface.

modelOptions

Current modelOptions accepts providerOptions and promptCache. Set portable reasoning effort with the separate reasoning field; use modelOptions.providerOptions for provider-specific controls.

Operating rules:

• separate reasoning-heavy agents from transactional agents
• gate model option changes like prompt changes
• record model id and options in eval results
• document provider-specific portability risks

outputSchema

The 0.82.0 defineAgent type has no outputSchema field. Request structured output when creating a client session, sending a turn, or sending to a child session from a workflow. The schema applies only to that turn. A tool's own outputSchema is a separate return-value validation contract.

import { Client } from "eve/client";
import { z } from "zod";

const riskSchema = z.object({
  risk: z.enum(["low", "medium", "high"]),
  requiredApprovals: z.array(z.string()),
  rationale: z.string(),
});
type RiskReview = z.infer<typeof riskSchema>;
const client = new Client({ host: "http://127.0.0.1:2000" });
const { response } = await client.sessions.create<RiskReview>({
  message: "Review the proposed operation.",
  outputSchema: riskSchema,
});
const result = await response.result();
if (!result.data) throw new Error("No structured result was produced.");
console.log(result.data.risk);

The server validates the schema. A client generic does not independently revalidate the payload, and data may be undefined when no structured result was produced. Configure route authentication before using a remote host.

Client output schema.

Compaction

The default harness summarizes older turns as the context window fills. The default threshold is 90%.

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

Compaction saves context and cost, but it is also a risk surface. A bad summary can corrupt the factual base of a long session.

Experimental Flags

Do not copy the old experimental.codeMode or ExperimentalWorkflow exports into current configuration. Model-generated orchestration now uses the lowercase workflow() factory from eve/tools/workflow. Authored durable work uses defineWorkflowTool with a "use workflow" directive.

Check experimental.workflow world, retention, and checkpoint-batching settings against current types and a compatible World version. Keep replayed workflow bodies separate from steps that perform external effects, and configure approval independently.

Workflow tools · Agent config.

Hosted Build Packaging

build.externalDependencies keeps selected packages external in hosted output. It is packaging control, not security approval.

Review:

• package install availability in target host
• third-party SDK network and data behavior
• security review for externalized dependency
• parity between Vercel and self-host environments

Review Checklist