The Open Framework for Building Agents
feat(eve): define answerable setup decisions (#1790)
OwenKephartea530ec7d87a
diff --git a/.changeset/bright-setup-foundations.md b/.changeset/bright-setup-foundations.mdnew file mode 100644index 000000000..8a763673e--- /dev/null+++ b/.changeset/bright-setup-foundations.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add wire-safe setup questions and shared interactive/headless prerequisite handling for answer-backed integration setup flows.diff --git a/packages/eve/src/setup/ask.test.ts b/packages/eve/src/setup/ask.test.tsindex 755950e89..8e3dc2d52 100644--- a/packages/eve/src/setup/ask.test.ts+++ b/packages/eve/src/setup/ask.test.ts@@ -176,7 +176,12 @@ describe("interactiveAsker", () => {const { prompter } = createFakePrompter({ password });const value = await interactiveAsker(prompter).ask(- text({ key: "apiKey", message: "Gateway key?", sensitive: true }),+ text({+ key: "apiKey",+ message: "Gateway key?",+ sensitive: true,+ environment: "AI_GATEWAY_API_KEY",+ }),);expect(value).toBe("s3cret");@@ -286,6 +291,50 @@ describe("headlessAsker", () => {});describe("withAnswers", () => {+ it("prefers an explicit sensitive answer over its environment variable", async () => {+ const previous = process.env.DISCORD_BOT_TOKEN;+ process.env.DISCORD_BOT_TOKEN = "environment-token";+ try {+ await expect(+ withAnswers({ token: "answer-token" })(headlessAsker()).ask(+ text({+ key: "token",+ message: "Token",+ required: true,+ sensitive: true,+ environment: "DISCORD_BOT_TOKEN",+ }),+ ),+ ).resolves.toBe("answer-token");+ } finally {+ if (previous === undefined) delete process.env.DISCORD_BOT_TOKEN;+ else process.env.DISCORD_BOT_TOKEN = previous;+ }+ });++ it("uses an environment-backed secret headlessly and refuses when absent", async () => {+ const previous = process.env.DISCORD_BOT_TOKEN;+ process.env.DISCORD_BOT_TOKEN = "environment-token";+ const question = text({+ key: "token",+ message: "Token",+ required: true,+ sensitive: true,+ environment: "DISCORD_BOT_TOKEN",+ });+ try {+ await expect(withAnswers({})(headlessAsker()).ask(question)).resolves.toBe(+ "environment-token",+ );+ delete process.env.DISCORD_BOT_TOKEN;+ await expect(withAnswers({})(headlessAsker()).ask(question)).rejects.toMatchObject({+ prerequisite: { kind: "environment", variable: "DISCORD_BOT_TOKEN" },+ });+ } finally {+ if (previous === undefined) delete process.env.DISCORD_BOT_TOKEN;+ else process.env.DISCORD_BOT_TOKEN = previous;+ }+ });it("resolves a matching key without reaching the inner rung", async () => {const events = recordingEvents();const asker = withAnswers({ color: "red" }, events)(untouchableAsker());@@ -512,7 +561,14 @@ describe("decorator stacking", () => {await expect(stack.ask(colorQuestion({ detected: BLUE }))).resolves.toBe(RED);// Without an answer, the policy resolves before the base is reached.await expect(- stack.ask(select({ key: "shade", message: "Shade?", options: [], detected: "dark" })),+ stack.ask(+ select({+ key: "shade",+ message: "Shade?",+ options: [{ id: "dark", label: "Dark", value: "dark" }],+ detected: "dark",+ }),+ ),).resolves.toBe("dark");expect(events.resolutions.map((resolution) => resolution.source)).toEqual(["answer",diff --git a/packages/eve/src/setup/ask.ts b/packages/eve/src/setup/ask.tsindex d741fdeae..2b0f90246 100644--- a/packages/eve/src/setup/ask.ts+++ b/packages/eve/src/setup/ask.ts@@ -14,7 +14,9 @@// Boxes only ever see `Asker`. Policies are presence/absence of decorators,// which also unlocks combinations a monolithic factory could not express.+import { SetupPrerequisiteRequired } from "./integrations/shared/prerequisite.js";import type { Prompter } from "./prompter.js";+import { optionById, requiredOptionId } from "./question-options.js";/** One choice in a select question. */export interface SelectOption<T> {@@ -90,7 +92,15 @@ export type Question<T> = {| {kind: "text";validate?: (raw: string) => string | null;- sensitive?: boolean;+ sensitive?: false;+ /** Presentation hint: ghost text shown while the input is empty. */+ placeholder?: string;+ }+ | {+ kind: "text";+ validate?: (raw: string) => string | null;+ sensitive: true;+ environment: string;/** Presentation hint: ghost text shown while the input is empty. */placeholder?: string;}@@ -148,17 +158,29 @@ export const confirm = (q: {kind: "confirm",});-/** Builds a text question without spelling the discriminant at call sites. */-export const text = (q: {+interface TextQuestionInput {key: string;message: string;detected?: string;recommended?: string;required?: boolean;validate?: (raw: string) => string | null;- sensitive?: boolean;placeholder?: string;-}): Question<string> => ({ ...q, kind: "text" });+}++/** Builds a text question without spelling the discriminant at call sites. */+export function text(+ q: TextQuestionInput & { sensitive: true; environment: string },+): Question<string>;+export function text(+ q: TextQuestionInput & { sensitive?: false; environment?: never },+): Question<string>;+export function text(+ q: TextQuestionInput &+ ({ sensitive: true; environment: string } | { sensitive?: false; environment?: never }),+): Question<string> {+ return { ...q, kind: "text" };+}/** The capability boxes see. Pure and flow-agnostic: Prompter's successor. */export interface Asker {@@ -209,11 +231,15 @@ export class InteractionRequired extends Error {/** Thrown when a pre-supplied answer fails the question's own validation. */export class InvalidAnswerError extends Error {- readonly key: string;- constructor(key: string, message: string) {+ readonly question: AnyQuestion;+ constructor(question: AnyQuestion, message: string) {super(message);this.name = "InvalidAnswerError";- this.key = key;+ this.question = question;+ }++ get key(): string {+ return this.question.key;}}@@ -245,11 +271,11 @@ function announce<T>(function coerceAnswer<T>(question: Question<T>, raw: unknown): T {if (question.kind === "select") {const id = String(raw);- const match = question.options.find((option) => option.id === id);+ const match = optionById(question, id);if (!match) {const ids = question.options.map((option) => option.id).join(", ");throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": ${id}. Expected one of: ${ids}.`,);}@@ -260,7 +286,7 @@ function coerceAnswer<T>(question: Question<T>, raw: unknown): T {typeof raw === "boolean" ? raw : raw === "true" ? true : raw === "false" ? false : null;if (value === null) {throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": expected a boolean.`,);}@@ -268,7 +294,7 @@ function coerceAnswer<T>(question: Question<T>, raw: unknown): T {}const value = String(raw);const problem = question.validate?.(value);- if (problem) throw new InvalidAnswerError(question.key, problem);+ if (problem) throw new InvalidAnswerError(question, problem);return value as T;}@@ -282,25 +308,25 @@ function coerceAnswer<T>(question: Question<T>, raw: unknown): T {function coerceManyAnswer<T>(question: MultiSelectQuestion<T>, raw: unknown): T[] {if (!Array.isArray(raw)) {throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": expected an array of option ids.`,);}const values: T[] = [];for (const item of raw) {const id = String(item);- const match = question.options.find((option) => option.id === id);+ const match = optionById(question, id);if (!match) {const ids = question.options.map((option) => option.id).join(", ");throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": ${id}. Expected one of: ${ids}.`,);}if (match.disabled) {const reason = match.disabledReason === undefined ? "" : ` (${match.disabledReason})`;throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": ${id} is unavailable${reason}.`,);}@@ -330,7 +356,11 @@ async function renderQuestion<T>(prompter: Prompter, question: Question<T>): ProinitialValue:preselected === undefined? undefined- : question.options.find((option) => option.value === preselected)?.id,+ : requiredOptionId(+ question,+ preselected,+ question.detected !== undefined ? "detected value" : "recommendation",+ ),search: question.search,placeholder: question.placeholder,});@@ -392,9 +422,13 @@ async function renderManyQuestion<T>(initialValues:premarked === undefined? undefined- : question.options- .filter((option) => premarked.includes(option.value))- .map((option) => option.id),+ : premarked.map((value) =>+ requiredOptionId(+ question,+ value,+ question.detected !== undefined ? "detected value" : "recommendation",+ ),+ ),required: question.requireSelection,search: question.search,placeholder: question.placeholder,@@ -404,10 +438,10 @@ async function renderManyQuestion<T>(// re-judging its output would move box-level guards (e.g. the Slack/Vercel// assert in select-channels) behind a different error.return chosen.map((id) => {- const match = question.options.find((option) => option.id === id);+ const match = optionById(question, id);if (!match) {throw new InvalidAnswerError(- question.key,+ question,`Invalid answer for "${question.key}": ${id} is not an option id.`,);}@@ -453,10 +487,10 @@ export function headlessAsker(events?: AskerEvents): Asker {return {// Async so refusal and skip surface as rejections, like every other rung.async ask<T>(question: Question<T>): Promise<T> {- return refuse(question as Question<unknown>);+ return refuse(question);},async askMany<T>(question: MultiSelectQuestion<T>): Promise<T[]> {- return refuse(question as MultiSelectQuestion<unknown>);+ return refuse(question);},};}@@ -477,6 +511,22 @@ export function withAnswers(const value = coerceAnswer(question, answers[question.key]);return announce(events, question.key, value, "answer");}+ if (question.kind === "text" && question.sensitive === true) {+ const environmentValue = process.env[question.environment];+ if (environmentValue !== undefined) return coerceAnswer(question, environmentValue);+ try {+ return await inner.ask(question);+ } catch (error) {+ if (!(error instanceof InteractionRequired)) throw error;+ throw new SetupPrerequisiteRequired({+ kind: "environment",+ code: question.key,+ message: `Set ${question.environment}, then retry setup.`,+ variable: question.environment,+ sensitive: true,+ });+ }+ }return inner.ask(question);},async askMany<T>(question: MultiSelectQuestion<T>): Promise<T[]> {@@ -527,9 +577,15 @@ export function withPolicy(policy: AnswerPolicy, events?: AskerEvents): AskerDecasync ask<T>(question: Question<T>): Promise<T> {if (policy === "assume") {if (question.detected !== undefined) {+ if (question.kind === "select") {+ requiredOptionId(question, question.detected, "detected value");+ }return announce(events, question.key, question.detected, "detected");}if (question.recommended !== undefined) {+ if (question.kind === "select") {+ requiredOptionId(question, question.recommended, "recommendation");+ }return announce(events, question.key, question.recommended, "assumed");}// Assume minimizes interaction: the unknowable is skipped when the@@ -555,9 +611,15 @@ export function withPolicy(policy: AnswerPolicy, events?: AskerEvents): AskerDecasync askMany<T>(question: MultiSelectQuestion<T>): Promise<T[]> {if (policy === "assume") {if (question.detected !== undefined) {+ for (const value of question.detected) {+ requiredOptionId(question, value, "detected value");+ }return announce(events, question.key, [...question.detected], "detected");}if (question.recommended !== undefined) {+ for (const value of question.recommended) {+ requiredOptionId(question, value, "recommendation");+ }return announce(events, question.key, [...question.recommended], "assumed");}if (!question.required) {diff --git a/packages/eve/src/setup/boxes/resolve-provisioning.ts b/packages/eve/src/setup/boxes/resolve-provisioning.tsindex 64764e3f4..ca7a44711 100644--- a/packages/eve/src/setup/boxes/resolve-provisioning.ts+++ b/packages/eve/src/setup/boxes/resolve-provisioning.ts@@ -392,6 +392,7 @@ export function resolveProvisioning(key: "gateway-api-key",message: "Enter your AI_GATEWAY_API_KEY",sensitive: true,+ environment: "AI_GATEWAY_API_KEY",validate: (value) => (value.trim().length === 0 ? "API key cannot be empty." : null),required: true,}),diff --git a/packages/eve/src/setup/integrations/discord/setup.ts b/packages/eve/src/setup/integrations/discord/setup.tsindex ed6eff010..330698510 100644--- a/packages/eve/src/setup/integrations/discord/setup.ts+++ b/packages/eve/src/setup/integrations/discord/setup.ts@@ -88,6 +88,7 @@ export async function setupDiscord(message: "Discord bot token",required: true,sensitive: true,+ environment: "DISCORD_BOT_TOKEN",}),)).trim();diff --git a/packages/eve/src/setup/integrations/github/setup.test.ts b/packages/eve/src/setup/integrations/github/setup.test.tsindex 2379dea31..5de6e97b2 100644--- a/packages/eve/src/setup/integrations/github/setup.test.ts+++ b/packages/eve/src/setup/integrations/github/setup.test.ts@@ -69,7 +69,10 @@ describe("GitHub setup", () => {{appRoot: "/project",environment: integrationSetupEnvironment("authenticated", { kind: "unresolved" }),- ui: createIntegrationSetupUi({ asker: { ask: vi.fn(), askMany }, prompter: fake.prompter }),+ ui: createIntegrationSetupUi({+ asker: { ask: vi.fn(), askMany },+ prompter: fake.prompter,+ }),},deps(),);diff --git a/packages/eve/src/setup/integrations/photon/setup-flow.ts b/packages/eve/src/setup/integrations/photon/setup-flow.tsindex f259fdbd6..f34bc653d 100644--- a/packages/eve/src/setup/integrations/photon/setup-flow.ts+++ b/packages/eve/src/setup/integrations/photon/setup-flow.ts@@ -136,6 +136,7 @@ async function choosePhotonProject(message: "Photon project secret",required: true,sensitive: true,+ environment: "IMESSAGE_PROJECT_SECRET",}),);return { photonProject: { projectId: projectId.trim(), projectSecret: projectSecret.trim() } };diff --git a/packages/eve/src/setup/integrations/shared/prerequisite.ts b/packages/eve/src/setup/integrations/shared/prerequisite.tsnew file mode 100644index 000000000..696326cc1--- /dev/null+++ b/packages/eve/src/setup/integrations/shared/prerequisite.ts@@ -0,0 +1,14 @@+export type SetupPrerequisite =+ | { kind: "command"; code: string; message: string; command: string }+ | { kind: "environment"; code: string; message: string; variable: string; sensitive: true };++/** A read-only setup refusal whose prerequisite must be satisfied by the caller. */+export class SetupPrerequisiteRequired extends Error {+ readonly prerequisite: SetupPrerequisite;++ constructor(prerequisite: SetupPrerequisite) {+ super(prerequisite.message);+ this.name = "SetupPrerequisiteRequired";+ this.prerequisite = prerequisite;+ }+}diff --git a/packages/eve/src/setup/question-options.ts b/packages/eve/src/setup/question-options.tsnew file mode 100644index 000000000..9982d78ea--- /dev/null+++ b/packages/eve/src/setup/question-options.ts@@ -0,0 +1,38 @@+export interface QuestionOption {+ id: string;+ value: unknown;+}++interface QuestionWithOptions<O extends QuestionOption> {+ key: string;+ options: readonly O[];+}++/** Finds an option by the stable id used by prompt and wire boundaries. */+export function optionById<O extends QuestionOption>(+ question: QuestionWithOptions<O>,+ id: unknown,+): O | undefined {+ return question.options.find((option) => option.id === String(id));+}++/** Finds an option by its in-process rich value. */+export function optionByValue<O extends QuestionOption>(+ question: QuestionWithOptions<O>,+ value: O["value"],+): O | undefined {+ return question.options.find((option) => option.value === value);+}++/** Maps a rich value to its stable id, rejecting an invalid question definition. */+export function requiredOptionId<O extends QuestionOption>(+ question: QuestionWithOptions<O>,+ value: O["value"],+ role: string,+): string {+ const option = optionByValue(question, value);+ if (option === undefined) {+ throw new Error(`Question "${question.key}" has a ${role} that is not one of its options.`);+ }+ return option.id;+}diff --git a/packages/eve/src/setup/setup-question-wire.test.ts b/packages/eve/src/setup/setup-question-wire.test.tsnew file mode 100644index 000000000..3adea04f3--- /dev/null+++ b/packages/eve/src/setup/setup-question-wire.test.ts@@ -0,0 +1,142 @@+import { describe, expect, it } from "vitest";+import { confirm, select, text, type MultiSelectQuestion } from "./ask.js";+import { setupQuestionToWire } from "./setup-question-wire.js";++describe("setupQuestionToWire", () => {+ it("projects selects to stable option ids without runtime values", () => {+ const value = { internal: true };+ const wire = setupQuestionToWire(+ select({+ key: "mode",+ message: "Mode?",+ options: [{ id: "managed", label: "Managed", value }],+ recommended: value,+ required: true,+ }),+ );+ expect(wire).toEqual({+ kind: "select",+ key: "mode",+ message: "Mode?",+ required: true,+ recommended: "managed",+ options: [{ id: "managed", label: "Managed" }],+ });+ expect(JSON.stringify(wire)).not.toContain("internal");+ });+ it("projects confirms and ordinary text without runtime behavior", () => {+ expect(+ setupQuestionToWire(+ confirm({ key: "deploy", message: "Deploy?", recommended: true, required: true }),+ ),+ ).toEqual({+ kind: "confirm",+ key: "deploy",+ message: "Deploy?",+ required: true,+ recommended: true,+ });+ expect(+ setupQuestionToWire(+ text({+ key: "name",+ message: "Name?",+ placeholder: "my-agent",+ validate: () => "not serialized",+ }),+ ),+ ).toEqual({+ kind: "text",+ key: "name",+ message: "Name?",+ required: false,+ placeholder: "my-agent",+ sensitive: false,+ });+ });++ it("projects multi-select availability and rich recommendations to ids", () => {+ const locked = { internal: "locked" };+ const optional = { internal: "optional" };+ const question: MultiSelectQuestion<object> = {+ key: "components",+ message: "Components?",+ options: [+ {+ id: "core",+ label: "Core",+ value: locked,+ locked: true,+ lockedReason: "Always included",+ },+ {+ id: "extra",+ label: "Extra",+ value: optional,+ hint: "Optional tools",+ disabled: true,+ disabledReason: "Unavailable",+ },+ ],+ recommended: [locked],+ };++ const wire = setupQuestionToWire(question);++ expect(wire).toEqual({+ kind: "multi-select",+ key: "components",+ message: "Components?",+ required: false,+ recommended: ["core"],+ options: [+ { id: "core", label: "Core", locked: true, lockedReason: "Always included" },+ {+ id: "extra",+ label: "Extra",+ hint: "Optional tools",+ disabled: true,+ disabledReason: "Unavailable",+ },+ ],+ });+ expect(JSON.stringify(wire)).not.toContain("internal");+ });++ it("rejects recommendations that are not represented by an option id", () => {+ const known = { id: "known" };+ const unknown = { id: "unknown" };++ expect(() =>+ setupQuestionToWire(+ select({+ key: "mode",+ message: "Mode?",+ options: [{ id: "known", label: "Known", value: known }],+ recommended: unknown,+ }),+ ),+ ).toThrow('Question "mode" has a recommendation that is not one of its options.');+ });++ it("exposes only the environment name for sensitive questions", () => {+ expect(+ setupQuestionToWire(+ text({+ key: "token",+ message: "Token",+ sensitive: true,+ environment: "TOKEN",+ required: true,+ }),+ ),+ ).toEqual({+ kind: "environment",+ key: "token",+ message: "Token",+ required: true,+ variable: "TOKEN",+ sensitive: true,+ });+ });+});diff --git a/packages/eve/src/setup/setup-question-wire.ts b/packages/eve/src/setup/setup-question-wire.tsnew file mode 100644index 000000000..6f834f494--- /dev/null+++ b/packages/eve/src/setup/setup-question-wire.ts@@ -0,0 +1,99 @@+import type { AnyQuestion } from "./ask.js";+import { requiredOptionId } from "./question-options.js";++export interface SetupWireOption {+ id: string;+ label: string;+ hint?: string;+ disabled?: boolean;+ disabledReason?: string;+ locked?: boolean;+ lockedReason?: string;+}++type SharedWireQuestion = { key: string; message: string; required: boolean };+export type SetupWireQuestion =+ | (SharedWireQuestion & { kind: "confirm"; recommended?: boolean })+ | (SharedWireQuestion & { kind: "text"; placeholder?: string; sensitive?: false })+ | (SharedWireQuestion & { kind: "environment"; variable: string; sensitive: true })+ | (SharedWireQuestion & {+ kind: "select";+ recommended?: string;+ options: readonly SetupWireOption[];+ })+ | (SharedWireQuestion & {+ kind: "multi-select";+ recommended?: readonly string[];+ options: readonly SetupWireOption[];+ });++function wireOptions(question: {+ options: readonly {+ id: string;+ label: string;+ hint?: string;+ disabled?: boolean;+ disabledReason?: string;+ locked?: boolean;+ lockedReason?: string;+ }[];+}): SetupWireOption[] {+ return question.options.map((option) => {+ const wire: SetupWireOption = { id: option.id, label: option.label };+ if (option.hint !== undefined) wire.hint = option.hint;+ if (option.disabled !== undefined) wire.disabled = option.disabled;+ if (option.disabledReason !== undefined) wire.disabledReason = option.disabledReason;+ if (option.locked !== undefined) wire.locked = option.locked;+ if (option.lockedReason !== undefined) wire.lockedReason = option.lockedReason;+ return wire;+ });+}++function sharedQuestion(question: AnyQuestion): SharedWireQuestion {+ return { key: question.key, message: question.message, required: question.required === true };+}++/** Removes runtime values and validators from one internal setup question. */+export function setupQuestionToWire(question: AnyQuestion): SetupWireQuestion {+ const shared = sharedQuestion(question);+ if (!("kind" in question)) {+ const many = question;+ const wire: Extract<SetupWireQuestion, { kind: "multi-select" }> = {+ ...shared,+ kind: "multi-select",+ options: wireOptions(many),+ };+ if (many.recommended !== undefined) {+ wire.recommended = many.recommended.map((value) =>+ requiredOptionId(many, value, "recommendation"),+ );+ }+ return wire;+ }+ const single = question;+ if (single.kind === "confirm") {+ const wire: Extract<SetupWireQuestion, { kind: "confirm" }> = { ...shared, kind: "confirm" };+ if (single.recommended !== undefined) wire.recommended = single.recommended as boolean;+ return wire;+ }+ if (single.kind === "text") {+ if (single.sensitive === true)+ return { ...shared, kind: "environment", variable: single.environment, sensitive: true };+ const wire: Extract<SetupWireQuestion, { kind: "text" }> = {+ ...shared,+ kind: "text",+ sensitive: false,+ };+ if (single.placeholder !== undefined) wire.placeholder = single.placeholder;+ return wire;+ }+ const wire: Extract<SetupWireQuestion, { kind: "select" }> = {+ ...shared,+ kind: "select",+ options: wireOptions(single),+ };+ if (single.recommended !== undefined) {+ wire.recommended = requiredOptionId(single, single.recommended, "recommendation");+ }+ return wire;+}