From d01b8b5d73de2b9763f942fd187716ed3f82ce5b Mon Sep 17 00:00:00 2001 From: Magnus Hedemark Date: Thu, 16 Jul 2026 00:40:12 -0400 Subject: [PATCH] feat: add Vercel Eve skill Adds the public Vercel Eve Agent Skill, validated through three autonomous greenfield SkillOpt epochs and exact-head CI.\n\nAI-assisted contribution; binding self-review recorded on PR #55. --- AGENTS.md | 1 + README.md | 4 + vercel-eve/README.md | 44 ++++++ vercel-eve/SKILL.md | 129 ++++++++++++++++++ vercel-eve/evals/evals.json | 34 +++++ .../references/deployment-and-self-hosting.md | 57 ++++++++ .../development-and-architecture.md | 44 ++++++ vercel-eve/references/source-index.md | 12 ++ 8 files changed, 325 insertions(+) create mode 100644 vercel-eve/README.md create mode 100644 vercel-eve/SKILL.md create mode 100644 vercel-eve/evals/evals.json create mode 100644 vercel-eve/references/deployment-and-self-hosting.md create mode 100644 vercel-eve/references/development-and-architecture.md create mode 100644 vercel-eve/references/source-index.md diff --git a/AGENTS.md b/AGENTS.md index f24b341..2170047 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,6 +153,7 @@ When the user mentions these keywords, load the corresponding skill: | "c4-diagramming", "c4 diagramming" | [c4-diagramming](c4-diagramming/SKILL.md) | | "technology-radar", "technology radar" | [technology-radar](technology-radar/SKILL.md) | | "strategy", "strategic planning", "OKRs", "strategic narrative", "Five Forces", "Blue Ocean", "competitive positioning", "moat", "Ansoff", "Three Horizons", "market entry", "capital allocation", "M&A evaluation", "BCG Matrix", "portfolio management" | [strategy-frameworks](strategy-frameworks/SKILL.md) | +| "Vercel Eve", "eve agent", "eve dev", "eve build", "eve start", "Eve self-hosting", "durable Eve session", "Eve sandbox", "Eve Workflow", "Eve subagent", "Eve agent skills", "Eve deployment", "Eve reverse proxy" | [vercel-eve](vercel-eve/SKILL.md) | | "verification-methodology", "verification methodology" | [verification-methodology](verification-methodology/SKILL.md) | | "accessibility", "a11y", "WCAG", "ARIA", "accessible name", "screen reader", "keyboard navigation", "focus management", "focus trap", "dialog", "modal", "combobox", "listbox", "accessible form", "form validation", "error recovery", "accessible authentication", "color contrast", "reduced motion", "target size", "accessibility testing" | [web-accessibility](web-accessibility/SKILL.md) | | "seo-audit", "seo audit" | [seo-audit](seo-audit/SKILL.md) | diff --git a/README.md b/README.md index 89213ee..e4b65f1 100644 --- a/README.md +++ b/README.md @@ -329,6 +329,10 @@ Trakt.tv media discovery from the terminal. Browse trending, anticipated, and po Transistor.fm podcast hosting from the terminal. Manage shows and episodes, view subscriber analytics. API key from transistor.fm settings. +### [vercel-eve](vercel-eve/SKILL.md) + +Build, deploy, self-host, secure, and troubleshoot durable backend AI agents with Vercel Eve. Covers the filesystem-first agent project, typed tools, skills, subagents, connections, sandboxes, durable sessions, Vercel deployment, and the operational contracts required for a Node-hosted deployment. + ### [verification-methodology](verification-methodology/SKILL.md) Replace completion claims with a disciplined evidence trail that shows what was checked, what passed, and what remains uncertain. diff --git a/vercel-eve/README.md b/vercel-eve/README.md new file mode 100644 index 0000000..6ace70b --- /dev/null +++ b/vercel-eve/README.md @@ -0,0 +1,44 @@ +# Vercel Eve skill + +Build and operate durable AI agents with Vercel Eve, including the parts that matter when you leave Vercel’s managed platform. + +## Why Install This Skill + +Eve makes an agent legible: instructions, tools, skills, subagents, integrations, schedules, and sandboxing live in predictable files. That gives an agent project the shape of an application rather than a pile of prompts and callbacks. + +The hard part is deployment. This skill keeps the distinction clear between “the Node server started” and “durable agent work survives restart, resumes through the proxy, protects credentials, and produces usable traces.” It covers both Vercel and self-hosted Node deployments. + +## What You Get + +| Resource | Purpose | +|---|---| +| `SKILL.md` | Development, deployment, security, and verification workflow | +| `references/development-and-architecture.md` | Agent-directory model, tools, skills, subagents, connections, sandboxing, and observability | +| `references/deployment-and-self-hosting.md` | Vercel versus Node hosting, persistent workflow state, reverse proxy, model, auth, scheduling, and validation requirements | +| `references/source-index.md` | Official documentation and repository sources | +| `evals/evals.json` | Representative skill-quality scenarios | + +## Quick Start + +```sh +npx eve@latest init my-agent +cd my-agent +npm run dev +``` + +For a self-hosted service: + +```sh +eve build +PORT=3000 eve start --host 0.0.0.0 +``` + +Do not expose it until persistent workflow storage, authentication, proxy routes, and a real session have been verified. + +## Triggers + +Use this skill when building an Eve agent, adding tools or skills, configuring subagents, sandboxes, sessions, schedules, channels, connections, telemetry, Vercel deployment, or self-hosted Eve infrastructure. + +## Requirements + +Current Eve requires Node.js 24+. An agent needs an LLM provider credential or AI Gateway access. Production self-hosting also needs persistent storage for workflow state, an authentication policy, and an appropriate sandbox backend for any generated command or code execution. \ No newline at end of file diff --git a/vercel-eve/SKILL.md b/vercel-eve/SKILL.md new file mode 100644 index 0000000..c77ad22 --- /dev/null +++ b/vercel-eve/SKILL.md @@ -0,0 +1,129 @@ +--- +name: vercel-eve +description: >- + Build, develop, deploy, self-host, secure, and troubleshoot durable backend AI agents with Vercel Eve. Use when creating an Eve agent, adding tools, skills, subagents, channels, schedules, sandboxing, durable sessions, observability, or deploying Eve on Vercel or a Node host. Do not use for the separate Vercel AI SDK Agent APIs such as ToolLoopAgent or WorkflowAgent; use an AI SDK-specific skill for those. +license: MIT +compatibility: Requires Node.js 24+ for the current Eve package. Deployment requires an LLM provider credential or Vercel AI Gateway access; self-hosted durable execution requires persistent workflow storage. +metadata: + source: https://github.com/vercel/eve + research_checked: "2026-07-15" +--- + +# Vercel Eve + +Eve is a filesystem-first framework for durable backend agents. Treat the `agent/` directory as the application boundary and the deployment as a composition of independently replaceable HTTP, workflow, sandbox, model, credential, and observability layers. + +## Operating contract + +1. Start with the generated project structure. Put agent behavior in `agent/instructions.md`, runtime choices in `agent/agent.ts`, and one typed capability per file under its relevant directory. +2. Keep authority outside the model prompt. Use typed tools, connections, sandbox boundaries, and route authentication instead of placing credentials or policy in instructions. +3. Treat a durable session as a workflow, not an in-memory chat. Define persistence, idempotency, callback reachability, and recovery before relying on long-running or side-effecting work. +4. On self-hosted deployments, replace every Vercel service deliberately. A Node process that starts is not evidence that workflow callbacks, persisted state, schedules, sandbox isolation, authentication, and telemetry work. +5. Verify with a health request and a real authenticated session that exercises the workflow path. Never treat an HTTP 200 alone as a production readiness signal. + +## When not to use + +Do not load this for the separate `ai` package’s `ToolLoopAgent`, `WorkflowAgent`, or `HarnessAgent` APIs. Do not use it for generic Next.js deployment without an Eve agent. For vendor-neutral workflow orchestration, use the relevant workflow or agent-framework skill instead. + +When such a request appears, say that Eve does not apply and route to current AI SDK documentation or an AI SDK-specific skill. Do not write AI SDK API code, model configuration, or deployment guidance from this skill. + +## Project model + +| Need | Default location | +|---|---| +| Always-on behavior | `agent/instructions.md` | +| Model and runtime options | `agent/agent.ts` | +| Typed actions | `agent/tools/*.ts` | +| On-demand procedures | `agent/skills/` | +| Narrower child agents | `agent/subagents/` | +| HTTP, Slack, or other entry points | `agent/channels/` | +| Typed external integrations | `agent/connections/` | +| Isolated compute | `agent/sandbox/` | +| OpenTelemetry setup | `agent/instrumentation.ts` | +| Recurring work | `agent/schedules/` | + +Read [development and architecture](references/development-and-architecture.md) before creating or restructuring an agent. + +## Quick start + +```sh +npx eve@latest init my-agent +cd my-agent +npm run dev +``` + +Use the generated README and package scripts as the local source of truth. A minimal runtime configuration selects a model: + +```ts +import { defineAgent } from "eve"; + +export default defineAgent({ + model: "anthropic/claude-opus-4.8", +}); +``` + +On Vercel, a string model ID routes through AI Gateway and can use project OIDC. Outside Vercel, either configure `AI_GATEWAY_API_KEY` or use an AI SDK provider object with the provider’s normal credential. Do not assume that BYOK means the Gateway is bypassed. + +## Build capabilities deliberately + +### Tools + +A tool is a typed boundary between model reasoning and an external action. Give it a narrow schema and a description that makes the authorization and side-effect boundary clear. A tool declares typed inputs, outputs, and side effects. It does not hold credentials or grant authority: keep integration credentials in connections and enforce authorization server-side before the effect occurs. + +```ts +import { defineTool } from "eve/tools"; +import { z } from "zod"; + +export default defineTool({ + description: "Look up a city’s current weather.", + inputSchema: z.object({ city: z.string().min(1) }), + async execute({ city }) { + return { city, condition: "Sunny" }; + }, +}); +``` + +Use a skill for larger procedures that should load only when relevant. Use a subagent when the work needs a fresh history, narrower toolset, or isolated intermediate state. + +### Credentials and execution + +Use `agent/connections/` for typed service integrations. Use `agent/sandbox/` for generated code or shell work. Never place provider keys, OAuth tokens, or route-auth secrets in instructions, tool source, generated artifacts, or logs. + +For sandbox design and lifecycle choices, read [development and architecture](references/development-and-architecture.md). For self-hosting backends and routing, read [deployment and self-hosting](references/deployment-and-self-hosting.md). + +## Deploy + +### Vercel + +Use a Git-connected project or `vercel deploy`. Eve emits Vercel Build Output, uses Vercel Workflows for durable sessions, and normally selects Vercel Sandbox. Replace scaffolded placeholder authentication before exposing a browser-facing route. + +### Self-hosted Node service + +```sh +eve build +PORT=3000 eve start --host 0.0.0.0 +``` + +This uses the normal Nitro Node output under `.output/`. Before production traffic, read [deployment and self-hosting](references/deployment-and-self-hosting.md) and explicitly verify persistent workflow storage, sandbox backend, model credential path, authentication, the `/eve/` and `/.well-known/workflow/` proxy prefixes, schedule execution, and telemetry. + +Treat host paths, reverse-proxy product configuration, storage product, and scheduler implementation as target-specific evidence. If the target topology is not supplied or inspected, name the required contract and the missing evidence rather than inventing a configuration. + +## Security and observability + +- Replace placeholder authentication with a real policy before any production browser request. Outside Vercel, do not rely on `vercelOidc()` as the sole authenticator. +- Give sandboxes the minimum network and credential access required. A sandbox does not protect secrets that are deliberately injected into it. +- Vercel Agent Runs is convenient, but treat OpenTelemetry as the portable operational evidence path. Set `recordInputs` or `recordOutputs` to `false` when traces would contain sensitive data. +- For personal, sensitive, or regulated data, assess what model inputs, tool arguments, outputs, and traces are retained and disclose collection where required. + +## Verification gate + +1. Build the deployed artifact. +2. Confirm the health endpoint: `GET /eve/v1/health`. +3. Start one authenticated session: `POST /eve/v1/session`. +4. Attach to its stream and verify a real turn completes. +5. For self-hosting, exercise a durable workflow callback or resume path, not only a stateless reply. +6. Inspect the trace and ensure secrets and sensitive payloads are absent or intentionally redacted. + +## Exit criteria + +The task is complete only when the requested agent capability is implemented, its route and authorization boundary are explicit, and the relevant local or deployed session path has been exercised with evidence. See [source index](references/source-index.md) when validating version-sensitive behavior. \ No newline at end of file diff --git a/vercel-eve/evals/evals.json b/vercel-eve/evals/evals.json new file mode 100644 index 0000000..d878c3f --- /dev/null +++ b/vercel-eve/evals/evals.json @@ -0,0 +1,34 @@ +{ + "skill_name": "vercel-eve", + "evals": [ + { + "id": "self-hosted-durable-agent", + "prompt": "Deploy our Eve agent behind Traefik on a Node VM. It must survive restart and run a nightly schedule.", + "expected_output": "A deployment plan that requires persistent Workflow storage, both proxy prefixes, an explicit sandbox backend, host authentication, schedule execution, and an authenticated session-plus-resume verification path.", + "assertions": [ + "Names both /eve/ and /.well-known/workflow/ proxy prefixes", + "Requires persistent workflow state rather than ephemeral container storage", + "Does not treat a health check as sufficient verification" + ] + }, + { + "id": "direct-provider-without-gateway", + "prompt": "Use Eve on our own server with Anthropic directly. We do not want requests routed through Vercel AI Gateway.", + "expected_output": "Instructions to use an AI SDK Anthropic provider model object and ANTHROPIC_API_KEY rather than a string Gateway model ID.", + "assertions": [ + "Distinguishes a direct provider model object from a string model ID", + "Does not claim BYOK bypasses the Gateway", + "Keeps credentials out of source files" + ] + }, + { + "id": "near-miss-ai-sdk", + "prompt": "Add a ToolLoopAgent to our AI SDK app and make it durable.", + "expected_output": "Routes to an AI SDK-specific workflow rather than treating ToolLoopAgent as an Eve API.", + "assertions": [ + "States that ToolLoopAgent belongs to the separate AI SDK API", + "Does not invent an Eve-specific ToolLoopAgent configuration" + ] + } + ] +} diff --git a/vercel-eve/references/deployment-and-self-hosting.md b/vercel-eve/references/deployment-and-self-hosting.md new file mode 100644 index 0000000..b0fe8e3 --- /dev/null +++ b/vercel-eve/references/deployment-and-self-hosting.md @@ -0,0 +1,57 @@ +# Deployment and self-hosting + +## Deployment modes + +| Concern | Vercel deployment | Self-hosted Node deployment | +|---|---|---| +| HTTP host | Vercel Functions / Build Output | Nitro `.output/` served by `eve start` | +| Durable execution | Vercel Workflows | Local Workflow world by default, or compatible custom world | +| Session state | Managed Workflow storage | `.eve/.workflow-data` unless an external compatible world is selected | +| Sandbox | Vercel Sandbox by default | `defaultBackend()`, Docker, microsandbox, or custom backend | +| Model credential | Gateway via Vercel OIDC | Gateway API key or direct AI SDK provider key | +| Dashboard | Agent Runs | External OpenTelemetry backend | +| Schedules | Vercel Cron wiring | Nitro schedule runner or the operator’s scheduler | + +Eve can self-host. The portability comes from separate HTTP, workflow, and sandbox adapters, not from removing those responsibilities. + +## Build and start + +```sh +eve build +PORT=3000 eve start --host 0.0.0.0 +``` + +On Vercel, `eve build` emits `.vercel/output`. On a standard Node host, it emits the normal Nitro `.output/` plus Eve’s `.eve/` compilation artifacts. + +## Mandatory self-hosting checklist + +1. **Workflow persistence:** Put `.eve/.workflow-data` on durable storage, or select a compatible Workflow world package. Ephemeral container filesystems do not provide durable sessions. +2. **Reverse proxy:** Forward both `/eve/` and `/.well-known/workflow/`. The latter carries workflow callbacks; omitting it can start a session and then silently stall execution. +3. **Sandbox:** Leave `defaultBackend()` in place for the local default, select Docker or microsandbox explicitly, or provide a custom adapter. Do not pin `vercel()` for a host that should not create Vercel Sandboxes. +4. **Model route:** Use `AI_GATEWAY_API_KEY` for Gateway routing, or use a direct provider object plus its provider credential to remove Gateway dependency. +5. **Authentication:** Replace placeholder authentication. Do not use `vercelOidc()` as the only production authenticator outside Vercel; use Basic auth, JWT/OIDC validation for the host’s identity provider, or a custom verifier. +6. **Schedules:** Ensure the normal Nitro schedule runner is active, or trigger the equivalent work from an external scheduler. +7. **Observability:** Export OpenTelemetry to a reachable backend and redact sensitive capture when needed. +8. **Verification:** Test health, a real authenticated session, its stream, and a durable callback/resume path. + +## Common failures + +| Symptom | Likely cause | Check | +|---|---|---| +| Session starts but never progresses | Workflow callback route missing at the proxy | `/.well-known/workflow/` forwarding and upstream logs | +| Sessions disappear after restart | Workflow data on ephemeral disk | Volume mount or external Workflow world | +| Production endpoint rejects all requests | Placeholder auth still installed | Channel auth configuration and runtime secrets | +| Self-hosted deployment calls Vercel unexpectedly | Gateway string model or `vercel()` sandbox backend remains configured | `agent.ts` model shape and sandbox definition | +| Health is green but a real task fails | Only HTTP server checked | Authenticated session, stream, tool, callback, and trace evidence | + +## Verify + +```sh +curl https://example.test/eve/v1/health +curl -X POST https://example.test/eve/v1/session \ + -H 'content-type: application/json' \ + -d '{"message":"Hello from production"}' +curl https://example.test/eve/v1/session//stream +``` + +Use a real authentication mechanism when testing production. Confirm the trace shows the expected model, tool, workflow, and redaction behavior. \ No newline at end of file diff --git a/vercel-eve/references/development-and-architecture.md b/vercel-eve/references/development-and-architecture.md new file mode 100644 index 0000000..d78f46c --- /dev/null +++ b/vercel-eve/references/development-and-architecture.md @@ -0,0 +1,44 @@ +# Development and architecture + +## Authoring surface + +Eve discovers conventional files below `agent/` and compiles a manifest for the runtime. The files are the agent’s operational surface: + +| Path | Responsibility | +|---|---| +| `instructions.md` | Always-on system instructions | +| `agent.ts` | Model and runtime configuration | +| `tools/*.ts` | Typed model-callable actions; filename becomes tool name | +| `skills/` | Larger on-demand procedures and reference material | +| `subagents/` | Child agents with fresh state and their own configuration | +| `channels/` | HTTP, Slack, and other platform entry points | +| `connections/` | Typed external integrations and credential mediation | +| `sandbox/` | Isolated filesystem and command-execution configuration | +| `instrumentation.ts` | OpenTelemetry setup run at server startup | +| `schedules/` | Recurring work | + +Keep a capability in the smallest suitable boundary. A one-off action belongs in a tool. A reusable procedure belongs in a skill. Work with a fresh conversation, a narrower tool set, or potentially noisy intermediate state belongs in a subagent. + +## Sessions and durability + +A session is a durable conversation or task. Each message or external event creates a turn. On Vercel, Workflows persists an event log and replays it to reconstruct state across cold starts, deploys, and pauses. + +Do not infer application-level correctness from framework durability. External side effects must still be idempotent or guarded by a durable approval/receipt boundary. Decide what an interrupted tool call means before the agent can execute it twice. + +## Models and credentials + +A string `model` ID is AI-Gateway-routed. On Vercel, project OIDC can authenticate this path. Outside Vercel, use `AI_GATEWAY_API_KEY` if Gateway routing is desired. + +To avoid Gateway routing, install an AI SDK provider package and pass its model object, then use the provider’s normal environment credential. Keep that credential in the host environment or a secret manager, never in an agent file. + +## Tools, connections, and sandboxes + +A tool should make its input and side effects precise. Validate schema input at the tool boundary. Treat free-form shell, file mutation, outbound network access, and credential-bearing integrations as separate high-risk capabilities. + +Connections keep provider configuration and credentials outside prompts and generic tool implementation. Sandboxes constrain locally generated commands, but they do not repair an over-broad network policy or a secret injected into the sandbox. Choose the sandbox backend and policy before exposing tools that can execute commands. + +## Observability + +Vercel Agent Runs supplies a managed session and turn view. For portability, configure `agent/instrumentation.ts` to export AI SDK OpenTelemetry spans to the organization’s chosen backend. + +Trace capture can include message input, model output, tool arguments, and tool results. Use `recordInputs` and `recordOutputs` deliberately. Sensitive-data minimization is a configuration and policy decision, not an observability afterthought. diff --git a/vercel-eve/references/source-index.md b/vercel-eve/references/source-index.md new file mode 100644 index 0000000..c18ce62 --- /dev/null +++ b/vercel-eve/references/source-index.md @@ -0,0 +1,12 @@ +# Source index + +This skill is based on primary Vercel documentation and source code, checked 2026-07-15. + +- [Eve overview](https://vercel.com/docs/eve) — framework purpose, project layout, quick start, sessions, and platform services. +- [Eve concepts](https://vercel.com/docs/eve/concepts) — agent directories, sessions and turns, durability, channels, tools, skills, subagents, connections, sandbox, and observability. +- [Eve observability](https://vercel.com/docs/eve/observability) — Agent Runs, OpenTelemetry, trace content, and privacy implications. +- [Eve pricing and limits](https://vercel.com/docs/eve/pricing) — component-level resource usage and inherited limits. +- [Vercel Eve repository](https://github.com/vercel/eve) — Apache-2.0 source, CLI, package metadata, and current project examples. +- [Deployment guide](https://github.com/vercel/eve/blob/main/docs/guides/deployment.md) — Vercel and self-hosted deployment paths, persistent Workflow world, reverse proxy prefixes, sandbox backends, credentials, authentication, schedules, and verification. + +Verify model names, package versions, beta status, and platform limits against these sources before using them in an implementation or a production decision. \ No newline at end of file