# Overview > What Flue and Eve expose, how the workspace repos relate, runtime assumptions, and the shortest source-backed paths into each framework. - Repository: withastro/flue-with-vercel-eve - GitHub: https://github.com/withastro/flue - Human docs: https://www.grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6 - Complete Markdown: https://www.grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6/llms-full.txt ## Source Files - `withastro-flue:README.md` - `withastro-flue:AGENTS.md` - `withastro-flue:packages/runtime/src/index.ts` - `vercel-eve:README.md` - `vercel-eve:docs/README.md` - `vercel-eve:docs/introduction.md` - `vercel-eve:packages/eve/src/public/index.ts` --- --- title: "Overview" description: "What Flue and Eve expose, how the workspace repos relate, runtime assumptions, and the shortest source-backed paths into each framework." --- Flue (`withastro/flue`) and Eve (`vercel/eve`) are independent TypeScript agent frameworks checked into this workspace. Flue compiles `agents/`, `workflows/`, and `channels/` modules into a Hono server with routes under `/agents`, `/workflows`, `/runs`, and `/channels`. Eve walks an `agent/` directory tree, compiles discovery output into `.eve/`, and serves a versioned HTTP protocol at `/eve/v1/session` with NDJSON streaming and `continuationToken` follow-ups. Neither repo depends on the other; choose one authoring model and runtime contract per project. ## Workspace layout | Repository | Package | CLI binary | Primary artifact | | ---------- | ------- | ---------- | ---------------- | | `withastro-flue/` | `@flue/runtime`, `@flue/cli`, `@flue/sdk` | `flue` | Built server under `/dist` | | `vercel-eve/` | `eve` | `eve` | Compiled `.eve/` + host output `.output/` | `withastro-flue/` is the primary repository in this workspace. `vercel-eve/` ships alongside it for cross-framework comparison and Eve-specific docs pages. Both are BYOC/BYOK: model providers, API keys, and external services are registered or configured in project code—not locked to a single vendor. ## Runtime assumptions | Requirement | Flue | Eve | | ----------- | ---- | --- | | Node.js | `>=22` | `>=24` | | Package manager | `pnpm >=11` (monorepo) | `pnpm` (monorepo) | | TypeScript | Required for agent/workflow modules | Required; `agent.ts` and `tools/` are TypeScript | | Default dev port | `3583` (`flue dev`) | Nitro dev server (fixture scripts use `eve dev`) | Flue requires an explicit build target (`node` or `cloudflare`) in `flue.config.*` or via `--target`. Eve scaffolds a full app with `eve init` and runs local discovery through `eve dev` / `eve info` without a separate target flag. ## What Flue exposes Flue is a programmable agent harness: TypeScript modules define agents, workflows, channels, sandboxes, and HTTP composition. The `@flue/runtime` barrel exports `createAgent`, `defineAgentProfile`, `defineTool`, `dispatch`, provider registration, and inspection helpers (`listAgents`, `listRuns`, `getRun`). Routing lives on `@flue/runtime/routing` as `flue()`, a mountable Hono sub-app. ### Authoring surfaces Flue discovers modules from a resolved source root. Precedence is `/.flue/` when present, else `/src/`, else `/`: | Path (under source root) | Export contract | HTTP surface | | ------------------------ | --------------- | ------------ | | `agents/.ts` | Default export: `createAgent(...)` | `POST/GET /agents/:name/:id` when module exports `route` | | `workflows/.ts` | Named export `run(ctx)` | `POST /workflows/:name` when module exports `route` | | `channels/.ts` | Channel module | `ALL /channels/:name` and `/channels/:name/*` | | `app.ts` | Default export: Hono app mounting `flue()` | Custom routes alongside Flue API | | `flue.config.ts` | `defineConfig({ target, root, output })` | Build-time only | Build-time config (`target`, `root`, `output`) stays in `flue.config.*`. Runtime provider registration (`registerProvider`) belongs in `app.ts` because keys often come from `process.env`. ### Terminology ``` Agent profile → defineAgentProfile(...) Created agent → createAgent(...) Agent module → agents/.ts AgentInstance → URL Harness → init(agent) return value Session → harness.session(name?) Operation → session.prompt / skill / task / shell Turn → one LLM round-trip Workflow → workflows/.ts; export run(...) Workflow run → unique ctx.id (runId); /runs and flue logs inspect these only ``` Runs are workflow-only. Direct agent prompts and channel dispatches use persistent sessions and are not runs. ### CLI entry points ```bash flue dev # long-running watch-mode server flue run # one-shot build + invoke flue connect # interactive agent session flue build # production artifact to dist/ flue init --target flue logs # tail/replay workflow run events ``` ### HTTP API (via `flue()`) | Method | Path | Role | | ------ | ---- | ---- | | `GET` | `/openapi.json` | OpenAPI spec | | `POST` | `/agents/:name/:id` | Admit prompt (`?wait=result` for sync JSON) | | `GET/HEAD` | `/agents/:name/:id` | Durable Streams event read | | `POST` | `/workflows/:name` | Start workflow run (`?wait=result` optional) | | `GET/HEAD` | `/runs/:runId` | Workflow run event stream | | `ALL` | `/channels/:name` | Verified channel webhooks | Persistence adapters (`PersistenceAdapter`, session stores) are authored against `@flue/runtime/adapter`, separate from the root barrel. ## What Eve exposes Eve is a filesystem-first framework for durable backend agents. Authored files under `agent/` are the contract; path-derived names replace registries. The published package is `eve`; the CLI binary is `eve`. ### Authoring slots under `agent/` | Path | Purpose | | ---- | ------- | | `agent.ts` | `defineAgent({ model, name, ... })` — additive runtime config | | `instructions.md` / `instructions.ts` | Always-on system prompt (required on root agent) | | `tools/` | `defineTool` modules; name from filename | | `skills/` | On-demand procedures (Markdown or modules) | | `connections/` | External MCP/OpenAPI connections | | `channels/` | HTTP and messaging ingress (root-only) | | `sandbox/` | Per-agent sandbox override and workspace seeds | | `subagents/` | Specialist child agents under `subagents//` | | `schedules/` | Recurring jobs (root-only) | | `lib/` | Shared import-only code | Identity comes from paths: `agent/tools/get_weather.ts` resolves to tool `get_weather` with no separate `name` field. ### Runtime split Eve separates three layers: - **Channel** — normalizes inbound transport, applies auth/delivery policy, owns `continuationToken` - **Harness** — executes one unit of AI work, returns `{ session, next }` - **Runtime** — persists state, follows `next`, streams NDJSON events, owns workflow orchestration Public HTTP therefore exposes two handles: - `continuationToken` — send the next user message to the same conversation - `sessionId` — attach to the event stream and inspect a run Durability is implemented on the open-source Workflow SDK; Eve checkpoints progress at step boundaries so tools, sandboxes, and subagents feel synchronous inside a durable session. ### CLI entry points ```bash eve init [target] # scaffold new agent (or add to existing package.json) eve dev # local runtime + terminal UI eve info # discovery results and .eve/ artifacts eve build # compile .eve/ and build host output eve start # serve built .output/ app eve link / eve deploy # Vercel project linking and production deploy eve eval # run eval suites eve channels add|list # scaffold or list channel integrations ``` Compiled artifacts land under `.eve/discovery/` and `.eve/compile/` (manifests, module map, diagnostics). `eve info` surfaces these paths for inspection. ### HTTP protocol (`/eve/v1`) | Route | Role | | ----- | ---- | | `POST /eve/v1/session` | Create session; returns `sessionId` + `continuationToken` | | `POST /eve/v1/session/:sessionId` | Follow-up with `continuationToken` (+ message or `inputResponses`) | | `GET /eve/v1/session/:sessionId/stream` | NDJSON event stream (`application/x-ndjson`) | | `GET /eve/v1/info` | JSON inspection payload | | `GET /eve/v1/health` | Health check | Stream events include `session.started`, `turn.started`, `actions.requested`, `action.result`, `input.requested`, `subagent.called`, `message.appended`, `turn.completed`, `session.waiting`, and terminal failure/completion events. Clients reconnect to the stream by `sessionId`; they resume conversation turns with `continuationToken`. Public authoring helpers export from `eve` (`defineAgent`) and subpaths such as `eve/tools` (`defineTool`), `eve/skills`, `eve/connections`, and channel packages under `eve/channels/*`. ## How the frameworks differ ```mermaid flowchart TB subgraph flue ["Flue (withastro/flue)"] FC["flue.config.ts
target, root, output"] FS["Source root
.flue/ → src/ → root"] AM["agents/*.ts
createAgent"] WM["workflows/*.ts
run(ctx)"] CM["channels/*.ts"] APP["app.ts
Hono + registerProvider"] API["flue() routes
/agents /workflows /runs /channels"] FC --> FS FS --> AM & WM & CM & APP APP --> API end subgraph eve ["Eve (vercel/eve)"] AG["agent/
filesystem slots"] DISC["Discovery → .eve/"] CH["Channel layer
continuationToken"] HAR["Harness
one AI unit"] RT["Runtime
sessionId + NDJSON stream"] HTTP["/eve/v1/session*"] AG --> DISC --> CH --> HAR --> RT --> HTTP end ``` | Concern | Flue | Eve | | ------- | ---- | --- | | Primary unit of work | Agent session operations; workflow **runs** for scripted automation | Durable **session turns** across HTTP follow-ups | | Discovery | TypeScript modules by filename under source root | Path-derived slots under `agent/` | | Instructions | Inline string or imported `SKILL.md` in `createAgent` | `instructions.md` (filesystem contract) | | Workflow concept | First-class `workflows/.ts` with `run()` and `runId` telemetry | Workflow SDK under the hood; orchestration owned by runtime | | Streaming | Durable Streams on `/agents/...` and `/runs/:runId` | NDJSON on `/eve/v1/session/:sessionId/stream` | | Deploy targets | Node.js, Cloudflare Workers (+ ecosystem adapters) | Vercel-first (`eve deploy`); local Nitro host via `eve dev` / `eve start` | | Client SDK | `@flue/sdk` (`createFlueClient`, `invoke`) | TypeScript SDK and framework bindings (Next.js, Nuxt, SvelteKit) | Both frameworks support tools, skills, sandboxes, subagents, MCP connections, and channel ingress. Flue adds explicit workflow modules and workflow-only run history; Eve optimizes for markdown-first authoring and a stable session protocol with separated continuation and stream identifiers. ## Shortest paths in From `withastro-flue/examples/hello-world/`: ```bash pnpm install flue dev --target node flue run hello --target node ``` `hello` workflow initializes an agent via `init(agent)`, opens a session, and runs `session.prompt`. Use `flue connect session-test local` for an interactive agent instance. From `vercel-eve/apps/fixtures/weather-agent/`: ```bash pnpm install eve dev ``` In another terminal, create a session: ```bash curl -X POST http://127.0.0.1:3000/eve/v1/session \ -H 'content-type: application/json' \ -d '{"message":"What is the weather in San Francisco?"}' ``` Use the returned `sessionId` to open `GET /eve/v1/session//stream`. Run `eve info` to inspect discovery and `.eve/` compile output. Model strings are provider-neutral in both frameworks. Flue sets `model` in `createAgent(() => ({ model: "provider/model" }))` or per-call prompt options. Eve sets `model` in `defineAgent({ model: "provider/model" })` inside `agent/agent.ts`. ## Monorepo packages (reference) **Flue** core packages in `withastro-flue/packages/`: | Package | Role | | ------- | ---- | | `@flue/runtime` | Harness, sessions, tools, sandbox, `flue()` routing | | `@flue/cli` | Build graph, discovery, `flue` binary | | `@flue/sdk` | HTTP client for deployed agents and workflows | | `@flue/postgres`, `@flue/mysql`, … | Optional `PersistenceAdapter` backends | | Channel packages (`@flue/slack`, …) | Provider webhook blueprints | **Eve** ships as a single `eve` package with compiled `dist/`, bundled docs, and framework entry points (`eve/tools`, `eve/channels/slack`, `eve/nuxt`, etc.). Fixtures and templates live under `vercel-eve/apps/`. ## Related pages Prerequisites, Node engine requirements, and first-install commands for both frameworks. Scaffold, `flue dev`, `flue run`, and `flue connect`. `eve init`, `eve dev`, `eve info`, and the first session POST. Compare Flue sessions and workflow runs with Eve sessions, turns, and token contracts. Source-root resolution, agents, workflows, and `app.ts`. Authored slots under `agent/` and path-derived naming.