The Open Framework for Building Agents
feat(eve): offer selfmod cues in the local dev composer (#3930)
prhacd13d12be177
diff --git a/.changeset/quiet-local-cues.md b/.changeset/quiet-local-cues.mdnew file mode 100644index 000000000..e536a2d2b--- /dev/null+++ b/.changeset/quiet-local-cues.md@@ -0,0 +1,5 @@+---+"eve": patch+---++The initial `eve dev` composer now suggests concrete changes you can ask your agent to make, based on its instructions and capabilities. Fresh `eve init` agents get the customization hint even when scaffolded channels expose workflow webhook routes; agents with an added channel keep the minimal “Send a message…” placeholder.diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.mdindex 1b553b5fb..7e0a7dfeb 100644--- a/docs/guides/dev-tui.md+++ b/docs/guides/dev-tui.md@@ -13,6 +13,8 @@ The footer shows the active model and connection separated by dots. Vercel accouThe transcript remains in your terminal scrollback after you exit. Run `/help` in the UI to see the commands available in the current session.+Before your first message, the empty composer may suggest asking your local agent to edit its instructions or add a tool or channel. The suggestion depends on the agent's current capabilities; typing replaces it without sending a message or changing files.+## Commands| Command | Description |diff --git a/packages/eve/src/cli/dev/tui/prompt-placeholder.integration.test.ts b/packages/eve/src/cli/dev/tui/prompt-placeholder.integration.test.tsnew file mode 100644index 000000000..be42f770b--- /dev/null+++ b/packages/eve/src/cli/dev/tui/prompt-placeholder.integration.test.ts@@ -0,0 +1,33 @@+import { expect, it } from "vitest";++import { defaultDevelopmentExtensions } from "#compiler/development-extensions.js";+import { compileAgentManifest } from "#compiler/normalize-manifest.js";+import { createAgentSourceManifest } from "#discover/manifest.js";+import { buildAgentInfoResponse } from "#internal/nitro/routes/agent-info/build-agent-info-response.js";+import { AGENT_INSTRUCTIONS_TEMPLATE } from "#setup/scaffold/create/instructions-template.js";+import { initialPromptPlaceholder } from "./prompt-placeholder.js";++it("recognizes scaffold instructions and bundled capabilities through compiled agent info", async () => {+ const source = createAgentSourceManifest({+ agentId: "local-cues",+ agentRoot: "/virtual/local-cues/agent",+ appRoot: "/virtual/local-cues",+ });+ source.instructions.push({+ sourceId: "instructions.md",+ logicalPath: "instructions.md",+ sourceKind: "markdown",+ definition: { content: AGENT_INSTRUCTIONS_TEMPLATE },+ });+ const manifest = await compileAgentManifest(source, {+ developmentExtensions: defaultDevelopmentExtensions(),+ });+ const info = buildAgentInfoResponse(+ { manifest, schedules: [] },+ { mode: "development", gatewayCredentials: { apiKey: false, oidc: false } },+ );++ expect(initialPromptPlaceholder(info, true)).toBe(+ "Ask me to connect a channel, edit instructions, add a tool…",+ );+});diff --git a/packages/eve/src/cli/dev/tui/prompt-placeholder.test.ts b/packages/eve/src/cli/dev/tui/prompt-placeholder.test.tsnew file mode 100644index 000000000..2a953a040--- /dev/null+++ b/packages/eve/src/cli/dev/tui/prompt-placeholder.test.ts@@ -0,0 +1,225 @@+import { describe, expect, it } from "vitest";++import type { AgentInfoResult } from "#client/index.js";+import { createTestAgentInfoResult } from "#internal/testing/agent-info-fixture.js";+import { AGENT_INSTRUCTIONS_TEMPLATE } from "#setup/scaffold/create/instructions-template.js";+import { initialPromptPlaceholder } from "./prompt-placeholder.js";++function scaffold(): AgentInfoResult {+ const info = createTestAgentInfoResult();+ const source = {+ logicalPath: "instructions.md",+ sourceId: "instructions.md",+ sourceKind: "markdown" as const,+ owner: { kind: "application" as const },+ };+ return {+ ...info,+ instructions: {+ dynamic: [],+ static: [+ { ...source, name: "instructions", role: "system", content: AGENT_INSTRUCTIONS_TEMPLATE },+ ],+ },+ channels: {+ shadowed: [],+ routes: [+ {+ ...info.agent.config,+ logicalPath: "channels/eve.ts",+ name: "eve",+ method: "POST",+ urlPath: "/eve/v1/session",+ },+ {+ ...info.agent.config,+ logicalPath: "channels/eve.ts",+ name: "eve",+ method: "POST",+ urlPath: "/.well-known/workflow/v1/webhook/:token",+ },+ ],+ },+ subagents: {+ total: 1,+ local: [+ {+ ...info.agent.config,+ owner: { kind: "extension", namespace: "self-modification", packageName: "eve" },+ name: "self-modification__agent",+ entryPath: "subagents/agent/agent.ts",+ rootPath: "/eve/self-modification",+ nodeId: "self-modification__agent",+ parentNodeId: "__root__",+ summary: {+ channels: 0,+ connections: 0,+ hooks: 0,+ instructions: 1,+ memories: 0,+ schedules: 0,+ skills: 1,+ tools: 3,+ },+ },+ ],+ },+ };+}++describe("initialPromptPlaceholder", () => {+ it("invites scaffold customization despite the default eve channel and development capabilities", () => {+ const info = scaffold();+ expect(+ initialPromptPlaceholder(+ {+ ...info,+ skills: {+ dynamic: [],+ static: [+ {+ ...info.subagents.local[0]!,+ name: "self-modification__trace_analysis",+ description: "Inspect traces",+ markdown: "Inspect traces",+ },+ ],+ },+ },+ true,+ ),+ ).toBe("Ask me to connect a channel, edit instructions, add a tool…");+ });++ it.each(["instructions", "tool", "extension", "dynamic tool"])(+ "suggests a channel after customizing %s",+ (change) => {+ const info = scaffold();+ const tool = {+ ...info.agent.config,+ logicalPath: "tools/quote.ts",+ name: "quote",+ description: "Quote an order",+ hasAuth: false,+ hasExecute: true,+ hasModelOutputProjection: false,+ hasOutputSchema: false,+ inputSchema: {},+ requiresApproval: false,+ };+ const customized: AgentInfoResult =+ change === "instructions"+ ? {+ ...info,+ instructions: {+ dynamic: [],+ static: [+ { ...info.instructions.static[0]!, content: "Help Alice prepare orders." },+ ],+ },+ }+ : change === "dynamic tool"+ ? {+ ...info,+ tools: {+ static: [],+ dynamic: [+ {+ ...info.agent.config,+ logicalPath: "tools/quote.ts",+ slug: "quote",+ eventNames: ["turn.started"],+ },+ ],+ },+ }+ : {+ ...info,+ tools: {+ dynamic: [],+ static: [+ {+ ...tool,+ ...(change === "extension"+ ? {+ owner: {+ kind: "extension" as const,+ packageName: "@acme/orders",+ namespace: "orders",+ },+ }+ : {}),+ },+ ],+ },+ };+ expect(initialPromptPlaceholder(customized, true)).toBe(+ "Send a message, or ask me to add a channel…",+ );+ },+ );++ it("stays neutral once an integration channel exists", () => {+ const info = scaffold();+ expect(+ initialPromptPlaceholder(+ {+ ...info,+ channels: {+ ...info.channels,+ routes: [+ ...info.channels.routes,+ {+ ...info.agent.config,+ logicalPath: "channels/slack.ts",+ name: "slack",+ method: "POST",+ urlPath: "/slack",+ },+ ],+ },+ },+ true,+ ),+ ).toBe("Send a message…");+ });++ it.each([+ "remote",+ "production",+ "missing info",+ "no self-modification",+ "discovery error",+ "missing instructions",+ "dynamic instructions",+ ])("stays neutral with %s", (condition) => {+ const info = scaffold();+ const uncertain =+ condition === "missing info"+ ? undefined+ : condition === "production"+ ? { ...info, mode: "production" as const }+ : condition === "no self-modification"+ ? { ...info, subagents: { local: [], total: 0 } }+ : condition === "discovery error"+ ? { ...info, diagnostics: { discoveryErrors: 1, discoveryWarnings: 0 } }+ : condition === "missing instructions"+ ? { ...info, instructions: { static: [], dynamic: [] } }+ : condition === "dynamic instructions"+ ? {+ ...info,+ instructions: {+ static: [],+ dynamic: [+ {+ ...info.agent.config,+ slug: "instructions",+ eventNames: ["turn.started"],+ },+ ],+ },+ }+ : info;+ expect(initialPromptPlaceholder(uncertain, condition !== "remote")).toBe("Send a message…");+ });+});diff --git a/packages/eve/src/cli/dev/tui/prompt-placeholder.ts b/packages/eve/src/cli/dev/tui/prompt-placeholder.tsnew file mode 100644index 000000000..d44b1d807--- /dev/null+++ b/packages/eve/src/cli/dev/tui/prompt-placeholder.ts@@ -0,0 +1,74 @@+import type { AgentInfoResult, AgentInfoSource } from "#client/agent-info-schema.js";+import { AGENT_INSTRUCTIONS_TEMPLATE } from "#setup/scaffold/create/instructions-template.js";+import { SCAFFOLDED_AGENT_PATHS } from "#setup/scaffold/create/agent-paths.js";++const MESSAGE = "Send a message…";+const scaffoldedSourcePaths = new Set(+ Object.values(SCAFFOLDED_AGENT_PATHS).map((path) => path.slice("agent/".length)),+);++function isSelfModification(source: AgentInfoSource): boolean {+ return (+ source.owner.kind === "extension" &&+ source.owner.packageName === "eve" &&+ source.owner.namespace === "self-modification"+ );+}++function isApplicationCapability(source: AgentInfoSource): boolean {+ return source.owner.kind !== "framework" && !isSelfModification(source);+}++function isAddedCapability(source: AgentInfoSource): boolean {+ return (+ isApplicationCapability(source) &&+ !(source.owner.kind === "application" && scaffoldedSourcePaths.has(source.logicalPath))+ );+}++export function initialPromptPlaceholder(+ info: AgentInfoResult | undefined,+ localDevelopment: boolean,+): string {+ if (+ !localDevelopment ||+ info === undefined ||+ info.mode !== "development" ||+ info.diagnostics.discoveryErrors > 0 ||+ !info.subagents.local.some(+ (entry) => entry.name === "self-modification__agent" && isSelfModification(entry),+ )+ ) {+ return MESSAGE;+ }++ if (info.channels.routes.some(isAddedCapability)) return MESSAGE;++ const instructions = info.instructions.static.filter(isApplicationCapability);+ if (info.instructions.dynamic.some(isApplicationCapability) || instructions.length === 0) {+ return MESSAGE;+ }++ const hasCapabilities = [+ ...info.tools.static,+ ...info.tools.dynamic,+ ...info.skills.static,+ ...info.skills.dynamic,+ ...info.connections,+ ...info.schedules,+ ...info.hooks,+ ...info.memories,+ ...info.subagents.local,+ ...info.remoteAgents.entries,+ ].some(isAddedCapability);+ const [instructionsFile] = instructions;+ const isScaffold =+ instructions.length === 1 &&+ instructionsFile?.owner.kind === "application" &&+ instructionsFile.logicalPath === SCAFFOLDED_AGENT_PATHS.instructions.slice("agent/".length) &&+ instructionsFile.content.trim() === AGENT_INSTRUCTIONS_TEMPLATE.trim();++ return isScaffold && !hasCapabilities+ ? "Ask me to connect a channel, edit instructions, add a tool…"+ : "Send a message, or ask me to add a channel…";+}diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.tsindex 5ee039600..2e36c2525 100644--- a/packages/eve/src/cli/dev/tui/runner.test.ts+++ b/packages/eve/src/cli/dev/tui/runner.test.ts@@ -623,6 +623,7 @@ describe("EveTUIRunner agent header", () => {expect(headers[0]).toEqual({name: "Weather Agent",serverUrl: "http://localhost:3000",+ localDevelopment: false,info: AGENT_INFO,});expect(renderer.readPrompt).toHaveBeenCalled();@@ -679,6 +680,7 @@ describe("EveTUIRunner agent header", () => {{name: "Weather Agent",serverUrl: "http://localhost:3000",+ localDevelopment: false,info: AGENT_INFO,},]);diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.tsindex 91866ebed..3e906c3eb 100644--- a/packages/eve/src/cli/dev/tui/runner.ts+++ b/packages/eve/src/cli/dev/tui/runner.ts@@ -251,6 +251,7 @@ export type AgentTUIAgentHeader = {name: string;serverUrl: string;info?: AgentInfoResult;+ localDevelopment?: boolean;};export type AgentTUIRenderer = {@@ -748,6 +749,7 @@ export class EveTUIRunner {const header: AgentTUIAgentHeader = {name: this.#name,serverUrl,+ localDevelopment: this.#appRoot !== undefined,};if (headerInfo !== undefined) header.info = headerInfo;this.#renderer.renderAgentHeader?.(header);diff --git a/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts b/packages/eve/src/cli/dev/tui/terminal-renderer.test.tsindex e54f3635d..03b61b4f8 100644--- a/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts+++ b/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts@@ -1778,20 +1778,69 @@ describe("TerminalRenderer (inline scrollback)", () => {renderer.shutdown();});- it("retires the placeholder after the first user message", async () => {+ it("retires a local cue after the first user message, including after a header refresh", async () => {const { screen, input, renderer } = makeRenderer();+ const info = createTestAgentInfoResult();+ const header = {+ name: "Orders",+ serverUrl: "http://localhost:3000",+ localDevelopment: true,+ info: {+ ...info,+ instructions: {+ dynamic: [],+ static: [+ {+ ...info.agent.config,+ name: "instructions",+ role: "system" as const,+ content: "Help with orders.",+ },+ ],+ },+ subagents: {+ total: 1,+ local: [+ {+ ...info.agent.config,+ owner: {+ kind: "extension" as const,+ namespace: "self-modification",+ packageName: "eve",+ },+ name: "self-modification__agent",+ entryPath: "subagents/agent/agent.ts",+ rootPath: "/eve/self-modification",+ nodeId: "self-modification__agent",+ parentNodeId: "__root__",+ summary: {+ channels: 0,+ connections: 0,+ hooks: 0,+ instructions: 1,+ memories: 0,+ schedules: 0,+ skills: 0,+ tools: 1,+ },+ },+ ],+ },+ },+ };+ renderer.renderAgentHeader(header);const first = renderer.readPrompt();- expect(screen.snapshot()).toContain("❯ Send a message…");+ expect(screen.snapshot()).toContain("❯ Send a message, or ask me to add a channel…");input.type("hello");input.enter();expect(await first).toBe("hello");+ await renderer.renderStream(streamOf([]), { continueSession: true, submittedPrompt: "hello" });- // Once the user has spoken, the empty prompt keeps the default-color `❯` but- // drops the invitation text; typing still colors the active `❯`.+ renderer.renderAgentHeader(header);const second = renderer.readPrompt();expect(screen.snapshot()).toContain("❯");- expect(screen.snapshot()).not.toContain("Send a message…");+ expect(screen.snapshot()).not.toContain("ask me to add a channel");input.type("again");expect(screen.snapshot()).toContain("❯ again");input.ctrlC();@@ -1799,6 +1848,24 @@ describe("TerminalRenderer (inline scrollback)", () => {input.ctrlC();await expect(second).rejects.toThrow();renderer.shutdown();++ const queued = makeRenderer();+ queued.renderer.beginStartupDraft({ title: "Orders" });+ queued.input.type("hello from startup");+ queued.input.enter();+ const startup = queued.renderer.finishStartupDraft();+ expect(startup.queuedPrompt).toBe("hello from startup");+ queued.renderer.renderAgentHeader(header);+ await queued.renderer.renderStream(streamOf([]), {+ continueSession: true,+ submittedPrompt: startup.queuedPrompt,+ });+ const afterQueuedMessage = queued.renderer.readPrompt();+ expect(queued.screen.snapshot()).not.toContain("ask me to add a channel");+ queued.input.ctrlC();+ queued.input.ctrlC();+ await expect(afterQueuedMessage).rejects.toThrow();+ queued.renderer.shutdown();});it("keeps collapsed reasoning out of the transcript behind the turn bar", async () => {diff --git a/packages/eve/src/cli/dev/tui/terminal-renderer.ts b/packages/eve/src/cli/dev/tui/terminal-renderer.tsindex 982c410c9..b8aba7299 100644--- a/packages/eve/src/cli/dev/tui/terminal-renderer.ts+++ b/packages/eve/src/cli/dev/tui/terminal-renderer.ts@@ -86,6 +86,7 @@ import type {TerminalPartDisplayMode,} from "./types.js";import type { AgentInfoResult } from "#client/index.js";+import { initialPromptPlaceholder } from "./prompt-placeholder.js";import { summarizeKnownError } from "#harness/semantic-errors/index.js";import { inspectError, type LogRecord } from "#internal/logging.js";import {@@ -303,6 +304,7 @@ type AgentHeaderOptions = {name: string;serverUrl: string;info?: AgentInfoResult;+ localDevelopment?: boolean;};type DisplayModes = {@@ -439,6 +441,7 @@ export class TerminalRenderer implements AgentTUIRenderer {readonly #fileContents = new FileContentCache();readonly #subagentHeaders = new Set<string>();#agentHeader?: AgentHeaderOptions;+ #initialPromptPlaceholder = "Send a message…";#startupPhase?: "starting" | "connecting" | "updating";#startupEditor?: LineState;#startupConsumer?: (key: TerminalKey) => void;@@ -774,6 +777,10 @@ export class TerminalRenderer implements AgentTUIRenderer {this.#resolvedModelId = undefined;}this.#agentHeader = options;+ this.#initialPromptPlaceholder = initialPromptPlaceholder(+ options.info,+ options.localDevelopment === true,+ );this.#start();const body = this.#renderAgentHeaderRows().join("\n");if (this.#agentHeaderRendered) {@@ -3682,6 +3689,7 @@ export class TerminalRenderer implements AgentTUIRenderer {#addSubmittedPrompt(prompt: string | undefined) {if (prompt == null) return;+ this.#hasUserMessage = true;const origin = this.#nextSubmittedPromptOrigin;this.#nextSubmittedPromptOrigin = undefined;if (this.#pendingEchoedPrompt === prompt) {@@ -4587,7 +4595,7 @@ export class TerminalRenderer implements AgentTUIRenderer {? "Message · Enter to queue": this.#hasUserMessage? ""- : "Send a message…";+ : this.#initialPromptPlaceholder;}const renderedPromptRows = promptInputRows(promptRows);// The prompt helper ends with a footer spacer; a drawer owns that gap.diff --git a/packages/eve/src/setup/scaffold/create/agent-paths.ts b/packages/eve/src/setup/scaffold/create/agent-paths.tsnew file mode 100644index 000000000..25139b642--- /dev/null+++ b/packages/eve/src/setup/scaffold/create/agent-paths.ts@@ -0,0 +1,5 @@+export const SCAFFOLDED_AGENT_PATHS = {+ config: "agent/agent.ts",+ channel: "agent/channels/eve.ts",+ instructions: "agent/instructions.md",+} as const;diff --git a/packages/eve/src/setup/scaffold/create/instructions-template.ts b/packages/eve/src/setup/scaffold/create/instructions-template.tsnew file mode 100644index 000000000..75ca249e8--- /dev/null+++ b/packages/eve/src/setup/scaffold/create/instructions-template.ts@@ -0,0 +1,8 @@+export const AGENT_INSTRUCTIONS_TEMPLATE = `# Identity++You are a general-purpose AI agent powered by eve, Vercel's agent framework.++# Customization++Your behavior and capabilities are defined by this project's code. You can be customized into whatever kind of agent the user wants by updating the project's instructions, tools, skills, connections, channels, subagents, and schedules.+`;diff --git a/packages/eve/src/setup/scaffold/create/project.ts b/packages/eve/src/setup/scaffold/create/project.tsindex b1ba3ff23..c4e594b02 100644--- a/packages/eve/src/setup/scaffold/create/project.ts+++ b/packages/eve/src/setup/scaffold/create/project.ts@@ -16,6 +16,8 @@ import {type WorkspaceRootMutation,} from "../workspace-root.js";import { WEB_CHANNEL_TEMPLATES } from "./web-template.js";+import { AGENT_INSTRUCTIONS_TEMPLATE } from "./instructions-template.js";+import { SCAFFOLDED_AGENT_PATHS } from "./agent-paths.js";export const CURRENT_DIRECTORY_PROJECT_NAME = ".";@@ -101,9 +103,9 @@ export function agentTemplateFiles(reasoning?: AgentReasoningDefinition,): Record<string, string> {return {- "agent/agent.ts": renderAgentTemplate(model, reasoning),- "agent/channels/eve.ts": WEB_CHANNEL_TEMPLATES.default,- "agent/instructions.md": AGENT_INSTRUCTIONS_TEMPLATE,+ [SCAFFOLDED_AGENT_PATHS.config]: renderAgentTemplate(model, reasoning),+ [SCAFFOLDED_AGENT_PATHS.channel]: WEB_CHANNEL_TEMPLATES.default,+ [SCAFFOLDED_AGENT_PATHS.instructions]: AGENT_INSTRUCTIONS_TEMPLATE,};}@@ -220,15 +222,6 @@ export const ROOT_ONLY_PACKAGE_JSON_TEMPLATE_SUFFIX = `,}`;-const AGENT_INSTRUCTIONS_TEMPLATE = `# Identity--You are a general-purpose AI agent powered by eve, Vercel's agent framework.--# Customization--Your behavior and capabilities are defined by this project's code. You can be customized into whatever kind of agent the user wants by updating the project's instructions, tools, skills, connections, channels, subagents, and schedules.-`;-const SHARED_TEMPLATE_FILES: Record<string, string> = {"README.md": `# __EVE_INIT_APP_NAME__@@ -266,8 +259,8 @@ eve deploy\`eve deploy\` links a Vercel project if needed and deploys the agent to production. See the [eve deployment documentation](https://eve.dev/docs/guides/deployment/vercel) for authentication, environment variables, and deployment options.`,- "agent/channels/eve.ts": WEB_CHANNEL_TEMPLATES.default,- "agent/instructions.md": AGENT_INSTRUCTIONS_TEMPLATE,+ [SCAFFOLDED_AGENT_PATHS.channel]: WEB_CHANNEL_TEMPLATES.default,+ [SCAFFOLDED_AGENT_PATHS.instructions]: AGENT_INSTRUCTIONS_TEMPLATE,"tsconfig.json": `{"compilerOptions": {"target": "ES2022",@@ -368,7 +361,7 @@ function templateFiles(input: {includeRootOnlyPackageJsonFields: boolean;}): Record<string, string> {return {- "agent/agent.ts": input.byokProvider ? BYOK_AGENT_TEMPLATE : BASE_AGENT_TEMPLATE,+ [SCAFFOLDED_AGENT_PATHS.config]: input.byokProvider ? BYOK_AGENT_TEMPLATE : BASE_AGENT_TEMPLATE,...SHARED_TEMPLATE_FILES,"package.json": packageJsonTemplate(input.includeRootOnlyPackageJsonFields),};