# Comparison Verdict & Portable Ideas

> Closing synthesis: where Eve wins (Vercel-native durability, filesystem discoverability, opinionated harness defaults) versus where Flue wins (multi-target deploy, explicit workflow surface, channel package ecosystem); which patterns—skills, sandbox isolation, session streaming—transfer across either stack.

- Repository: vercel/eve-with-withastro-flue
- GitHub: https://github.com/vercel/eve
- Human wiki: https://grok-wiki.com/public/wiki/vercel-eve-with-withastro-flue-43b600348681
- Complete Markdown: https://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/security-model.md`
- `vercel-eve:packages/eve/package.json`
- `withastro-flue:packages/runtime/package.json`
- `withastro-flue:packages/postgres/package.json`
- `withastro-flue:packages/opentelemetry/package.json`
- `vercel-eve:Dockerfile`

---

<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/Dockerfile](vercel-eve/Dockerfile)
- [vercel-eve/docs/concepts/security-model.md](vercel-eve/docs/concepts/security-model.md)
- [vercel-eve/docs/concepts/execution-model-and-durability.md](vercel-eve/docs/concepts/execution-model-and-durability.md)
- [vercel-eve/docs/concepts/default-harness.md](vercel-eve/docs/concepts/default-harness.md)
- [vercel-eve/docs/concepts/sessions-runs-and-streaming.md](vercel-eve/docs/concepts/sessions-runs-and-streaming.md)
- [vercel-eve/docs/reference/project-layout.md](vercel-eve/docs/reference/project-layout.md)
- [vercel-eve/packages/eve/package.json](vercel-eve/packages/eve/package.json)
- [withastro-flue/README.md](withastro-flue/README.md)
- [withastro-flue/AGENTS.md](withastro-flue/AGENTS.md)
- [withastro-flue/packages/runtime/package.json](withastro-flue/packages/runtime/package.json)
- [withastro-flue/packages/postgres/package.json](withastro-flue/packages/postgres/package.json)
- [withastro-flue/packages/opentelemetry/package.json](withastro-flue/packages/opentelemetry/package.json)
- [withastro-flue/packages/sdk/src/public/stream.ts](withastro-flue/packages/sdk/src/public/stream.ts)
- [withastro-flue/packages/runtime/src/skill-frontmatter.ts](withastro-flue/packages/runtime/src/skill-frontmatter.ts)
- [withastro-flue/apps/docs/src/content/docs/api/routing-api.md](withastro-flue/apps/docs/src/content/docs/api/routing-api.md)

</details>

# Comparison Verdict & Portable Ideas

Eve and Flue both ship a TypeScript agent harness with skills, sandboxes, durable sessions, and channel ingress — but they optimize for different deployment and authoring models. Eve is a **filesystem-first** framework where the `agent/` directory is the contract and durability is on by default through the Workflow SDK. Flue is a **programmable harness** where agents and workflows are distinct TypeScript modules, compiled for multiple runtimes, with a broad channel and persistence package ecosystem.

This page closes the multi-repo comparison: where each framework wins, where they converge, and which patterns transfer regardless of which stack you choose.

## Verdict at a Glance

| Dimension | Eve (`vercel/eve`) | Flue (`withastro/flue`) |
| --- | --- | --- |
| **Authoring model** | Directory contract: `instructions.md`, `skills/`, `tools/`, path-derived names | TypeScript modules: `agents/<name>.ts`, `workflows/<name>.ts`, `createAgent()` factories |
| **Durability** | Sessions durable by default; Workflow SDK checkpoints every step | Durable sessions + explicit workflow runs with persisted `runId` |
| **Deploy targets** | Vercel-native (Nitro host, Vercel Sandbox, Vercel Workflow) | Node, Cloudflare Workers, GitHub Actions, GitLab CI, Render, Daytona |
| **HTTP surface** | Stable `/eve/v1/session` API with `continuationToken` + `sessionId` | Mountable `flue()` Hono app: `/agents/:name/:id`, `/workflows/:name`, `/channels/:name/*` |
| **Channels** | Built into `eve` package exports (`./channels/slack`, etc.) | 20+ standalone channel packages (`@flue/slack`, `@flue/stripe`, …) |
| **Persistence** | Framework-owned workflow state | Pluggable adapters (`@flue/postgres`, `@flue/mysql`, `@flue/redis`, …) |
| **Streaming** | NDJSON event stream per session | Durable Streams protocol with offset-based replay |
| **Harness defaults** | Rich built-in tool set, compaction, `ask_question`, subagent delegation | Harness composed in `createAgent(() => ({ ... }))`; sandbox via `local()` or adapters |

