Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: route coding agents to the page that answers the task (#2244)

OwenKephart33db9a42a56f
diff --git a/.changeset/bright-continuations-answer.md b/.changeset/bright-continuations-answer.md
new file mode 100644
index 000000000..56ec3910c
--- /dev/null
+++ b/.changeset/bright-continuations-answer.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Improve non-interactive setup recovery: `eve add` now reports terminal outcomes on every path and includes non-secret answer placeholders in blocked continuation commands. `eve link` and `eve deploy` also point non-interactive callers to eve's own project commands.
diff --git a/AGENTS.md b/AGENTS.md
index cf1beef42..4ca513f4c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -217,6 +217,10 @@ live under `packages/eve/test/tui-client` and run with `pnpm test:tui`. See
- When moving a published route, update authored links to the new URL and add a
permanent redirect from every old HTML and supported Markdown URL.
- Sidebar order lives in `docs/meta.json`.
+- Use Title Case for page `title` frontmatter and `meta.json` section titles
+ (Fumadocs renders `title` as both the sidebar entry and the `<h1>`), and
+ sentence case for in-page headings — capitalize only the first word plus
+ proper nouns and acronyms, e.g. `Next.js`, `CLI`, `agent.ts`.
- Keep markdown framework-agnostic — no MDX-only constructs unless the page is
`.mdx`.
diff --git a/docs/README.md b/docs/README.md
index 526616518..32e59d507 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,31 @@ Important naming note:
- The current published package name is `eve`.
- The CLI binary is `eve`.
+## Find the page for your task
+
+| To do this | Read this |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Create a project, or understand the file layout | [Getting Started](./getting-started.mdx) |
+| Set the model, reasoning, or other agent-wide config | [Agents](./agent-config.md) |
+| Change what the agent does and how it behaves | [Instructions](./instructions.mdx) |
+| Give the agent a typed capability it can call | [Tools](./tools/overview.mdx) |
+| Require approval, or ask the user something mid-turn | [Human in the Loop](./tools/human-in-the-loop.md) |
+| Call an external HTTP API or MCP server | [Connections](./connections/overview.mdx) |
+| Add a messaging surface (Slack, Discord, iMessage, …) | [Channels](./channels/overview.mdx) |
+| Expose your own HTTP route as a conversation surface | [Custom Channels](./channels/custom.mdx) |
+| Package a procedure the agent loads only when it applies | [Skills](./skills.mdx) |
+| Carry state across turns, or shape what the model sees | [State](./concepts/state.md), [Context Control](./concepts/context-control.md) |
+| Run commands or untrusted code in isolation | [Sandboxes](./sandbox.mdx) |
+| Delegate work to a specialist child agent | [Subagents](./subagents/index.mdx) |
+| Run work on a recurring schedule | [Schedules](./schedules.mdx) |
+| Install an existing integration instead of writing one | [Add Integrations](./install-integrations.mdx) |
+| Link a Vercel project and deploy to production | [Deploy to Vercel](./guides/deployment/vercel.mdx) |
+| Self-host, or compare hosting strategies | [Deployment](./guides/deployment/overview.md) |
+| Authorize routes, sessions, and per-user access | [Authentication](./guides/auth-and-route-protection.md) |
+| Build a web UI, or stream a session to a client | [Client SDK](./guides/client/overview.mdx), [Frontend](./guides/frontend/overview.mdx) |
+| Test the agent's behavior | [Evals](./evals/overview.mdx) |
+| Look up a CLI command or an exported type | [CLI](./reference/cli.md), [TypeScript API](./reference/typescript-api.md) |
+
## Legal and safeguards
eve is in preview; the framework, APIs, documentation, and behavior may change before general availability.
@@ -24,14 +49,9 @@ Require human approval or other safeguards for sensitive, irreversible, regulate
Unless you configure stricter controls, eve agents may operate with permissive settings, including tool execution without human approval where approval is omitted and sandbox network egress that is not deny-all. Do not rely on model behavior alone to prevent sensitive or irreversible actions.
-Casing convention:
-
-- Use Title Case for page `title` frontmatter and `meta.json` section titles (Fumadocs renders the page `title` as both the sidebar entry and the `<h1>`, so one casing covers both) — e.g. `Execution Model & Durability`, `Dynamic Capabilities`, `Build an Agent`.
-- Use sentence case for in-page headings (`##` and below). Capitalize only the first word plus proper nouns/acronyms — e.g. `Next.js`, `SvelteKit`, `Slack`, `GitHub`, `CLI`, `TypeScript API`, `agent.ts`.
-
## Read this first
-Read in this order:
+For a full picture rather than a single task, read in this order:
1. [Getting Started](./getting-started.mdx)
2. [Tutorial](./tutorial/first-agent.mdx)
@@ -100,8 +120,3 @@ session without leaking that routing identity into the HTTP client contract.
- Then learn the durable runtime model: HITL, session context, sessions, streaming, and
ID-addressed follow-ups and channel address routing.
- Then add advanced features: subagents, schedules, route protection, deployment.
-
-## Good companions in this repo
-
-- Weather-focused smoke/dev fixture: [`../apps/fixtures/weather-agent`](../apps/fixtures/weather-agent)
-- Public API source of truth: [`../packages/eve/src/public/index.ts`](../packages/eve/src/public/index.ts)
diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdx
index a7d1c40df..977a4099f 100644
--- a/docs/channels/custom.mdx
+++ b/docs/channels/custom.mdx
@@ -58,6 +58,8 @@ export default defineChannel({
});
```
+A route's `path` is its app URL; the channel filename does not prefix it. The route above answers at `POST /threads/:threadId/messages`, not `/support/threads/:threadId/messages`. Use a unique method-and-path pair for each route, and do not use the framework-owned `/eve/v1/*` namespace.
+
Each route receives these operation surfaces:
- `from(address)` binds `send`, `respond`, `cancel`, `compact`, `clear`, and `reset` to a channel-local continuation address.
diff --git a/docs/guides/deployment/vercel.mdx b/docs/guides/deployment/vercel.mdx
index ad001baf4..c95871bee 100644
--- a/docs/guides/deployment/vercel.mdx
+++ b/docs/guides/deployment/vercel.mdx
@@ -13,12 +13,14 @@ Link the agent directory to a Vercel project:
eve link
```
-The command links an existing project or creates one, then pulls its environment variables. In continuous integration (CI) environments, use the non-interactive Vercel command instead:
+The command links an existing project or creates one, then pulls its environment variables. For non-interactive use, name the project instead of picking it:
```bash
-vercel link --project your_project_name --yes --non-interactive
+eve link --project your_project_name --non-interactive
```
+Use `--team` as well when the account has access to more than one team. `eve link` creates the project if it doesn't exist yet.
+
## Configure credentials and auth
A string model ID routes requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). The deployment authenticates through project OpenID Connect (OIDC), so you don’t need a provider API key for that path.
@@ -57,6 +59,12 @@ eve deploy
`eve deploy` installs dependencies, runs `vercel deploy --prod`, and pulls the project environment after deployment. You can also push to a Git-connected Vercel project. Hosted Vercel builds set `VERCEL`, so `eve build` writes the deployment bundle under `.vercel/output`.
+For non-interactive use, confirm the production deploy up front. `--project` links first, so a new project needs no separate `eve link`:
+
+```bash
+eve deploy --project your_project_name --non-interactive --yes
+```
+
Vercel uses the generated output to configure these services:
- **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
diff --git a/docs/install-integrations.mdx b/docs/install-integrations.mdx
index 70844c496..e97a951bb 100644
--- a/docs/install-integrations.mdx
+++ b/docs/install-integrations.mdx
@@ -26,7 +26,19 @@ Some integrations package several independently installable components. For exam
When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the selected components' declared flows from the beginning.
-For non-interactive automation, run `eve add <item> --non-interactive`. Add `--yes` to accept recommended setup values and reduce setup round trips; explicit `--answer` values take precedence. Eve returns structured component, setup-input, or prerequisite instructions instead of prompting. Use the continuation command in the response and add the requested answer; it adds `--skip-install` once registry installation has completed; resupply any prior answers from the calling agent's state. Pass non-secret answers with repeatable `--answer 'key=<JSON value>'` options. Supply secrets through the integration's documented environment variable or secret store rather than command-line arguments.
+## Automate setup
+
+Use `eve add <item> --non-interactive` when a script or coding agent cannot answer terminal prompts. It prints NDJSON events and exits with a status you can branch on:
+
+| Exit code | Meaning |
+| --------- | ----------------------------------------------- |
+| `0` | Installation and setup completed. |
+| `1` | Installation or setup failed. |
+| `2` | Setup needs an answer or an unmet prerequisite. |
+
+On exit code `2`, read the final event and run its `next.command`. For a non-secret question, replace its `<JSON value>` placeholder with the answer you collected. Never pass a secret in `--answer`; use the environment variable or secret store the integration documents. Add `--yes` to accept recommended values; explicit answers take precedence.
+
+A setup may report `eve link` as a prerequisite. Run it, then retry the continuation. See [Deployment](./guides/deployment/vercel.mdx) for the non-interactive `eve link` and `eve deploy` forms.
## Find an integration
diff --git a/docs/schedules.mdx b/docs/schedules.mdx
index c180d6600..a464e0609 100644
--- a/docs/schedules.mdx
+++ b/docs/schedules.mdx
@@ -84,6 +84,10 @@ The agent does not have to deliver a message on every run. When a prompt makes d
A handler-form session runs on the same durable runtime engine as any other session, so it can park (durably suspend), for instance when the channel handoff is waiting for a Slack reply. Only markdown task mode is barred from waiting.
+## Session continuity
+
+Markdown schedules start a new session on every fire. Handler schedules do too, unless they send to an existing conversation, such as a Slack thread. Store data that must survive across fires outside session state.
+
## Trigger a schedule while iterating
The dev server mounts a one-shot dispatch route that fires a schedule by name, out of band, exactly once. Since `eve dev` never runs schedules on their cron cadence, this is how you trigger one without waiting for the next production tick.
diff --git a/packages/eve/src/cli/commands/deploy.ts b/packages/eve/src/cli/commands/deploy.ts
index e5cc9d715..9fb0c3cff 100644
--- a/packages/eve/src/cli/commands/deploy.ts
+++ b/packages/eve/src/cli/commands/deploy.ts
@@ -63,7 +63,7 @@ export async function runDeployCommand(
});
if (result.kind === "needs-link") {
logger.error(
- "This directory is not linked to a Vercel project. Run `eve link` first (or `vercel link --project <name> --yes --non-interactive` in CI), then re-run `eve deploy`.",
+ "This directory is not linked to a Vercel project. Run `eve link` first, or name the project on the deploy itself: `eve deploy --project <name-or-id> --non-interactive --yes`.",
);
process.exitCode = 1;
return;
diff --git a/packages/eve/src/cli/commands/init-target.integration.test.ts b/packages/eve/src/cli/commands/init-target.integration.test.ts
index cd7774126..011faa15b 100644
--- a/packages/eve/src/cli/commands/init-target.integration.test.ts
+++ b/packages/eve/src/cli/commands/init-target.integration.test.ts
@@ -30,6 +30,18 @@ describe("resolveInitTarget", () => {
});
});
+ it("rejects targets that traverse outside the parent directory", async () => {
+ const parentDirectory = await createScratchDirectory("eve-init-target-parent-");
+
+ await expect(resolveTarget(parentDirectory, "../escaped")).rejects.toThrow(
+ "Project name can only contain",
+ );
+ await expect(resolveTarget(parentDirectory, "apps/../escaped")).resolves.toMatchObject({
+ kind: "fresh",
+ projectPath: join(parentDirectory, "escaped"),
+ });
+ });
+
it("preserves the small environment-only allowlist", async () => {
const parentDirectory = await createScratchDirectory("eve-init-target-environment-");
const projectPath = join(parentDirectory, "weather");
diff --git a/packages/eve/src/cli/commands/init-target.ts b/packages/eve/src/cli/commands/init-target.ts
index 816ad08f5..5a1e330cb 100644
--- a/packages/eve/src/cli/commands/init-target.ts
+++ b/packages/eve/src/cli/commands/init-target.ts
@@ -1,8 +1,8 @@
import { readdir, stat } from "node:fs/promises";
-import { basename, resolve } from "node:path";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
import { classifyAgentRootEntry, getDirectoryEntryType } from "#discover/filesystem.js";
-import { parseProjectName } from "#setup/project-name.js";
+import { parseProjectName, PROJECT_NAME_ERROR } from "#setup/project-name.js";
import type { InitFailurePolicy } from "./init-recovery.js";
@@ -73,11 +73,23 @@ function listEntries(entries: readonly string[]): string {
return entries.map((entry) => ` - ${entry}`).join("\n");
}
+function assertTargetStaysWithinParent(
+ parentPath: string,
+ target: string | undefined,
+ projectPath: string,
+): void {
+ if (target === undefined || isAbsolute(target)) return;
+ const relativeTarget = relative(parentPath, projectPath);
+ if (relativeTarget === ".." || relativeTarget.startsWith(`..${sep}`))
+ throw new Error(PROJECT_NAME_ERROR);
+}
+
/** Classifies the target itself without walking ancestor projects. */
export async function resolveInitTarget(input: ResolveInitTargetInput): Promise<InitTarget> {
const parentPath = resolve(input.parentDirectory);
const targetProvided = input.target !== undefined;
const projectPath = resolve(parentPath, input.target ?? ".");
+ assertTargetStaysWithinParent(parentPath, input.target, projectPath);
const createInPlace = projectPath === parentPath;
const kind = await pathKind(projectPath);
diff --git a/packages/eve/src/cli/commands/init.integration.test.ts b/packages/eve/src/cli/commands/init.integration.test.ts
index e308e43ef..9588ff939 100644
--- a/packages/eve/src/cli/commands/init.integration.test.ts
+++ b/packages/eve/src/cli/commands/init.integration.test.ts
@@ -746,7 +746,7 @@ describe("runInitCommand", () => {
const projectPath = join(parentDirectory, "my-agent");
expect(stripAnsi(output.errors.join("\n"))).toContain(
- `Git initialization failed during commit: commit refused\nThe Git repository and staged files were preserved at "${projectPath}".\n\nResolve the Git error above, then retry:\n git -C ${JSON.stringify(projectPath)} commit -m "Initial commit from eve"`,
+ `Git initialization failed during commit: commit refused\nThe eve agent was created successfully. Git repository metadata and staged files were preserved at "${projectPath}"; the initial commit is optional.\n\nTo create it later, configure Git identity and run:\n git -C ${JSON.stringify(projectPath)} commit -m "Initial commit from eve"`,
);
expect(deps.spawnPackageManager).toHaveBeenCalledWith("pnpm", projectPath, [
"--config.minimum-release-age=0",
diff --git a/packages/eve/src/cli/commands/init.ts b/packages/eve/src/cli/commands/init.ts
index 4c00a1cfb..f0bcbee88 100644
--- a/packages/eve/src/cli/commands/init.ts
+++ b/packages/eve/src/cli/commands/init.ts
@@ -615,7 +615,7 @@ export async function runInitCommand(
if (result.gitResult.stage === "commit") {
logger.error(
pc.yellow(
- `The Git repository and staged files were preserved at "${result.projectPath}".\n\nResolve the Git error above, then retry:\n git -C ${JSON.stringify(result.projectPath)} commit -m "Initial commit from eve"`,
+ `The eve agent was created successfully. Git repository metadata and staged files were preserved at "${result.projectPath}"; the initial commit is optional.\n\nTo create it later, configure Git identity and run:\n git -C ${JSON.stringify(result.projectPath)} commit -m "Initial commit from eve"`,
),
);
}
diff --git a/packages/eve/src/cli/commands/link.ts b/packages/eve/src/cli/commands/link.ts
index 2359adb3a..30db88a83 100644
--- a/packages/eve/src/cli/commands/link.ts
+++ b/packages/eve/src/cli/commands/link.ts
@@ -44,7 +44,7 @@ export async function runLinkCommand(
}
if (!dependencies.hasInteractiveTerminal()) {
logger.error(
- "`eve link` needs an interactive terminal to pick the team and project. In CI, run `vercel link --project <name> --yes --non-interactive` instead.",
+ "`eve link` needs an interactive terminal to pick the team and project. Name the project instead: `eve link --project <name-or-id> --non-interactive`.",
);
process.exitCode = 1;
return;
diff --git a/packages/eve/src/cli/commands/registry-declared-setups.ts b/packages/eve/src/cli/commands/registry-declared-setups.ts
index 64bd306ab..e57eb0e99 100644
--- a/packages/eve/src/cli/commands/registry-declared-setups.ts
+++ b/packages/eve/src/cli/commands/registry-declared-setups.ts
@@ -66,7 +66,12 @@ export async function runDeclaredSetups(input: {
installed: true,
completedItems: [],
...result.blocker,
- next: headlessSetupContinuation({ item: input.item, installed: true }),
+ next: headlessSetupContinuation({
+ item: input.item,
+ installed: true,
+ question:
+ result.blocker.status === "input_required" ? result.blocker.question : undefined,
+ }),
}),
);
process.exitCode = 2;
diff --git a/packages/eve/src/cli/commands/registry-package.ts b/packages/eve/src/cli/commands/registry-package.ts
index 137bf949f..82667b773 100644
--- a/packages/eve/src/cli/commands/registry-package.ts
+++ b/packages/eve/src/cli/commands/registry-package.ts
@@ -84,6 +84,7 @@ async function selectComponents(
throw error;
const question = (error as import("#setup/ask.js").InteractionRequired).question;
const { setupQuestionToWire } = await import("#setup/setup-question-wire.js");
+ const wireQuestion = setupQuestionToWire(question);
logger.error(
serializeHeadlessSetupEvent({
version: 1,
@@ -92,8 +93,8 @@ async function selectComponents(
item,
installed: false,
completedItems: [],
- question: setupQuestionToWire(question),
- next: headlessSetupContinuation({ item, installed: false }),
+ question: wireQuestion,
+ next: headlessSetupContinuation({ item, installed: false, question: wireQuestion }),
}),
);
process.exitCode = 2;
diff --git a/packages/eve/src/cli/commands/registry.test.ts b/packages/eve/src/cli/commands/registry.test.ts
index 90e14e648..872e2e582 100644
--- a/packages/eve/src/cli/commands/registry.test.ts
+++ b/packages/eve/src/cli/commands/registry.test.ts
@@ -128,6 +128,20 @@ describe("registry commands", () => {
expect(logger.errors).toEqual([]);
});
+ it("reports completion after installing an item without setup headlessly", async () => {
+ const logger = createLogger();
+ getRegistryItems.mockResolvedValue([{ name: "extension/browser", type: "registry:item" }]);
+
+ await runAddCommand(logger, "/project", "extension/browser", { nonInteractive: true });
+
+ expect(JSON.parse(logger.logs[0]!)).toEqual({
+ version: 1,
+ type: "completed",
+ item: "extension/browser",
+ completedItems: ["extension/browser"],
+ });
+ });
+
it("suggests matching registry items when an item is not found", async () => {
const logger = createLogger();
getRegistryItems.mockRejectedValue(
@@ -261,7 +275,10 @@ describe("registry commands", () => {
item: "linear",
installed: false,
question: { key: "components" },
- next: { command: "eve", args: ["add", "linear", "--non-interactive"] },
+ next: {
+ command: "eve",
+ args: ["add", "linear", "--non-interactive", "--answer", "components=<JSON value>"],
+ },
});
expect(process.exitCode).toBe(2);
});
@@ -301,6 +318,36 @@ describe("registry commands", () => {
});
});
+ it("completes the resumed setup that a blocked item hands back", async () => {
+ const logger = createLogger();
+ const runSetupCommand = vi.fn(async () => ({ kind: "completed" as const, facts: [] }));
+ getRegistryItems.mockResolvedValue([
+ {
+ meta: {
+ eve: {
+ setup: [{ package: "eve", bin: "eve", args: ["integration", "setup", "web"] }],
+ },
+ },
+ },
+ ]);
+
+ await runAddCommand(
+ logger,
+ "/project",
+ "channel/web",
+ { nonInteractive: true, skipInstall: true, answers: { phoneNumber: "+15551234567" } },
+ { loadSetupCommandRunner: async () => runSetupCommand },
+ );
+
+ expect(addRegistryItems).not.toHaveBeenCalled();
+ expect(JSON.parse(logger.logs.at(-1)!)).toEqual({
+ version: 1,
+ type: "completed",
+ item: "channel/web",
+ completedItems: ["channel/web"],
+ });
+ });
+
it("uses an answered component selection headlessly", async () => {
const logger = createLogger();
getRegistryItems
@@ -658,6 +705,30 @@ describe("registry commands", () => {
]);
});
+ it("reports completion when non-interactive setup is skipped", async () => {
+ const logger = createLogger();
+ getRegistryItems.mockResolvedValue([
+ {
+ meta: { eve: { setup: [{ package: "@acme/slack", bin: "eve-slack", args: ["setup"] }] } },
+ },
+ ]);
+
+ await runAddCommand(logger, "/project", "channel/slack", {
+ nonInteractive: true,
+ skipSetup: true,
+ });
+
+ expect(logger.logs.map((entry) => JSON.parse(entry))).toEqual([
+ { version: 1, type: "progress", message: "Installed channel/slack" },
+ {
+ version: 1,
+ type: "completed",
+ item: "channel/slack",
+ completedItems: ["channel/slack"],
+ },
+ ]);
+ });
+
it("does not ask again after the TUI authorizes installation", async () => {
const fake = createFakePrompter();
const runSetup = vi.fn(async () => ({ kind: "completed" as const, facts: [] }));
diff --git a/packages/eve/src/cli/commands/registry.ts b/packages/eve/src/cli/commands/registry.ts
index dedf61040..a0e8e0f7a 100644
--- a/packages/eve/src/cli/commands/registry.ts
+++ b/packages/eve/src/cli/commands/registry.ts
@@ -34,11 +34,9 @@ import {
type RegistrySearchPresentationSection,
} from "./registry-presentation.js";
import type { runRegistrySetupCommand } from "./registry-setup-command.js";
-import { serializeHeadlessSetupEvent } from "./setup-headless.js";
+import { reportHeadlessSetupCompletion, serializeHeadlessSetupEvent } from "./setup-headless.js";
import { addRegistryMappings, readRegistryConfig } from "./registry-project.js";
-
export type { RegistryCommandLogger } from "./registry-recovery.js";
-
export interface AddCommandOptions {
skipInstall?: boolean;
overwrite?: boolean;
@@ -530,7 +528,7 @@ export async function runAddCommand(
setupReminder: (packageItem) => setupReminder(packageItem, "skipped"),
},
});
- return completion === false ? undefined : completion;
+ return reportCompletion(logger, item, completion, options);
}
if (options.skipInstall === true) {
@@ -547,7 +545,7 @@ export async function runAddCommand(
cancelledReminder: setupReminder(item, "cancelled"),
resumeCommand: setupResumeCommand(item),
});
- return completion === false ? undefined : completion;
+ return reportCompletion(logger, item, completion, options);
}
await addRegistryItems([address], {
@@ -556,7 +554,8 @@ export async function runAddCommand(
overwrite: options.overwrite,
silent: options.silent,
});
- if (eveMetadata?.setup === undefined) return;
+ if (eveMetadata?.setup === undefined)
+ return reportCompletion(logger, item, { facts: [] }, options);
const interactive =
dependencies.hasInteractiveTerminal?.() ??
@@ -570,9 +569,16 @@ export async function runAddCommand(
}),
);
}
+ if (options.skipSetup === true) {
+ if (options.nonInteractive) return reportCompletion(logger, item, { facts: [] }, options);
+ logger.log(setupReminder(item, "skipped"));
+ return;
+ }
if (
- options.skipSetup === true ||
- (!options.nonInteractive && !options.yes && !interactive && options.setupAuthorized !== true)
+ !options.nonInteractive &&
+ !options.yes &&
+ !interactive &&
+ options.setupAuthorized !== true
) {
logger.log(setupReminder(item, "skipped"));
return;
@@ -613,23 +619,20 @@ export async function runAddCommand(
cancelledReminder: setupReminder(item, "cancelled"),
resumeCommand: setupResumeCommand(item),
});
- if (completion !== false && options.nonInteractive) {
- logger.log(
- serializeHeadlessSetupEvent({
- version: 1,
- type: "completed",
- item,
- completedItems: [item],
- ...(completion.deploymentRequired === true
- ? {
- deploymentRequired: true as const,
- next: { command: "eve", args: ["deploy"] },
- }
- : {}),
- }),
- );
- }
- return completion === false ? undefined : completion;
+ return reportCompletion(logger, item, completion, options);
+ });
+}
+function reportCompletion(
+ logger: RegistryCommandLogger,
+ item: string,
+ completion: RegistrySetupCompletion | false,
+ options: AddCommandOptions,
+): RegistrySetupCompletion | undefined {
+ return reportHeadlessSetupCompletion({
+ logger,
+ item,
+ completion,
+ nonInteractive: options.nonInteractive,
});
}
diff --git a/packages/eve/src/cli/commands/setup-answers.test.ts b/packages/eve/src/cli/commands/setup-answers.test.ts
index 6dda8dfdd..350cedac2 100644
--- a/packages/eve/src/cli/commands/setup-answers.test.ts
+++ b/packages/eve/src/cli/commands/setup-answers.test.ts
@@ -15,10 +15,43 @@ describe("setup answers", () => {
expect(() => parseSetupAnswer("mode=portable")).toThrow("must be JSON");
});
- it("builds a minimal resume command", () => {
- expect(headlessSetupContinuation({ item: "channel/github", installed: true })).toEqual({
+ it("builds a resume command with a non-secret answer placeholder", () => {
+ expect(
+ headlessSetupContinuation({
+ item: "channel/github",
+ installed: true,
+ question: { key: "phoneNumber", kind: "text", message: "Phone number?", required: true },
+ }),
+ ).toEqual({
command: "eve",
- args: ["add", "channel/github", "--non-interactive", "--skip-install"],
+ args: [
+ "add",
+ "channel/github",
+ "--non-interactive",
+ "--skip-install",
+ "--answer",
+ "phoneNumber=<JSON value>",
+ ],
+ });
+ });
+
+ it("does not put a secret answer placeholder on the command line", () => {
+ expect(
+ headlessSetupContinuation({
+ item: "connection/linear",
+ installed: true,
+ question: {
+ key: "apiKey",
+ kind: "environment",
+ message: "API key?",
+ required: true,
+ variable: "LINEAR_API_KEY",
+ sensitive: true,
+ },
+ }),
+ ).toEqual({
+ command: "eve",
+ args: ["add", "connection/linear", "--non-interactive", "--skip-install"],
});
});
});
diff --git a/packages/eve/src/cli/commands/setup-headless.ts b/packages/eve/src/cli/commands/setup-headless.ts
index 194687e1c..0aa066519 100644
--- a/packages/eve/src/cli/commands/setup-headless.ts
+++ b/packages/eve/src/cli/commands/setup-headless.ts
@@ -1,4 +1,7 @@
-import type { RegistrySetupBlocker } from "#setup/registry-setup-protocol.js";
+import type {
+ RegistrySetupBlocker,
+ RegistrySetupCompletion,
+} from "#setup/registry-setup-protocol.js";
export interface HeadlessSetupCommand {
command: string;
@@ -52,10 +55,23 @@ export type HeadlessSetupEvent =
export function headlessSetupContinuation(input: {
item: string;
installed: boolean;
+ question?: Extract<RegistrySetupBlocker, { status: "input_required" }>["question"];
}): HeadlessSetupCommand {
+ const answer =
+ input.question?.kind === "environment"
+ ? []
+ : input.question === undefined
+ ? []
+ : ["--answer", `${input.question.key}=<JSON value>`];
return {
command: "eve",
- args: ["add", input.item, "--non-interactive", ...(input.installed ? ["--skip-install"] : [])],
+ args: [
+ "add",
+ input.item,
+ "--non-interactive",
+ ...(input.installed ? ["--skip-install"] : []),
+ ...answer,
+ ],
};
}
@@ -74,6 +90,29 @@ export type HeadlessIntegrationSetupEvent =
| { version: 1; type: "cancelled"; item: string }
| ({ version: 1; type: "blocked" } & RegistrySetupBlocker);
+export function reportHeadlessSetupCompletion(input: {
+ logger: { log(message: string): void };
+ item: string;
+ completion: RegistrySetupCompletion | false;
+ nonInteractive: boolean | undefined;
+}): RegistrySetupCompletion | undefined {
+ if (input.completion === false) return undefined;
+ if (input.nonInteractive === true) {
+ input.logger.log(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "completed",
+ item: input.item,
+ completedItems: [input.item],
+ ...(input.completion.deploymentRequired === true
+ ? { deploymentRequired: true as const, next: { command: "eve", args: ["deploy"] } }
+ : {}),
+ }),
+ );
+ }
+ return input.completion;
+}
+
export function serializeHeadlessSetupEvent(
event: HeadlessSetupEvent | HeadlessIntegrationSetupEvent,
): string {
diff --git a/packages/eve/src/setup/project-name.ts b/packages/eve/src/setup/project-name.ts
index 0f75fc183..bad126b5a 100644
--- a/packages/eve/src/setup/project-name.ts
+++ b/packages/eve/src/setup/project-name.ts
@@ -1,5 +1,5 @@
const PROJECT_NAME_REGEX = /^(?!.*---)[a-z0-9-_.]+$/;
-const PROJECT_NAME_ERROR =
+export const PROJECT_NAME_ERROR =
"Project name can only contain up to 100 lowercase letters, digits, and the characters '.', '_', '-'.";
/** Returns an error message when a project name is not a safe single path segment. */
diff --git a/packages/eve/src/setup/scaffold/create/project.ts b/packages/eve/src/setup/scaffold/create/project.ts
index 72ebdb5ef..488f0f639 100644
--- a/packages/eve/src/setup/scaffold/create/project.ts
+++ b/packages/eve/src/setup/scaffold/create/project.ts
@@ -293,121 +293,59 @@ dist
`,
"AGENTS.md": `# eve Agent App
-This project uses the eve framework. For a content-only change to the root agent's
-identity, purpose, tone, or response guidelines, edit its existing authored
-instructions. Fresh projects use \`agent/instructions.md\`; a project may instead
-use \`agent/instructions.ts\` or files under \`agent/instructions/\`. You do not
-need to read the framework docs for a content-only instructions change.
-
-Before adding or changing eve framework features, classify the requested
-capability. A self-contained typed tool can use the routine recipe below without
-further discovery. For other changes, open the relevant guide directly from the
-installed eve package docs:
-
-- tools beyond the routine recipe: \`node_modules/eve/docs/tools/overview.mdx\`
-- tool approvals: \`node_modules/eve/docs/tools/human-in-the-loop.md\`
-- connections: \`node_modules/eve/docs/connections/overview.mdx\`
-- channels: \`node_modules/eve/docs/channels/overview.mdx\`
-- skills: \`node_modules/eve/docs/skills.mdx\`
-- subagents: \`node_modules/eve/docs/subagents/index.mdx\`
-- schedules: \`node_modules/eve/docs/schedules.mdx\`
-- authentication: \`node_modules/eve/docs/guides/auth-and-route-protection.md\`
-- deployment: \`node_modules/eve/docs/guides/deployment/overview.md\`
+This project uses the eve framework: an agent is a directory of files under \`agent/\`, and eve compiles and runs it.
-Use a bounded authoring loop:
+For a content-only change to the root agent's identity, purpose, tone, or response guidelines, edit its existing authored instructions. Fresh projects use \`agent/instructions.md\`; a project may instead use \`agent/instructions.ts\` or files under \`agent/instructions/\`. You do not need to read the framework docs for a content-only instructions change. A fresh project already has its selected model in \`agent/agent.ts\`; preserve that file unless the user asks to change the model.
-1. Read this file and the relevant guide's opening example and contract.
-2. Inspect only existing files you will modify or need to imitate.
-3. Stop discovery once the file location, imports, and definition shape are
- clear. Implement the smallest complete behavior the user requested.
-4. Run one narrow verification. Expand investigation only when it fails or the
- request needs project-specific integration details.
-
-Do not create a plan or todo list for a contained one-file change. Do not
-recursively glob \`node_modules\`, enumerate the entire docs tree, or read
-unrelated scaffold files when the direct path is known. Package-manager links
-can hide files from recursive glob tools even though direct reads work.
-
-In workspaces or local package installs where \`node_modules/eve\` is absent,
-resolve it with \`realpath node_modules/eve\` or the package manager, then open
-the same path below its \`docs/\` directory. If package docs are unavailable,
-use https://eve.dev/docs as a fallback.
-
-## Routine typed tools
-
-For a self-contained typed action, the standard shape is enough; do not inspect
-unrelated agent config or invent a third-party integration the user did not ask
-for:
-
-\`\`\`ts
-// agent/tools/<tool_name>.ts — the filename supplies the tool name.
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-
-export default defineTool({
- description: "Describe when the model should call this tool.",
- inputSchema: z.object({ value: z.string() }),
- async execute({ value }) {
- return { value };
- },
-});
+## Read the docs before writing code
+
+\`\`\`sh
+ls node_modules/eve/docs
\`\`\`
-Omitting \`approval\` allows calls without human approval, equivalent to
-\`approval: never()\`. Read the tools guide when the implementation needs
-approval, authentication, sandbox access, streaming output, or custom model
-output.
+Start with \`docs/README.md\`: it maps each task to the page that covers it. Read that page before authoring tools, connections, channels, skills, subagents, schedules, or deployment. In a workspace or local package install, resolve the installed \`eve\` package location first. If the package docs are missing, use https://eve.dev/docs.
+
+Use a bounded authoring loop:
+
+1. Read the relevant page and inspect only files you will modify or need to imitate.
+2. Stop discovery once the file location, imports, and definition shape are clear. Implement the smallest complete behavior the user requested.
+3. Run one narrow verification. Expand investigation only when it fails or the request needs project-specific details.
+
+Follow links or inspect public types only when the routed page leaves the task unanswered. Do not recursively glob \`node_modules\`, enumerate the entire docs tree, or read unrelated scaffold files when the direct path is known. Package-manager links can hide files from recursive glob tools even though direct reads work.
-## Adding integrations
+## Prefer an existing integration
-Before implementing an integration yourself, discover existing integrations:
+When a task names an external product or service, search the registry before implementing its integration. For a generic capability, author a tool instead.
\`\`\`sh
eve registry search <query> --json
eve registry view <item>
\`\`\`
-Prefer registry items whose \`implementation\` is \`native\`; use Chat SDK adapters when no
-native channel fits. \`registry view\` provides the selected item's documentation link.
+Prefer items whose \`implementation\` is \`native\`; use Chat SDK adapters when no native channel fits. \`registry view\` links the item's documentation.
-Install and configure one without driving interactive terminal prompts:
+Install without driving interactive prompts:
\`\`\`sh
eve add <item> --non-interactive
\`\`\`
-Exit code 0 means setup completed, 1 means setup failed, and 2 means setup needs
-input or a prerequisite. On exit 2, parse the final NDJSON event and use its
-\`next.command\` as the continuation.
+Exit code 0 means setup completed, 1 failed, and 2 needs an answer or a prerequisite. On exit 2, run the \`next.command\` from the final NDJSON event. For a non-secret question, replace its \`<JSON value>\` answer placeholder with the answer you collected; string values need JSON quotes. Never pass a secret in \`--answer\`. See \`docs/install-integrations.mdx\` for setup prerequisites.
-Every \`--answer\` value is JSON, so strings need JSON quotes. For an editable
-question, you may supply its nested \`editable.key\` with the parent key in one
-invocation:
+## Use eve for Vercel operations
+
+Use eve to link and deploy Vercel projects:
\`\`\`sh
-eve add channel/photon-imessage --non-interactive \\
- --answer 'photon-project-source="create"' \\
- --answer 'photon-project-name="eve · my-agent"'
+eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>]
+eve deploy --non-interactive --yes [--project <name-or-id>]
\`\`\`
-Never pass secrets in \`--answer\`; use the documented environment variable or
-secret store. Add \`--yes\` to accept recommended setup values and reduce setup
-round trips; explicit \`--answer\` values take precedence. Use the reported
-\`--skip-install\` continuation after installation.
-
-A Vercel Connect setup may report \`eve link\` as a prerequisite; run it and
-retry the continuation. For a named Vercel project in CI or an agent run, use
-\`eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>]\`.
-To deploy non-interactively, use
-\`eve deploy --non-interactive --yes [--project <name-or-id>] [--team <team-id-or-slug>]\`.
-Use these eve commands instead of calling \`vercel\` directly; eve owns the
-link, environment pull, and deploy lifecycle.
-
-An \`external_action\` event with \`blocking: true\` means the command is still
-running while it waits for the user. Surface its URL and code, keep the process
-alive, and wait for its matching \`external_action_resolved\` event or a terminal
-event. Do not start a continuation. When a completed event has
-\`deploymentRequired: true\`, recommend its \`next\` command to deploy the changes.
+A setup may report \`eve link\` as a prerequisite; run it, then retry the continuation. When a completed setup event has \`deploymentRequired: true\`, run the \`next\` command it reports.
+
+## Validate the change
+
+Run the validation the task requests. When it does not establish the behavior you changed, run the narrowest relevant check.
`,
"CLAUDE.md": `@AGENTS.md
`,
diff --git a/packages/eve/src/setup/scaffold/index.integration.test.ts b/packages/eve/src/setup/scaffold/index.integration.test.ts
index 2c85e7573..2103ef0f3 100644
--- a/packages/eve/src/setup/scaffold/index.integration.test.ts
+++ b/packages/eve/src/setup/scaffold/index.integration.test.ts
@@ -985,33 +985,26 @@ describe("scaffoldBaseProject", () => {
);
const agentsMd = await readFile(join(projectRoot, "AGENTS.md"), "utf8");
expect(agentsMd).toContain("content-only change to the root agent's");
- expect(agentsMd).toContain("You do not\nneed to read the framework docs");
+ expect(agentsMd).toContain("You do not need to read the framework docs");
+ expect(agentsMd).toContain("preserve that file unless the user asks to change the model");
expect(agentsMd).toContain("`agent/instructions.ts` or files under `agent/instructions/`");
- expect(agentsMd).toContain("Before adding or changing eve framework features");
- expect(agentsMd).toContain("installed eve package docs");
- expect(agentsMd).toContain("node_modules/eve/docs/tools/overview.mdx");
- expect(agentsMd).toContain("node_modules/eve/docs/connections/overview.mdx");
+ expect(agentsMd).toContain("ls node_modules/eve/docs");
+ expect(agentsMd).toContain("Start with `docs/README.md`: it maps each task");
expect(agentsMd).toContain("Use a bounded authoring loop");
expect(agentsMd).toContain("Stop discovery once the file location");
- expect(agentsMd).toContain("Do not create a plan or todo list");
+ expect(agentsMd).toContain("Follow links or inspect public types only");
expect(agentsMd).toContain("recursively glob `node_modules`");
- expect(agentsMd).toContain("realpath node_modules/eve");
- expect(agentsMd).toContain("## Routine typed tools");
- expect(agentsMd).toContain('import { defineTool } from "eve/tools"');
- expect(agentsMd).toContain("Omitting `approval` allows calls without human approval");
expect(agentsMd).toContain("eve registry search <query> --json");
expect(agentsMd).toContain("eve registry view <item>");
+ expect(agentsMd).toContain("For a generic capability, author a tool instead.");
expect(agentsMd).toContain("eve add <item> --non-interactive");
- expect(agentsMd).toContain("`implementation` is `native`");
- expect(agentsMd).toContain("`deploymentRequired: true`");
expect(agentsMd).toContain("Exit code 0 means setup completed");
- expect(agentsMd).toContain("next.command");
- expect(agentsMd).toContain("--skip-install");
- expect(agentsMd).toContain("eve link");
+ expect(agentsMd).toContain("replace its `<JSON value>` answer placeholder");
+ expect(agentsMd).toContain("docs/install-integrations.mdx");
expect(agentsMd).toContain("eve link --non-interactive --project <name-or-id>");
expect(agentsMd).toContain("eve deploy --non-interactive --yes");
- expect(agentsMd).toContain("instead of calling `vercel` directly");
- expect(agentsMd).toContain("external_action_resolved");
+ expect(agentsMd).toContain("Use eve to link and deploy Vercel projects");
+ expect(agentsMd).toContain("Run the validation the task requests");
// `vercel deploy` uploads everything a .vercelignore doesn't exclude, and
// the platform default-ignores only the .env.local variants — eve's dev
// artifacts and a bare .env must be excluded here or a source deploy