The Open Framework for Building Agents
feat(eve): accept a registry address in /add (#2472)
prha50488a1083b9
diff --git a/.changeset/parameterized-add-command.md b/.changeset/parameterized-add-command.mdnew file mode 100644index 000000000..4f65b8885--- /dev/null+++ b/.changeset/parameterized-add-command.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`/add` in the dev terminal UI now accepts a registry item address. `/add channel/slack` skips the category and search screens and opens that item's details and confirmation directly, then runs the same installation, setup, add-more, and deployment flow as bare `/add`, which still opens the registry browser.diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.mdindex 6fd7659f4..fb72c3f0f 100644--- a/docs/guides/dev-tui.md+++ b/docs/guides/dev-tui.md@@ -13,24 +13,35 @@ The transcript remains in your terminal scrollback after you exit. Run `/help` i## Commands-| Command | Description |-| ------------- | ----------------------------------------------------------------------------------------------------- |-| `/model` | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`. |-| `/add` | Browse and install channels, MCP connections, extensions, and observability integrations. |-| `/deploy` | Deploy the agent to Vercel production. Links the directory first if needed. |-| `/vc:install` | Install the Vercel CLI. |-| `/vc:login` | Log in to Vercel or restore access to a remote deployment. |-| `/loglevel` | Choose which server and agent logs appear in the transcript. |-| `/traces` | Open the local trace viewer. Pass a trace ID prefix to open a specific trace. |-| `/reset` | Start a fresh session. |-| `/cancel` | Cancel the current turn without discarding settled context. |-| `/clear` | Clear the session's model-message history. `/new` is an alias. |-| `/compact` | Compact the current session's context. |-| `/exit` | Quit the UI. |-| `/help` | List available commands. |+| Command | Description |+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `/model` | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`. |+| `/add` | Browse and install channels, MCP connections, extensions, and observability integrations. Pass an item address to open it directly: `/add channel/slack`. |+| `/deploy` | Deploy the agent to Vercel production. Links the directory first if needed. |+| `/vc:install` | Install the Vercel CLI. |+| `/vc:login` | Log in to Vercel or restore access to a remote deployment. |+| `/loglevel` | Choose which server and agent logs appear in the transcript. |+| `/traces` | Open the local trace viewer. Pass a trace ID prefix to open a specific trace. |+| `/reset` | Start a fresh session. |+| `/cancel` | Cancel the current turn without discarding settled context. |+| `/clear` | Clear the session's model-message history. `/new` is an alias. |+| `/compact` | Compact the current session's context. |+| `/exit` | Quit the UI. |+| `/help` | List available commands. |`/model`, `/add`, `/deploy`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.+## Add an integration++Bare `/add` opens the categorized registry browser. Pass an item address — `<category>/<name>`, where category is `channel`, `connection`, `extension`, or `instrumentation` — to skip the category and search screens and open that item directly:++```text+/add channel/slack+/add extension/agent-browser+```++Either way the UI shows the item's details and asks to confirm before installing, then runs the same installation and setup prompts. Choosing **Back** on a directly addressed item returns to the registry browser.+## Work with the agentType a message and press `Enter` to send it. When the agent asks a question or requests tool approval, respond in the prompt shown by the UI. Connection authorization can open a browser; keep local `eve dev` running until the browser returns to it.diff --git a/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts b/packages/eve/src/cli/dev/tui/prompt-command-handler.test.tsindex 0423cbd75..6f4f40f92 100644--- a/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts+++ b/packages/eve/src/cli/dev/tui/prompt-command-handler.test.ts@@ -164,6 +164,43 @@ describe("createPromptCommandHandler", () => {}});+ it("routes a /add argument to the registry flow's initial address", async () => {+ const runTuiSetupCommand = vi.fn(async () => ({+ message: "Added Slack",+ preserveFlowDiagnostics: true,+ }));+ vi.doMock("./setup-commands.js", () => ({+ SETUP_FLOW_CONFIG: { add: { title: "Add to your agent", indicator: "pulse" } },+ runTuiSetupCommand,+ }));++ try {+ const setupFlow = setupFlowRenderer();+ const handler = createPromptCommandHandler({ target: LOCAL_TARGET });++ await handler.handle(+ { type: "extension", name: "add", argument: "channel/slack" },+ context({ setupFlow }),+ );+ await handler.handle(+ { type: "extension", name: "add", argument: "" },+ context({ setupFlow }),+ );++ expect(runTuiSetupCommand).toHaveBeenNthCalledWith(+ 1,+ expect.objectContaining({ command: "add", initialRegistryAddress: "channel/slack" }),+ );+ expect(runTuiSetupCommand).toHaveBeenNthCalledWith(+ 2,+ expect.not.objectContaining({ initialRegistryAddress: expect.anything() }),+ );+ } finally {+ vi.doUnmock("./setup-commands.js");+ vi.resetModules();+ }+ });+it("keeps the setup panel open for an immediate onboarding handoff", async () => {const runTuiSetupCommand = vi.fn(async () => ({message: "Vercel CLI installed.",diff --git a/packages/eve/src/cli/dev/tui/prompt-command-handler.ts b/packages/eve/src/cli/dev/tui/prompt-command-handler.tsindex 98f45f2c7..a5d9d7585 100644--- a/packages/eve/src/cli/dev/tui/prompt-command-handler.ts+++ b/packages/eve/src/cli/dev/tui/prompt-command-handler.ts@@ -122,6 +122,10 @@ export function createPromptCommandHandler(if (context.initialModelStep !== undefined) {commandInput.initialModelStep = context.initialModelStep;}+ // `/add <item>` opens that registry item directly; bare `/add` browses.+ if (command.name === "add" && command.argument.length > 0) {+ commandInput.initialRegistryAddress = command.argument;+ }if (options.flows !== undefined) commandInput.flows = options.flows;const result = await runTuiSetupCommand(commandInput);preserveFlowDiagnostics = result.preserveFlowDiagnostics;diff --git a/packages/eve/src/cli/dev/tui/prompt-commands.test.ts b/packages/eve/src/cli/dev/tui/prompt-commands.test.tsindex 7a15b09c6..31ecd0355 100644--- a/packages/eve/src/cli/dev/tui/prompt-commands.test.ts+++ b/packages/eve/src/cli/dev/tui/prompt-commands.test.ts@@ -65,6 +65,27 @@ describe("parsePromptCommand", () => {});});+ it("parses /add with a trimmed registry address", () => {+ expect(parsePromptCommand("/add channel/slack")).toEqual({+ type: "extension",+ name: "add",+ argument: "channel/slack",+ });+ expect(parsePromptCommand("/add extension/agent-browser ")).toEqual({+ type: "extension",+ name: "add",+ argument: "extension/agent-browser",+ });+ });++ it("parses the typeahead's completed /add, which carries a trailing space", () => {+ expect(parsePromptCommand("/add ")).toEqual({+ type: "extension",+ name: "add",+ argument: "",+ });+ });+it("parses bare /loglevel and /loglevel with a mode argument", () => {expect(parsePromptCommand("/loglevel")).toEqual({ type: "loglevel", argument: "" });expect(parsePromptCommand("/loglevel none")).toEqual({ type: "loglevel", argument: "none" });@@ -154,9 +175,9 @@ describe("PROMPT_COMMANDS registry", () => {}});- it("pairs an argument hint with takesArgument", () => {+ it("only gives argument hints to commands that accept arguments", () => {for (const spec of PROMPT_COMMANDS) {- expect(spec.argumentHint !== undefined).toBe(spec.takesArgument);+ if (spec.argumentHint !== undefined) expect(spec.takesArgument).toBe(true);}});diff --git a/packages/eve/src/cli/dev/tui/prompt-commands.ts b/packages/eve/src/cli/dev/tui/prompt-commands.tsindex d6be90f32..1acaae441 100644--- a/packages/eve/src/cli/dev/tui/prompt-commands.ts+++ b/packages/eve/src/cli/dev/tui/prompt-commands.ts@@ -25,7 +25,7 @@ export interface PromptCommandSpec {readonly aliases: readonly string[];/** One-line discovery copy shown by the typeahead. */readonly description: string;- /** Argument shape shown dim after the name, e.g. "[provider/model]". */+ /** Optional argument shape shown dim after the name, e.g. "[provider/model]". */readonly argumentHint?: string;/** Accepts a trailing argument (enables `/name <arg>` parsing). */readonly takesArgument: boolean;@@ -132,8 +132,8 @@ const PROMPT_COMMAND_DEFINITIONS = [name: "add",aliases: [],description: "Add an integration from the registry",- takesArgument: false,- build: () => ({ type: "extension", name: "add", argument: "" }),+ takesArgument: true,+ build: (argument) => ({ type: "extension", name: "add", argument }),targets: ["local"],},{diff --git a/packages/eve/src/cli/dev/tui/setup-commands.test.ts b/packages/eve/src/cli/dev/tui/setup-commands.test.tsindex 4ac42bdcd..deed8530b 100644--- a/packages/eve/src/cli/dev/tui/setup-commands.test.ts+++ b/packages/eve/src/cli/dev/tui/setup-commands.test.ts@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";import { createFakePrompter } from "#internal/testing/fake-prompter.js";import { HumanActionRequiredError } from "#setup/human-action.js";-import { RegistryFlowFailedError } from "#setup/flows/registry.js";+import { RegistryFlowFailedError, runRegistryFlow } from "#setup/flows/registry.js";import {runTuiSetupCommand,@@ -76,6 +76,7 @@ function run(input: {flows: TuiSetupFlows;renderer?: TuiSetupCommandRenderer;initialModelStep?: "provider";+ initialRegistryAddress?: string;upgradeChoice?: "upgrade" | "later";withExclusiveTerminal?: TuiSetupCommandInput["withExclusiveTerminal"];}) {@@ -93,6 +94,9 @@ function run(input: {if (input.initialModelStep !== undefined) {commandInput.initialModelStep = input.initialModelStep;}+ if (input.initialRegistryAddress !== undefined) {+ commandInput.initialRegistryAddress = input.initialRegistryAddress;+ }if (input.withExclusiveTerminal !== undefined) {commandInput.withExclusiveTerminal = input.withExclusiveTerminal;}@@ -429,6 +433,64 @@ describe("runTuiSetupCommand", () => {expect(runRegistryFlow).toHaveBeenCalledWith(expect.objectContaining({ appRoot: APP_ROOT }));});+ it("forwards a /add argument as the registry flow's initial address", async () => {+ const flows = fakeFlows();++ await run({ command: "add", flows, initialRegistryAddress: "channel/slack" });++ expect(flows.runRegistryFlow).toHaveBeenCalledWith(+ expect.objectContaining({ appRoot: APP_ROOT, initialAddress: "channel/slack" }),+ );+ });++ it("omits an initial address for bare /add", async () => {+ const flows = fakeFlows();++ await run({ command: "add", flows });++ expect(flows.runRegistryFlow).toHaveBeenCalledWith(+ expect.not.objectContaining({ initialAddress: expect.anything() }),+ );+ });++ it.each([+ ["bare /add browses the catalog", undefined, "Add an integration"],+ ["/add <item> opens the item", "channel/slack", "Slack"],+ ])("composes with the real registry flow: %s", async (_case, address, firstPrompt) => {+ const prompts: string[] = [];+ const registryDeps = {+ browseRegistryCatalog: vi.fn(async () => ({+ items: [{ address: "channel/slack", name: "channel/slack", source: "Vercel" }],+ total: 1,+ errors: [],+ })),+ getRegistryItemManifest: vi.fn(async () => ({ name: "channel/slack", title: "Slack" })),+ installRegistryItem: vi.fn(async () => ({ output: [] })),+ detectDeployment: vi.fn(async () => ({ state: "unlinked" as const })),+ runDeployFlow: vi.fn(async () => ({ kind: "deployed" as const })),+ };+ // The real flow behind the command seam, so the parsed argument is proven+ // to reach `initialAddress` rather than stopping at a mock.+ const flows = fakeFlows({+ runRegistryFlow: (input) => {+ const fake = createFakePrompter({+ single: (options) => {+ prompts.push(options.message);+ return options.message === "Add an integration" ? "action:done" : "add";+ },+ });+ return runRegistryFlow({ ...input, prompter: fake.prompter, deps: registryDeps });+ },+ });++ const commandRun: Parameters<typeof run>[0] = { command: "add", flows };+ if (address !== undefined) commandRun.initialRegistryAddress = address;+ await run(commandRun);++ expect(prompts[0]).toBe(firstPrompt);+ expect(registryDeps.browseRegistryCatalog).toHaveBeenCalledTimes(address === undefined ? 1 : 0);+ });+it("overrides a settled success tone when add is interrupted", async () => {const renderer = fakePanelRenderer();const flows = fakeFlows({diff --git a/packages/eve/src/cli/dev/tui/setup-commands.ts b/packages/eve/src/cli/dev/tui/setup-commands.tsindex ac3ddb674..86c5aa956 100644--- a/packages/eve/src/cli/dev/tui/setup-commands.ts+++ b/packages/eve/src/cli/dev/tui/setup-commands.ts@@ -47,6 +47,8 @@ export interface TuiSetupCommandInput {renderer: TuiSetupCommandRenderer;/** Initial model-flow step authorized by the runner's boot evidence. */initialModelStep?: "provider";+ /** Registry address from `/add <item>`, opening that item instead of the browser. */+ initialRegistryAddress?: string;/** Live ChatGPT identity shown only inside model configuration UI. */chatGptAccountLabel?: string;/** Suspends development runtime artifacts while registry installation and setup mutate them. */@@ -258,7 +260,15 @@ async function executeSetupCommand(return outcome;}case "add": {- const result = await flows.runRegistryFlow({ appRoot, prompter, signal });+ const registryInput: Parameters<TuiSetupFlows["runRegistryFlow"]>[0] = {+ appRoot,+ prompter,+ signal,+ };+ if (input.initialRegistryAddress !== undefined) {+ registryInput.initialAddress = input.initialRegistryAddress;+ }+ const result = await flows.runRegistryFlow(registryInput);if (result.kind === "cancelled") {return { message: "/add dismissed.", preserveFlowDiagnostics: true };}diff --git a/packages/eve/src/setup/flows/registry.test.ts b/packages/eve/src/setup/flows/registry.test.tsindex 6aa6835b5..c1a7ad92f 100644--- a/packages/eve/src/setup/flows/registry.test.ts+++ b/packages/eve/src/setup/flows/registry.test.ts@@ -1,6 +1,7 @@import { describe, expect, it, vi } from "vitest";import { createFakePrompter } from "#internal/testing/fake-prompter.js";+import { WizardCancelledError } from "#setup/step.js";import { RegistryFlowFailedError, runRegistryFlow, type RegistryFlowDeps } from "./registry.js";@@ -289,6 +290,130 @@ describe("runRegistryFlow", () => {);});+ it("opens an initial address without the category or search screens", async () => {+ const answers = ["add"];+ const prompts: unknown[] = [];+ const fake = createFakePrompter({+ single: (options) => {+ prompts.push(options);+ return answers.shift()!;+ },+ });+ const flowDeps = deps({+ getRegistryItemManifest: vi.fn(async () => ({+ name: "channel/slack",+ title: "Slack",+ description: "Talk to your agent in Slack",+ dependencies: ["@slack/web-api"],+ })),+ });++ await expect(+ runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ initialAddress: "channel/slack",+ deps: flowDeps,+ }),+ ).resolves.toEqual({+ kind: "done",+ addedItems: ["channel/slack"],+ items: [{ address: "channel/slack", title: "Slack", facts: [], output: [] }],+ facts: [],+ output: [],+ });+ expect(flowDeps.browseRegistryCatalog).not.toHaveBeenCalled();+ expect(flowDeps.getRegistryItemManifest).toHaveBeenCalledWith(APP_ROOT, "channel/slack");+ expect(prompts).toHaveLength(1);+ expect(prompts[0]).toMatchObject({+ message: "Slack",+ description: "Talk to your agent in Slack",+ metadata: [+ { label: "Source", value: "Vercel" },+ { label: "Packages", value: "@slack/web-api" },+ ],+ options: [+ { value: "add", label: "Add to project" },+ { value: "back", label: "Back" },+ ],+ });+ expect(flowDeps.installRegistryItem).toHaveBeenCalledWith(+ APP_ROOT,+ "channel/slack",+ expect.objectContaining({ silent: true, prompter: fake.prompter }),+ );+ });++ it("falls back to the category hub when an initial address is not added", async () => {+ const answers = ["back", "action:done"];+ const fake = createFakePrompter({ single: () => answers.shift()! });+ const flowDeps = deps();++ await expect(+ runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ initialAddress: "channel/slack",+ deps: flowDeps,+ }),+ ).resolves.toEqual({ kind: "done", addedItems: [], items: [], facts: [], output: [] });++ expect(fake.selectMessages).toEqual(["agent-browser", "Add an integration"]);+ expect(flowDeps.installRegistryItem).not.toHaveBeenCalled();+ });++ it("ignores a blank initial address", async () => {+ const answers = ["action:done"];+ const fake = createFakePrompter({ single: () => answers.shift()! });+ const flowDeps = deps();++ await runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ initialAddress: " ",+ deps: flowDeps,+ });++ expect(flowDeps.getRegistryItemManifest).not.toHaveBeenCalled();+ expect(fake.selectMessages).toEqual(["Add an integration"]);+ });++ it("surfaces an unresolvable initial address", async () => {+ const fake = createFakePrompter({ single: () => "add" });+ const flowDeps = deps({+ getRegistryItemManifest: vi.fn(async () => {+ throw new Error('Registry item "channel/slak" was not found.');+ }),+ });++ await expect(+ runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ initialAddress: "channel/slak",+ deps: flowDeps,+ }),+ ).rejects.toThrow('Registry item "channel/slak" was not found.');+ expect(flowDeps.installRegistryItem).not.toHaveBeenCalled();+ });++ it("reports cancellation from an initial address as a dismissed flow", async () => {+ const fake = createFakePrompter({+ single: () => {+ throw new WizardCancelledError();+ },+ });++ await expect(+ runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ initialAddress: "channel/slack",+ deps: deps(),+ }),+ ).resolves.toEqual({ kind: "cancelled" });+ });+it("collects deployable setups, adds another, then deploys once", async () => {const answers = ["category:channel",diff --git a/packages/eve/src/setup/flows/registry.ts b/packages/eve/src/setup/flows/registry.tsindex 8081141b2..d3ddf4f16 100644--- a/packages/eve/src/setup/flows/registry.ts+++ b/packages/eve/src/setup/flows/registry.ts@@ -12,7 +12,7 @@ import type { RegistrySetupFact } from "#setup/registry-setup-protocol.js";import { WizardCancelledError } from "#setup/step.js";import { withSpinner } from "#setup/with-spinner.js";-import { createRegistrySession } from "./registry-session.js";+import { createRegistrySession, type RegistrySession } from "./registry-session.js";const ADDRESS_PREFIX = "address:";const BACK = "action:back";@@ -268,11 +268,46 @@ async function resolveAddressItem(return { item, manifest: record };}-/** Runs the categorized interactive registry catalog used by the dev TUI's `/add`. */+/**+ * Confirms, installs, and settles one resolved item. `undefined` means the flow+ * keeps browsing — the user backed out of the item, or asked to add more.+ */+async function offerItem(+ input: { appRoot: string; prompter: Prompter; signal?: AbortSignal },+ deps: RegistryFlowDeps,+ session: RegistrySession,+ item: RegistryCatalogItem,+ manifest?: Record<string, unknown>,+): Promise<RegistryFlowResult | undefined> {+ const inspected = await inspectItem(+ input.prompter,+ deps,+ input.appRoot,+ item,+ manifest,+ input.signal,+ );+ if (inspected.kind !== "added") return undefined;+ session.add(item.address, itemLabel(item), inspected.output, inspected.setup);+ const next = await session.continueAfterInstall({+ appRoot: input.appRoot,+ prompter: input.prompter,+ signal: input.signal,+ });+ return next === "add-more" ? undefined : next;+}++/**+ * Runs the categorized interactive registry catalog used by the dev TUI's+ * `/add`. `initialAddress` — `/add channel/slack` — skips the category and+ * search screens and opens that item's confirmation directly; backing out of it+ * lands on the same category hub the browser starts from.+ */export async function runRegistryFlow(input: {appRoot: string;prompter: Prompter;signal?: AbortSignal;+ initialAddress?: string;deps?: Partial<RegistryFlowDeps>;}): Promise<RegistryFlowResult> {let loaded: typeof import("#cli/commands/registry.js") | undefined;@@ -292,10 +327,20 @@ export async function runRegistryFlow(input: {};let notices: SelectNotice[] = [];const session = createRegistrySession(deps);+ const initialAddress = input.initialAddress?.trim();+ let pendingAddress = initialAddress === "" ? undefined : initialAddress;try {while (true) {input.signal?.throwIfAborted();+ if (pendingAddress !== undefined) {+ const address = pendingAddress;+ pendingAddress = undefined;+ const resolved = await resolveAddressItem(input.prompter, deps, input.appRoot, address);+ const settled = await offerItem(input, deps, session, resolved.item, resolved.manifest);+ if (settled !== undefined) return settled;+ continue;+ }const catalog = await withSpinner(input.prompter, "Loading registry…", () =>deps.browseRegistryCatalog(input.appRoot),);@@ -341,29 +386,14 @@ export async function runRegistryFlow(input: {if (resolved.item === undefined) {throw new Error("The selected registry item is no longer available.");}- const inspected = await inspectItem(- input.prompter,+ const settled = await offerItem(+ input,deps,- input.appRoot,+ session,resolved.item,"manifest" in resolved ? resolved.manifest : undefined,- input.signal,);- if (inspected.kind !== "added") continue;-- session.add(- resolved.item.address,- itemLabel(resolved.item),- inspected.output,- inspected.setup,- );- const next = await session.continueAfterInstall({- appRoot: input.appRoot,- prompter: input.prompter,- signal: input.signal,- });- if (next === "add-more") continue;- return next;+ if (settled !== undefined) return settled;}} catch (error) {if (error instanceof WizardCancelledError) return { kind: "cancelled" };