# Comparison Frame

> What Eve and Flue each optimize for, the shared problem space (durable agents with tools, skills, sandboxes, and channels), and the criteria—authoring ergonomics, runtime layering, deployment portability, and workflow boundaries—that make cross-repo lessons actionable.

- Repository: vercel/eve-with-withastro-flue
- GitHub: https://github.com/vercel/eve
- Human wiki: https://www.grok-wiki.com/public/wiki/vercel-eve-with-withastro-flue-43b600348681
- Complete Markdown: https://www.grok-wiki.com/public/wiki/vercel-eve-with-withastro-flue-43b600348681/llms-full.txt

## Source Files

- `vercel-eve:README.md`
- `withastro-flue:README.md`
- `vercel-eve:docs/concepts/execution-model-and-durability.md`
- `withastro-flue:AGENTS.md`
- `vercel-eve:package.json`
- `withastro-flue:package.json`

---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [vercel-eve/README.md](vercel-eve/README.md)
- [vercel-eve/AGENTS.md](vercel-eve/AGENTS.md)
- [vercel-eve/docs/introduction.md](vercel-eve/docs/introduction.md)
- [vercel-eve/docs/concepts/execution-model-and-durability.md](vercel-eve/docs/concepts/execution-model-and-durability.md)
- [vercel-eve/docs/reference/project-layout.md](vercel-eve/docs/reference/project-layout.md)
- [vercel-eve/packages/eve/README.md](vercel-eve/packages/eve/README.md)
- [vercel-eve/package.json](vercel-eve/package.json)
- [withastro-flue/README.md](withastro-flue/README.md)
- [withastro-flue/AGENTS.md](withastro-flue/AGENTS.md)
- [withastro-flue/CHANGELOG.md](withastro-flue/CHANGELOG.md)
- [withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md](withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md)
- [withastro-flue/examples/hello-world/flue.config.ts](withastro-flue/examples/hello-world/flue.config.ts)
- [withastro-flue/package.json](withastro-flue/package.json)

</details>

# Comparison Frame

Eve and Flue both target the same product space: **durable agents** that combine model reasoning with **tools**, **skills**, **sandboxes**, and **channels** so autonomous work can run safely across many turns, transports, and restarts. They diverge sharply in what each optimizes for—Eve around filesystem-authored contracts and Vercel-native durability, Flue around a programmable TypeScript harness and portable deployment targets.

This page is a comparison brief, not a feature checklist. Use it to decide which ideas are portable when borrowing patterns across repositories, and which differences reflect intentional tradeoffs in authoring ergonomics, runtime layering, deployment portability, and workflow boundaries.

## Shared Problem Space

Both frameworks assume agents are long-lived programs, not one-shot API calls. A message arrives from some transport; the runtime assembles instructions, skills, tools, and history; work may call tools, delegate to subagents, pause for human input, and stream progress; state must survive long gaps and process restarts.

| Capability | Eve | Flue |
|------------|-----|------|
| Tools | Typed `defineTool` modules under `agent/tools/` | `defineTool` and MCP-connected tools composed in `createAgent` |
| Skills | Markdown procedures under `agent/skills/` | `SKILL.md` imported as `SkillReference` values |
| Sandboxes | Per-agent authored `agent/sandbox/` override | Virtual, local, or remote container sandboxes in agent config |
| Channels | `agent/channels/` for HTTP, Slack, Discord, etc. | Verified HTTP channels (Slack, Teams, GitHub, …) via blueprints |
| Subagents | Declared directories with isolated sandbox/skills/state | Named `defineAgentProfile` subagents and `task` delegation |
| Durability | Sessions durable by default via Workflow SDK | Agent session history + submission lifecycle; workflows handled separately |

Sources: [vercel-eve/README.md:23-29](), [vercel-eve/docs/introduction.md:30-34](), [withastro-flue/README.md:47-56](), [withastro-flue/AGENTS.md:7-17]()

## What Each Framework Optimizes For