Sources: [vercel-eve/README.md:19-57](), [withastro-flue/README.md:58-76](), [withastro-flue/AGENTS.md:7-20]()

## Where Eve Wins

### Vercel-native durability without configuration

Eve treats every turn as a durable workflow. Sessions survive crashes, timeouts, and redeploys with no author configuration — the runtime owns `start()`, `resumeHook()`, and checkpoint boundaries. Parked work (approvals, OAuth, subagents) suspends compute until input arrives.

```text
User message
    │
    ▼
Channel (auth, continuationToken)
    │
    ▼
Harness (one AI unit of work → { session, next })
    │
    ▼
Runtime (persist state, stream events, workflow primitives)
    │
    ▼
Workflow SDK checkpoints at each step boundary
```

Sources: [vercel-eve/docs/concepts/execution-model-and-durability.md:16-28](), [vercel-eve/README.md:48-57]()

### Filesystem discoverability

The agent directory **is** the API. Path determines identity — no `name` field on `define*` calls. `eve info` and `eve build` emit inspectable artifacts under `.eve/` (`agent-discovery-manifest.json`, `diagnostics.json`, `compiled-agent-manifest.json`), making it straightforward to debug what the runtime will load before booting a server.

Sources: [vercel-eve/docs/reference/project-layout.md:6-17](), [vercel-eve/README.md:41-42](), [vercel-eve/README.md:134-136]()

### Opinionated harness defaults

Every Eve agent ships with a framework-owned loop and a full built-in tool table: `bash`, `read_file`, `write_file`, `glob`, `grep`, `web_fetch`, `todo`, `ask_question`, `agent` (subagent), `load_skill`, and conditional `connection_search`. Compaction at 90% context threshold is automatic. Authors extend or override; they do not assemble the loop from scratch.

Sources: [vercel-eve/docs/concepts/default-harness.md:6-40]()

### Security model tuned for production agents

Eve draws a hard trust boundary between **app runtime** (secrets, Node.js, unrestricted network) and **sandbox** (isolated `/workspace`, no `process.env`). Built-in file/shell tools proxy from runtime into sandbox; custom tools execute in runtime. Credential brokering, connection token caching, constant-time channel signature verification, and fail-closed auth are documented as first-class concepts.

Sources: [vercel-eve/docs/concepts/security-model.md:8-53](), [vercel-eve/Dockerfile:8-76]()

## Where Flue Wins

### Multi-target deploy and runtime adapters

Flue compiles projects into deployable server artifacts for Node **and** Cloudflare Workers (with `./cloudflare` and `./node` entrypoints), plus documented targets for GitHub Actions, GitLab CI, Render, and Daytona sandboxes. The runtime package itself exposes adapter-specific subpaths rather than assuming one host.

Sources: [withastro-flue/README.md:58-65](), [withastro-flue/packages/runtime/package.json:12-48]()

### Explicit agents vs. workflows surface

Flue separates **persistent agent instances** (sessions across direct prompts and dispatched inputs) from **finite workflow runs** (`workflows/<name>.ts` exports `run(...)` with unique `ctx.id === runId`). Runs are workflow-only; agent prompts operate within sessions. This split makes background automations and interactive agents first-class, addressable concepts rather than optional harness features.

