Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 agent
Type 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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" };