### Eve: filesystem-first, Vercel-durable backend agents

Eve treats **the agent directory as the contract**. Instructions, skills, tools, connections, sandbox, channels, subagents, and schedules are files in named slots; Eve discovers them and compiles inspectable artifacts under `.eve/`. Identity is path-derived—there is no parallel registry to keep in sync.

```text
my-agent/agent/
├── agent.ts              # additive runtime config (model, metadata, build)
├── instructions.md       # always-on prompt
├── skills/               # optional procedures
├── tools/                # typed integrations
├── connections/          # MCP servers
├── sandbox/              # workspace override
├── channels/             # ingress + delivery
└── subagents/            # specialists
```

Eve prioritizes markdown-first authoring, durable message runs with explicit `continuationToken` and `sessionId` HTTP contracts, and a runtime that **hides workflow primitives** from authors while making every turn durable by default.

Sources: [vercel-eve/README.md:19-44](), [vercel-eve/docs/reference/project-layout.md:6-17](), [vercel-eve/package.json:5]()

### Flue: programmable harness, agent/workflow split, deploy-anywhere

Flue is framed as an **agent harness framework**, not a thin SDK wrapper. Authors compose agents in TypeScript with `createAgent`, explicitly wiring model, tools, skills, sandbox, and instructions. Projects compile into deployable server artifacts; build targets (Node, Cloudflare Workers, GitHub Actions, etc.) are selected at build time via `flue.config.ts`, while provider registration stays runtime-owned.

Flue draws a hard line between **continuing agents** (persistent sessions, direct prompts, `dispatch`) and **finite workflows** (`run(...)` with `runId`). Runs, `/runs`, and `flue logs` inspect workflows only—agent interactions correlate by instance, session, operation, and `dispatchId`.

Sources: [withastro-flue/README.md:3-41](), [withastro-flue/AGENTS.md:3-20](), [withastro-flue/CHANGELOG.md:230-239](), [withastro-flue/examples/hello-world/flue.config.ts:4-12]()

## Runtime Layering: Where Boundaries Live

The most actionable cross-repo lesson is **where each framework draws ownership lines** between transport, agent execution, and persistence.

### Eve: channel → harness → runtime

```mermaid
flowchart TB
  subgraph transport["Ingress / delivery"]
    CH["channels/&lt;name&gt;.ts"]
  end
  subgraph unit["One AI unit"]
    HAR["harness"]
  end
  subgraph persist["Durability + orchestration"]
    RT["runtime"]
    WF["Workflow SDK primitives"]
  end

  CH -->|"normalizes message, owns continuationToken"| HAR
  HAR -->|"{ session, next }"| RT
  RT -->|"start(), resumeHook(), streams"| WF
  RT -->|"owns sessionId for inspection"| CH
```

- **Channel** normalizes inbound transport, applies auth/delivery policy, owns `continuationToken`.
- **Harness** performs one unit of AI work.
- **Runtime** persists state, follows `next`, streams events, and owns workflow primitives authors never touch.

Sources: [vercel-eve/README.md:48-57](), [vercel-eve/packages/eve/README.md:148-157]()

### Flue: instance → harness → session → operation (workflows parallel)

```mermaid
flowchart TB
  subgraph agents["Continuing agents"]
    AM["agents/&lt;name&gt;.ts"]
    AI["AgentInstance"]
    H["Harness"]
    S["Session"]
    OP["Operation / Turn"]
    AM --> AI --> H --> S --> OP
  end
  subgraph workflows["Finite jobs"]
    WM["workflows/&lt;name&gt;.ts"]
    RUN["run(...) / runId"]
    WM --> RUN
  end
  subgraph shared["Shared capabilities"]
    TOOLS["tools"]
    SK["skills"]
    SB["sandbox adapters"]
  end
  H --> TOOLS
  H --> SK
  H --> SB
  RUN -->|"init(agent) when needed"| H
```