```text
agents/<name>.ts          workflows/<name>.ts
  createAgent(...)          export run(...)
       │                         │
       ▼                         ▼
  Harness → Session         Workflow run (runId)
  (persistent)              (finite, persisted)
       │                         │
       ▼                         ▼
POST /agents/:name/:id    POST /workflows/:name
GET  /agents/:name/:id    GET  /runs/:runId
```

Sources: [withastro-flue/AGENTS.md:7-20](), [withastro-flue/apps/docs/src/content/docs/api/routing-api.md:44-56]()

### Channel package ecosystem

Flue distributes channels as standalone packages — Slack, Discord, Teams, GitHub, Stripe, Shopify, Twilio, Zendesk, and more — each with its own build, tests, and Cloudflare worker conformance. This modular layout lets teams add or upgrade one ingress provider without pulling the entire runtime. Eve consolidates channel exports inside the monolithic `eve` package.

Sources: [withastro-flue/README.md:67-76](), [withastro-flue/packages/runtime/package.json:1-49]()

### Pluggable persistence and observability

Persistence and telemetry are opt-in adapter packages: `@flue/postgres`, `@flue/mysql`, `@flue/redis`, `@flue/mongodb`, `@flue/libsql` for storage, and `@flue/opentelemetry` as a peer-dependent tracing adapter. Operators choose backing stores and exporters; the core runtime stays host-agnostic.

Sources: [withastro-flue/packages/postgres/package.json:1-39](), [withastro-flue/packages/opentelemetry/package.json:1-42]()

### Typed client SDK and Durable Streams

`@flue/sdk` wraps Durable Streams with offset-based replay, live tailing, and automatic reconnection. Agent prompts return `202 { streamUrl, offset }`; workflow runs return `202 { runId, streamUrl, offset }`. The SDK exposes `FlueEventStream` as an `AsyncIterable` with checkpoint semantics — a different protocol than Eve's NDJSON-per-line stream, but equally explicit about resume coordinates.

Sources: [withastro-flue/packages/sdk/src/public/stream.ts:1-47](), [withastro-flue/apps/docs/src/content/docs/api/routing-api.md:58-62]()

## Portable Patterns

These ideas transfer across either stack without lock-in to a single vendor or host.

### Skills as markdown expertise packs

Both frameworks treat skills as **markdown with YAML frontmatter** aligned to the Agent Skills ecosystem. Eve discovers `agent/skills/<name>.md` (or packaged `skills/<name>/SKILL.md`) and loads them on demand via `load_skill`. Flue imports `SKILL.md` with a `with { type: 'skill' }` attribute and validates frontmatter through `parseSkillMarkdown`, mirroring `skills-ref` name and description rules.

| Concern | Eve | Flue |
| --- | --- | --- |
| Discovery | Filesystem walk under `agent/skills/` | Import assertion or workspace discovery |
| Load trigger | Model calls `load_skill` | `session.skill(name)` or harness `skills` array |
| Frontmatter safety | YAML-only; `---js` fences disabled | FAILSAFE_SCHEMA YAML; unknown fields ignored |

Sources: [vercel-eve/docs/concepts/security-model.md:47-49](), [vercel-eve/docs/reference/project-layout.md:16](), [withastro-flue/packages/runtime/src/skill-frontmatter.ts:18-51](), [withastro-flue/README.md:8-10]()

Skill packs remain **provider-neutral**: they are plain files in a repository or catalog, not tied to a model API. A Grok-Wiki or similar knowledge surface can index the same `SKILL.md` trees regardless of which harness loads them.

### Sandbox isolation with shared tooling DNA

Both frameworks give agents an isolated workspace for shell and file operations. Eve proxies `bash`/`read_file`/`write_file` from app runtime into a per-agent sandbox (Vercel Sandbox microVM on Vercel, Docker/`just-bash`/`microsandbox` locally). Flue's `local()` factory binds directly to the host on Node and shares `just-bash` as a dependency. Eve's `Dockerfile` seeds a `vercel-sandbox` user with `/workspace` — evidence of opinionated sandbox image defaults.

