Research for agent runner abstraction layer to decouple eve harness from eve runtime

[felixarntz]

Summary

Related to #2194: That proposal correctly identifies StepFn as the point where eve's durable workflow invokes
agent work, but StepFn is an internal callable type rather than a swappable provider boundary. The current runtime always resolves a model-backed RuntimeTurnAgent, constructs or rehydrates a model-loop-specific HarnessSession, refreshes that session before every step, and then unconditionally creates the built-in tool loop. Merely allowing another function to satisfy the StepFn signature would not let an external package bypass that lifecycle, supply its own durable checkpoint, or change how runner state is resumed and persisted. HarnessAgent therefore cannot replace eve's harness layer through the current StepFn boundary.

This proposal introduces a provider-neutral, versioned AgentRunnerV1 layer. eve would continue to own durable root and subagent sessions, workflows, tools, approvals, sandboxes, events, and cancellation, while each runner would own only its native execution and opaque checkpoint. Unblocking HarnessAgent for subagents therefore requires changes inside the eve runtime—separating the common durable session envelope from built-in-runner state and adapting runner results into StepFn—but no HarnessAgent-specific branch, setting, dependency, or module-map entry in eve; a separate package could implement the generic contract.

Review focus

The main design question is whether AgentRunnerV1 draws the right ownership boundary: broad enough to support root agents and subagents implemented by an external package, but narrow enough that eve remains the sole owner of durable lifecycle and host capabilities. In particular, please review the checkpoint model, runner status transitions, tool and sandbox hosts, capability negotiation, and source-based module loading.

The other key question is whether we'd even want to have such an abstraction layer or whether we want to instead use AI SDK's HarnessAgent in eve itself conditionally instead of AI SDK's ToolLoopAgent. The tradeoff is that it would mean HarnessAgent inevitably becomes a part of eve itself; on the other hand, since HarnessAgent itself provides a harness abstraction layer, backing on it would avoid eve from having to invent its own.

Consider this example:

import { defineAgent } from "eve";

// Provide either a model (goes through `ToolLoopAgent`)
export default defineAgent({
  model: "openai/gpt-5.6-sol",
});

// Or provide a harness (goes through `HarnessAgent`)
export default defineAgent({
  harness: "codex",
});

While this would make for a neat public API, it clearly would couple HarnessAgent with eve directly.

Checklist

• This change was requested or approved by a maintainer
• I ran the relevant checks from CONTRIBUTING.md
• I added tests and documentation where relevant
• I added a changeset if this touches the published eve package
• DCO sign-off passes for every commit (git commit --signoff)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview, v0	Aug 25, 2026 8:42pm
eve-pkg	Ready	Preview, v0	Aug 25, 2026 8:42pm

[felixarntz]

not worth pursuing, overengineered