Flue's terminology stack—profile, created agent, module, instance, harness, session, operation, turn—is explicit in contributor docs. Workflows may initialize agents via `init(agent)` but remain a separate invocation surface with their own durability semantics.

Sources: [withastro-flue/AGENTS.md:7-20](), [withastro-flue/README.md:24-32]()

## Comparison Criteria

### 1. Authoring ergonomics

| Criterion | Eve | Flue |
|-----------|-----|------|
| Primary authoring surface | Filesystem slots under `agent/` | TypeScript modules (`agents/`, `workflows/`) |
| Instructions | `instructions.md` | Inline string or imported content in `createAgent` |
| Identity | Path-derived names; no `name` fields on `define*` | Agent instances have ids; harnesses and sessions have names |
| Discovery | Walk `agent/` tree; compiled `.eve/` artifacts | Vite build graph + CLI discovery (`flue.config.ts`) |
| Skill packaging | Drop markdown in `skills/` | Import `SKILL.md` with `{ type: 'skill' }`; bundle supporting files |
| Layout flexibility | Single recommended tree | `.flue/`, `src/`, or root `agents/` / `workflows/` |

**Portable lesson:** both treat skills as optional, load-on-demand expertise separate from always-on instructions. Eve optimizes for non-developer-readable trees; Flue optimizes for explicit composition and import graphs.

Sources: [vercel-eve/docs/introduction.md:38-61](), [vercel-eve/docs/reference/project-layout.md:8-17](), [withastro-flue/README.md:8-32](), [withastro-flue/AGENTS.md:34-35](), [withastro-flue/CHANGELOG.md:233]()

### 2. Runtime layering

| Criterion | Eve | Flue |
|-----------|-----|------|
| Transport ownership | Channel owns `continuationToken` | Channels + `route` / `websocket` middleware exports |
| Execution unit | Harness returns `{ session, next }` | Harness exposes sessions; operations are prompt/skill/task/shell |
| Hidden orchestration | Workflow SDK inside runtime only | Agent submission lifecycle + optional `PersistenceAdapter` |
| Public correlation IDs | `continuationToken` vs `sessionId` | Instance/session/operation/`dispatchId` vs workflow `runId` |

**Portable lesson:** separate **resume handles for the next user turn** from **inspection/streaming handles for observers**. Eve names this split directly in its HTTP protocol; Flue achieves a similar separation by refusing to call agent prompts "runs."

Sources: [vercel-eve/packages/eve/README.md:154-157](), [withastro-flue/AGENTS.md:20](), [withastro-flue/CHANGELOG.md:239]()

### 3. Deployment portability

| Criterion | Eve | Flue |
|-----------|-----|------|
| Primary deployment story | Durable backend agents on Vercel | Node, Cloudflare Workers, GitHub Actions, GitLab CI, Render, Daytona, … |
| Durability substrate | Workflow SDK (Vercel Workflow on Vercel) | Target-specific: DO SQLite on Cloudflare; optional `db.ts` adapters on Node |
| Build vs runtime config | `agent.ts` + compiled `.output/` | `flue.config.ts` (target, root, output) vs `app.ts` (providers) |
| Provider neutrality | Model string in `defineAgent`; connections for MCP | `registerProvider(...)` at runtime; BYOC API keys/bindings |

Eve's monorepo description and durability doc anchor it to Vercel's workflow stack. Flue documents materially different recovery behavior per target and requires explicit persistence for Node restarts.

Sources: [vercel-eve/package.json:5](), [vercel-eve/docs/concepts/execution-model-and-durability.md:16-22](), [withastro-flue/README.md:58-65](), [withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md:44-80](), [withastro-flue/examples/hello-world/flue.config.ts:4-12]()

### 4. Workflow boundaries

This is the sharpest conceptual fork.