Sources: [vercel-eve/docs/concepts/security-model.md:10-19](), [vercel-eve/docs/concepts/default-harness.md:25-33](), [vercel-eve/Dockerfile:61-76](), [withastro-flue/packages/runtime/package.json:78](), [withastro-flue/packages/runtime/src/node/index.ts:1-7]()

The portable lesson: **keep secrets and privileged API calls in the trusted runtime; let the model manipulate files only inside an isolated workspace.**

### Session streaming as a first-class contract

Both frameworks separate **submission/resume handles** from **observation handles** and expose event streams for UIs and automations.

| Handle | Eve | Flue |
| --- | --- | --- |
| Resume conversation | `continuationToken` (channel-owned) | Session persists across `POST /agents/:name/:id` |
| Stream/inspect | `sessionId` → `GET .../stream` (NDJSON) | `streamUrl` + `offset` (Durable Streams) |
| Workflow runs | Optional experimental `Workflow` tool | `POST /workflows/:name` → `GET /runs/:runId` |

Sources: [vercel-eve/docs/concepts/sessions-runs-and-streaming.md:8-33](), [withastro-flue/apps/docs/src/content/docs/api/routing-api.md:46-56]()

Client integrations should treat stream coordinates as opaque, support reconnection from the last acknowledged offset or event index, and never conflate "send next message" with "attach to event stream."

### Subagents and delegation

Eve's built-in `agent` tool delegates to a copy sharing the parent sandbox. Declared subagents in `subagents/` get separate sandboxes, skills, and durable sessions. Flue's harness supports task agents and subagent profiles through the same `createAgent` composition model. The portable pattern: **scope context and filesystem per delegation boundary; persist child work as its own session or run.**

Sources: [vercel-eve/docs/concepts/default-harness.md:38-44](), [vercel-eve/docs/concepts/execution-model-and-durability.md:38-40](), [withastro-flue/README.md:51]()

## Choosing Between Them

```mermaid
flowchart TD
  subgraph question [Start here]
    Q1{Vercel-primary deploy?}
    Q2{Need Cloudflare Workers or CI-native runs?}
    Q3{Prefer directory authoring or TS module composition?}
  end

  Q1 -->|Yes| EveFit[Eve: durable-by-default, Vercel Sandbox, eve info discovery]
  Q1 -->|No| Q2
  Q2 -->|Yes| FlueFit[Flue: multi-target adapters, workflow runs, channel packages]
  Q2 -->|No| Q3
  Q3 -->|Directory / markdown-first| EveFit
  Q3 -->|Explicit agents + workflows in code| FlueFit
```

**Choose Eve** when you want markdown-first authoring, zero-config durable sessions on Vercel Workflow, inspectable `.eve/` discovery artifacts, and a production security model with Vercel Sandbox credential brokering baked in.

**Choose Flue** when you need deploy portability (especially Cloudflare Workers), a clean split between long-lived agents and finite workflow runs, a wide channel adapter catalog, and bring-your-own persistence/telemetry.

**Borrow from both** when designing your own harness: filesystem-discoverable skills, strict sandbox/runtime trust boundaries, separated resume vs. stream handles, and durable checkpointing at tool boundaries are proven patterns in both codebases.

## Summary

Eve optimizes for **opinionated defaults on a Vercel-shaped runtime** — the agent folder is the source of truth, durability is automatic, and the harness ships ready to work. Flue optimizes for **explicit composition and deploy flexibility** — agents and workflows are distinct HTTP surfaces, channels and stores are modular packages, and the SDK speaks Durable Streams. Skills (Agent Skills markdown), sandbox isolation, and session/event streaming are the highest-value portable ideas: they are file- and protocol-level patterns that survive a change of host, model provider, or harness implementation.