| Aspect | Eve | Flue |
|--------|-----|------|
| What is a "run"? | Every **turn** is a durable workflow | **Runs** are workflow invocations only |
| Author workflow code? | No—primitives are implementation details | Yes—author `run(...)` for finite jobs |
| Workflow resumability | Steps checkpoint inside turns; parked work resumes | Workflows are **not resumable**; retry = new invocation |
| Message queue semantics | No durable FIFO per session; channel/app may queue | Per-instance ordered submission lifecycle on durable targets |
| When to use workflows | Implicit—durability wraps all agent turns | Explicit—bounded jobs (reports, CI tasks, batch orchestration) |

Eve parks turns durably when waiting on approval, OAuth, or subagents, then resumes from the workflow hook. Flue tells authors to move one-shot request/result modules into `workflows/` and keep long-lived agents in `agents/`.

```text
Eve turn lifecycle:
  user message → durable workflow turn → step checkpoints → response
                      ↓ (park)
              resumeHook when input arrives

Flue dual lifecycle:
  agent:   input → session history → operation → later input continues
  workflow: invoke run(runId) → result | error → retry = new runId
```

Sources: [vercel-eve/docs/concepts/execution-model-and-durability.md:14-36](), [withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md:88-109](), [withastro-flue/CHANGELOG.md:230-239]()

## Durability Philosophy

Both frameworks checkpoint agent work conservatively and warn about non-idempotent side effects—but they apply durability at different granularities.

**Eve** nests session → turn → step. Steps are durable checkpoints inside a turn; completed steps never re-run. Sessions are durable by default with nothing to configure. Authors use `ctx.session` and `defineState` rather than workflow APIs.

**Flue** distinguishes durable **agents** (session history + submission reconciliation) from **workflows** (single-shot functions without arbitrary TypeScript checkpointing). Sandbox files and conversation history are intentionally separate concerns.

Sources: [vercel-eve/docs/concepts/execution-model-and-durability.md:8-24](), [withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md:82-86](), [withastro-flue/apps/docs/src/content/docs/concepts/durable-execution.md:88-93]()

## Making Cross-Repo Lessons Actionable

Use these decision lenses when borrowing patterns:

1. **Prefer filesystem slots** when many contributors edit instructions/skills/tools without touching shared TypeScript—Eve's model. **Prefer explicit `createAgent` composition** when agents are code-first products with importable skill bundles and multiple deploy targets—Flue's model.

2. **Hide orchestration** when every conversational turn should feel like durable backend logic with minimal author burden (Eve). **Expose workflows** when the product mixes open-ended agents with finite, inspectable jobs that need their own `runId` and logs (Flue).

3. **Treat channels as policy owners** for resume tokens and delivery shaping in both systems; do not assume either framework gives you a strict per-session chat FIFO without app-layer queuing (Eve states this explicitly).

4. **Keep sandbox lifecycle separate from session persistence** on both sides—durable conversation ≠ durable workspace files.

5. **Stay provider-neutral** for skills and tools: both support MCP and typed tools; model/provider choice remains an authored or runtime-registered concern, not a framework lock-in.

For Grok-Wiki or similar synthesis UIs, treat skill packs as **portable file or catalog sources** (repository trees, `SKILL.md`, `docs/`, blueprints)—not as dependencies on a single model vendor. The comparison frame above maps cleanly to wiki page types: **concept** (shared problem space), **architecture pattern** (runtime layering), **developer convention** (authoring layouts), and **failure mode** (workflow vs turn durability, message ordering, idempotent side effects).

## Summary

Eve optimizes for **inspectable, markdown-first agent directories** and **opinionated durability on Vercel** via a channel/harness/runtime split that keeps workflow machinery internal. Flue optimizes for a **composable TypeScript harness**, a **strict agent-vs-workflow boundary**, and **multi-target deployment** with explicit persistence and sandbox adapters. The shared substrate—tools, skills, sandboxes, channels, subagents, durable sessions—is real; the actionable differences are how you author (tree vs module), what counts as a run (every turn vs workflow-only), and how much orchestration the framework owns versus what your application must supply at deploy time.