@amplitude/wizard 1.0.0-beta.0

package/dist/src/frameworks/unity/utils.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectUnityProject = detectUnityProject;
+exports.isAmplitudePluginPresent = isAmplitudePluginPresent;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Returns true when the directory contains a Unity project.
+ * Primary signal: ProjectSettings/ProjectVersion.txt — Unity-specific,
+ * present in every Unity project since 2017+.
+ */
+function detectUnityProject(options) {
+    return Promise.resolve(fs.existsSync(path.join(options.installDir, 'ProjectSettings', 'ProjectVersion.txt')));
+}
+/**
+ * Returns true if the Amplitude Unity plugin is already present,
+ * either via UPM (Packages/manifest.json) or manual import (Assets/).
+ */
+function isAmplitudePluginPresent(options) {
+    // Check UPM manifest
+    const manifestPath = path.join(options.installDir, 'Packages', 'manifest.json');
+    try {
+        const manifest = fs.readFileSync(manifestPath, 'utf-8');
+        if (manifest.includes('amplitude/unity-plugin'))
+            return true;
+    }
+    catch {
+        // no manifest
+    }
+    // Check for manually imported Assets
+    const assetsAmplitudePath = path.join(options.installDir, 'Assets', 'Amplitude');
+    return fs.existsSync(assetsAmplitudePath);
+}

package/dist/src/frameworks/unreal/unreal-wizard-agent.d.ts

@@ -0,0 +1,6 @@
+import type { FrameworkConfig } from '../../lib/framework-config';
+type UnrealContext = {
+    pluginAlreadyPresent?: boolean;
+};
+export declare const UNREAL_AGENT_CONFIG: FrameworkConfig<UnrealContext>;
+export {};

package/dist/src/frameworks/unreal/unreal-wizard-agent.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNREAL_AGENT_CONFIG = void 0;
+const package_manager_detection_1 = require("../../lib/package-manager-detection");
+const constants_1 = require("../../lib/constants");
+const utils_1 = require("./utils");
+exports.UNREAL_AGENT_CONFIG = {
+    metadata: {
+        name: 'Unreal Engine',
+        integration: constants_1.Integration.unreal,
+        beta: true,
+        docsUrl: 'https://amplitude.com/docs/sdks/analytics/unreal/unreal-sdk',
+        preRunNotice: 'Close the Unreal Editor before running the wizard to avoid file conflicts.',
+        gatherContext: async (options) => {
+            const pluginAlreadyPresent = await (0, utils_1.isAmplitudePluginPresent)(options);
+            return { pluginAlreadyPresent };
+        },
+    },
+    detection: {
+        packageName: 'AmplitudeUnreal',
+        packageDisplayName: 'Unreal Engine',
+        usesPackageJson: false,
+        getVersion: () => undefined,
+        detect: utils_1.detectUnrealProject,
+        detectPackageManager: package_manager_detection_1.unrealPackageManager,
+    },
+    environment: {
+        // API key goes in Config/DefaultEngine.ini — no .env files in Unreal projects
+        uploadToHosting: false,
+        getEnvVars: () => ({}),
+    },
+    analytics: {
+        getTags: (context) => ({
+            pluginAlreadyPresent: context.pluginAlreadyPresent ? 'true' : 'false',
+        }),
+    },
+    prompts: {
+        projectTypeDetection: 'This is an Unreal Engine project. Look for a .uproject file at the project root to confirm.',
+        packageInstallation: 'There is no package manager for Unreal Engine plugins. Download AmplitudeUnreal.zip from https://github.com/amplitude/Amplitude-Unreal/releases/latest, then extract it into Plugins/AmplitudeUnreal/ inside the project directory. Use Bash to run: mkdir -p Plugins/AmplitudeUnreal && curl -L <release-url> -o /tmp/AmplitudeUnreal.zip && unzip -o /tmp/AmplitudeUnreal.zip -d Plugins/AmplitudeUnreal/',
+        getAdditionalContextLines: (context) => {
+            const lines = [
+                `Framework docs ID: unreal (use amplitude://docs/frameworks/unreal for documentation)`,
+                `Plugin: AmplitudeUnreal — manual install into Plugins/AmplitudeUnreal/`,
+                `API key storage: Config/DefaultEngine.ini under [Analytics] section`,
+                `Required INI settings:`,
+                `  [Analytics]`,
+                `  ProviderModuleName=Amplitude`,
+                `  AmplitudeApiKey=<api_key>`,
+                `C++ usage: FAnalytics::Get().GetDefaultConfiguredProvider()->RecordEvent(TEXT("Event Name"));`,
+                `IMPORTANT: The Amplitude Unreal plugin only executes on Apple platforms (iOS/macOS/tvOS). On other platforms all calls are no-ops.`,
+                `IMPORTANT: No EU data residency, no server zone configuration, and no batch/flush interval settings are available in this SDK.`,
+            ];
+            if (context.pluginAlreadyPresent) {
+                lines.unshift('Amplitude plugin already present at Plugins/AmplitudeUnreal/ — skip download, proceed to INI configuration.');
+            }
+            return lines;
+        },
+    },
+    ui: {
+        successMessage: 'Amplitude integration complete',
+        estimatedDurationMinutes: 10,
+        getOutroChanges: (context) => [
+            context.pluginAlreadyPresent
+                ? 'Amplitude plugin was already present — skipped download'
+                : 'Downloaded and extracted AmplitudeUnreal plugin into Plugins/AmplitudeUnreal/',
+            'Configured AmplitudeApiKey in Config/DefaultEngine.ini',
+            'Enabled Amplitude as the analytics provider',
+        ],
+        getOutroNextSteps: () => [
+            'Open the Unreal Editor and enable the plugin: Settings > Plugins > Analytics > AmplitudeUnreal',
+            'Rebuild your project from source',
+            'Call FAnalytics::Get().GetDefaultConfiguredProvider()->StartSession() on game start',
+            'Visit your Amplitude dashboard to see incoming events',
+            'Note: events are only sent on iOS, macOS, and tvOS — other platforms are no-ops',
+        ],
+    },
+};

package/dist/src/frameworks/unreal/utils.d.ts

@@ -0,0 +1,10 @@
+import type { WizardOptions } from '../../utils/types';
+/**
+ * Returns true when the directory contains an Unreal Engine project.
+ * Primary signal: a .uproject file at the project root (Unreal-specific JSON manifest).
+ */
+export declare function detectUnrealProject(options: Pick<WizardOptions, 'installDir'>): Promise<boolean>;
+/**
+ * Returns true if the Amplitude plugin is already extracted into the project.
+ */
+export declare function isAmplitudePluginPresent(options: Pick<WizardOptions, 'installDir'>): Promise<boolean>;

package/dist/src/frameworks/unreal/utils.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectUnrealProject = detectUnrealProject;
+exports.isAmplitudePluginPresent = isAmplitudePluginPresent;
+const fast_glob_1 = __importDefault(require("fast-glob"));
+/**
+ * Returns true when the directory contains an Unreal Engine project.
+ * Primary signal: a .uproject file at the project root (Unreal-specific JSON manifest).
+ */
+async function detectUnrealProject(options) {
+    const uprojectFiles = await (0, fast_glob_1.default)('*.uproject', {
+        cwd: options.installDir,
+        deep: 1,
+    });
+    return uprojectFiles.length > 0;
+}
+/**
+ * Returns true if the Amplitude plugin is already extracted into the project.
+ */
+async function isAmplitudePluginPresent(options) {
+    const upluginFiles = await (0, fast_glob_1.default)('Plugins/AmplitudeUnreal/Amplitude.uplugin', {
+        cwd: options.installDir,
+        deep: 3,
+    });
+    return upluginFiles.length > 0;
+}

package/dist/src/frameworks/vue/vue-wizard-agent.d.ts

@@ -0,0 +1,4 @@
+import type { FrameworkConfig } from '../../lib/framework-config';
+type VueContext = Record<string, unknown>;
+export declare const VUE_AGENT_CONFIG: FrameworkConfig<VueContext>;
+export {};

package/dist/src/frameworks/vue/vue-wizard-agent.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VUE_AGENT_CONFIG = void 0;
+const package_manager_detection_1 = require("../../lib/package-manager-detection");
+const constants_1 = require("../../lib/constants");
+const package_json_1 = require("../../utils/package-json");
+const setup_utils_1 = require("../../utils/setup-utils");
+const semver_1 = require("../../utils/semver");
+const getVueVersionBucket = (0, semver_1.createVersionBucket)();
+exports.VUE_AGENT_CONFIG = {
+    metadata: {
+        name: 'Vue',
+        integration: constants_1.Integration.vue,
+        docsUrl: 'https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2',
+        beta: true,
+    },
+    detection: {
+        packageName: 'vue',
+        packageDisplayName: 'Vue',
+        getVersion: (packageJson) => (0, package_json_1.getPackageVersion)('vue', packageJson),
+        getVersionBucket: getVueVersionBucket,
+        getInstalledVersion: async (options) => {
+            const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
+            return packageJson ? (0, package_json_1.getPackageVersion)('vue', packageJson) : undefined;
+        },
+        detect: async (options) => {
+            const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
+            return packageJson ? (0, package_json_1.hasPackageInstalled)('vue', packageJson) : false;
+        },
+        detectPackageManager: package_manager_detection_1.detectNodePackageManagers,
+    },
+    environment: {
+        uploadToHosting: true,
+        getEnvVars: (apiKey, _host) => ({
+            VITE_AMPLITUDE_API_KEY: apiKey,
+        }),
+    },
+    analytics: {
+        getTags: () => ({}),
+    },
+    prompts: {
+        projectTypeDetection: 'This is a JavaScript/TypeScript project. Look for package.json and lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to confirm.',
+        getAdditionalContextLines: () => {
+            const frameworkId = 'vue';
+            return [
+                `Framework docs ID: ${frameworkId} (use amplitude://docs/frameworks/${frameworkId} for documentation)`,
+                `Preferred Amplitude SDK: @amplitude/unified (prefer over @amplitude/analytics-browser for new browser integrations)`,
+            ];
+        },
+    },
+    ui: {
+        successMessage: 'Amplitude integration complete',
+        estimatedDurationMinutes: 5,
+        getOutroChanges: () => [
+            'Analyzed your Vue project structure',
+            'Created and configured Amplitude initializers',
+            'Integrated Amplitude into your application',
+        ],
+        getOutroNextSteps: () => [
+            'Start your development server to see Amplitude in action',
+            'Visit your Amplitude dashboard to see incoming events',
+        ],
+    },
+};

package/dist/src/lib/agent-hooks.d.ts

@@ -0,0 +1,26 @@
+/** Mirror of HookEvent from @anthropic-ai/claude-agent-sdk */
+export type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'Notification' | 'UserPromptSubmit' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PermissionRequest';
+/** Mirror of HookCallback from @anthropic-ai/claude-agent-sdk */
+export type HookCallback = (input: Record<string, unknown>, toolUseID: string | undefined, options: {
+    signal: AbortSignal;
+}) => Promise<Record<string, unknown>>;
+/** Mirror of HookCallbackMatcher from @anthropic-ai/claude-agent-sdk */
+export interface HookCallbackMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+    timeout?: number;
+}
+export interface AgentHook {
+    name: HookEvent;
+    pre: boolean;
+    implemented: boolean;
+    description: string;
+    notes: string;
+}
+export declare const agentHooks: AgentHook[];
+/**
+ * Builds the SDK hooks config from the implemented agentHooks registry.
+ * Only hooks present in both the registry (implemented: true) and the
+ * callbacks map are included in the output.
+ */
+export declare function buildHooksConfig(callbacks: Partial<Record<HookEvent, HookCallback>>): Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/src/lib/agent-hooks.js

@@ -0,0 +1,118 @@
+"use strict";
+// Agent hook definitions that are supported by the Anthropic SDK.
+// See docs/flows.md for flow details.
+//
+// SDK types are mirrored locally to avoid ESM/CJS import issues with
+// @anthropic-ai/claude-agent-sdk (which is dynamically imported elsewhere).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentHooks = void 0;
+exports.buildHooksConfig = buildHooksConfig;
+exports.agentHooks = [
+    {
+        name: 'PreToolUse',
+        pre: true,
+        implemented: true,
+        description: 'Tool call request (can block or modify)',
+        notes: 'Block dangerous shell commands',
+    },
+    {
+        name: 'PostToolUse',
+        pre: true,
+        implemented: true,
+        description: 'Tool execution result',
+        notes: 'Log all file changes to audit trail',
+    },
+    {
+        name: 'PostToolUseFailure',
+        pre: true,
+        implemented: true,
+        description: 'Tool execution failure',
+        notes: 'Handle or log tool errors',
+    },
+    {
+        name: 'UserPromptSubmit',
+        pre: true,
+        implemented: true,
+        description: 'User prompt submission',
+        notes: 'Inject additional context into prompts',
+    },
+    {
+        name: 'Stop',
+        pre: true,
+        implemented: true,
+        description: 'Agent execution stop',
+        notes: 'Drain feature queue, collect remark, then allow stop',
+    },
+    {
+        name: 'SubagentStart',
+        pre: true,
+        implemented: true,
+        description: 'Subagent initialization',
+        notes: 'Track parallel task spawning',
+    },
+    {
+        name: 'SubagentStop',
+        pre: true,
+        implemented: true,
+        description: 'Subagent completion',
+        notes: 'Aggregate results from parallel tasks',
+    },
+    {
+        name: 'PreCompact',
+        pre: true,
+        implemented: true,
+        description: 'Conversation compaction request',
+        notes: 'Archive full transcript before summarizing',
+    },
+    {
+        name: 'PermissionRequest',
+        pre: true,
+        implemented: true,
+        description: 'Permission dialog would be displayed',
+        notes: 'Custom permission handling',
+    },
+    {
+        name: 'SessionStart',
+        pre: false,
+        implemented: true,
+        description: 'Session initialization',
+        notes: 'Initialize logging and telemetry',
+    },
+    {
+        name: 'SessionEnd',
+        pre: false,
+        implemented: true,
+        description: 'Session termination',
+        notes: 'Clean up temporary resources',
+    },
+    {
+        name: 'Notification',
+        pre: true,
+        implemented: true,
+        description: 'Agent status messages',
+        notes: 'Send agent status updates to Slack or PagerDuty',
+    },
+];
+const HOOK_TIMEOUTS = {
+    Stop: 30,
+};
+/**
+ * Builds the SDK hooks config from the implemented agentHooks registry.
+ * Only hooks present in both the registry (implemented: true) and the
+ * callbacks map are included in the output.
+ */
+function buildHooksConfig(callbacks) {
+    const config = {};
+    for (const hook of exports.agentHooks.filter((h) => h.implemented)) {
+        const callback = callbacks[hook.name];
+        if (!callback)
+            continue;
+        const timeout = HOOK_TIMEOUTS[hook.name];
+        const matcher = {
+            hooks: [callback],
+            ...(timeout !== undefined && { timeout }),
+        };
+        config[hook.name] = [matcher];
+    }
+    return config;
+}

package/dist/src/lib/agent-interface.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Shared agent interface for Amplitude wizards
+ * Uses Claude Agent SDK directly with Amplitude LLM gateway
+ */
+import { type SpinnerHandle } from '../ui';
+import type { WizardOptions } from '../utils/types';
+import { type AdditionalFeature } from './wizard-session';
+import type { PackageManagerDetector } from './package-manager-detection';
+import type { SDKMessage } from './middleware/types';
+import { type HookCallback } from './agent-hooks';
+type McpServersConfig = Record<string, unknown>;
+export declare const AgentSignals: {
+    /** Signal emitted when the agent reports progress to the user */
+    readonly STATUS: "[STATUS]";
+    /** Signal emitted when the agent cannot access the Amplitude MCP server */
+    readonly ERROR_MCP_MISSING: "[ERROR-MCP-MISSING]";
+    /** Signal emitted when the agent cannot access the setup resource */
+    readonly ERROR_RESOURCE_MISSING: "[ERROR-RESOURCE-MISSING]";
+    /** Signal emitted when the agent provides a remark about its run */
+    readonly WIZARD_REMARK: "[WIZARD-REMARK]";
+    /** Signal prefix for benchmark logging */
+    readonly BENCHMARK: "[BENCHMARK]";
+};
+export type AgentSignal = (typeof AgentSignals)[keyof typeof AgentSignals];
+/**
+ * Error types that can be returned from agent execution.
+ * These correspond to the error signals that the agent emits.
+ */
+export declare enum AgentErrorType {
+    /** Agent could not access the Amplitude MCP server */
+    MCP_MISSING = "WIZARD_MCP_MISSING",
+    /** Agent could not access the setup resource */
+    RESOURCE_MISSING = "WIZARD_RESOURCE_MISSING",
+    /** API rate limit exceeded */
+    RATE_LIMIT = "WIZARD_RATE_LIMIT",
+    /** Generic API error */
+    API_ERROR = "WIZARD_API_ERROR",
+    /** Authentication failed — bearer token invalid or expired */
+    AUTH_ERROR = "WIZARD_AUTH_ERROR"
+}
+/**
+ * Check if .claude/settings.json in the project directory contains env
+ * overrides for blocking keys that block the Wizard from accessing the Amplitude LLM Gateway.
+ * Returns the list of matched key names, or an empty array if none found.
+ */
+export declare function checkClaudeSettingsOverrides(workingDirectory: string): string[];
+/**
+ * Copy .claude/settings.json to .wizard-backup (overwriting if it exists),
+ * then remove the original so the SDK doesn't load the blocking overrides.
+ */
+export declare function backupAndFixClaudeSettings(workingDirectory: string): boolean;
+/**
+ * Restore .claude/settings.json from .wizard-backup.
+ * Copies (not moves) so the backup is preserved.
+ */
+export declare function restoreClaudeSettings(workingDirectory: string): void;
+export type AgentConfig = {
+    workingDirectory: string;
+    amplitudeMcpUrl: string;
+    amplitudeApiKey: string;
+    amplitudeBearerToken: string;
+    amplitudeApiHost: string;
+    additionalMcpServers?: Record<string, {
+        url: string;
+    }>;
+    detectPackageManager: PackageManagerDetector;
+    /** Feature flag key -> variant (evaluated at start of run). */
+    wizardFlags?: Record<string, string>;
+    wizardMetadata?: Record<string, string>;
+    /** When true, omit the amplitude-wizard MCP server (e.g. for generic/quickstart path). */
+    skipAmplitudeMcp?: boolean;
+    /** Remote skills URL. When set, skills are downloaded instead of using bundled copies. */
+    skillsBaseUrl?: string;
+};
+/**
+ * Create a stop hook callback that drains the additional feature queue,
+ * then collects a remark, then allows stop.
+ *
+ * Three-phase logic using closure state:
+ *   Phase 1 — drain queue: block with each feature prompt in order
+ *   Phase 2 — collect remark (once): block with remark prompt
+ *   Phase 3 — allow stop: return {}
+ *
+ * If `isAuthError()` returns true, all phases are skipped and stop is
+ * allowed immediately — the agent cannot respond when auth has failed.
+ */
+export declare function createStopHook(featureQueue: readonly AdditionalFeature[], isAuthError?: () => boolean): HookCallback;
+/**
+ * Configuration object returned by initializeAgent / getAgent.
+ */
+export type AgentRunConfig = {
+    workingDirectory: string;
+    mcpServers: McpServersConfig;
+    model: string;
+    wizardFlags?: Record<string, string>;
+    wizardMetadata?: Record<string, string>;
+    /** When true, bypass the Amplitude gateway and run via the local `claude` CLI. */
+    useLocalClaude?: boolean;
+    /** When true, ANTHROPIC_API_KEY is passed through to the SDK instead of the gateway. */
+    useDirectApiKey?: boolean;
+};
+/**
+ * Select wizard metadata from WIZARD_VARIANTS using the variant feature flag.
+ * If the flag is missing or the value is not in config, returns the "base" variant (VARIANT: "base").
+ */
+export declare function buildWizardMetadata(flags?: Record<string, string>): Record<string, string>;
+/**
+ * Check if command is a Amplitude skill installation from MCP.
+ * We control the MCP server, so we only need to verify:
+ * 1. It installs to .claude/skills/
+ * 2. It downloads from our GitHub releases or localhost (dev)
+ */
+export declare function isSkillInstallCommand(command: string): boolean;
+/**
+ * Check if command is an allowed package manager command.
+ * Matches: <pkg-manager> [run|exec] <safe-script> [args...]
+ */
+export declare function matchesAllowedPrefix(command: string): boolean;
+/**
+ * Permission hook that allows only safe commands.
+ * - Package manager install commands
+ * - Build/typecheck/lint commands for verification
+ * - Piping to tail/head for output limiting is allowed
+ * - Stderr redirection (2>&1) is allowed
+ * - Amplitude skill installation commands from MCP
+ */
+export declare function wizardCanUseTool(toolName: string, input: Record<string, unknown>): {
+    behavior: 'allow';
+    updatedInput: Record<string, unknown>;
+} | {
+    behavior: 'deny';
+    message: string;
+};
+/**
+ * Initialize agent configuration for the LLM gateway
+ */
+export declare function initializeAgent(config: AgentConfig, options: WizardOptions): Promise<AgentRunConfig>;
+/**
+ * Return the already-initialized agent config, or call initializeAgent to create it.
+ * Concurrent calls during initialization share the same Promise.
+ * On error the cached Promise is cleared so the next call retries.
+ *
+ * Omitting config/options reads the bearer token from ~/.ampli.json and uses production
+ * defaults (MCP disabled if no token found, cwd as working directory).
+ */
+export declare function getAgent(config?: AgentConfig, options?: WizardOptions): Promise<AgentRunConfig>;
+/**
+ * Run the agent by spawning the user's local `claude` CLI with --continue.
+ * Used when no Amplitude API key is present (local development).
+ * Streams stdout line-by-line and forwards text to the spinner.
+ */
+export declare function runAgentLocally(prompt: string, workingDirectory: string, spinner: SpinnerHandle, successMessage: string, errorMessage: string): Promise<{
+    error?: AgentErrorType;
+    message?: string;
+}>;
+/**
+ * Execute an agent with the provided prompt and options
+ * Handles the full lifecycle: spinner, execution, error handling
+ *
+ * @returns An object containing any error detected in the agent's output
+ */
+export declare function runAgent(agentConfig: AgentRunConfig, prompt: string, options: WizardOptions, spinner: SpinnerHandle, config?: {
+    estimatedDurationMinutes?: number;
+    spinnerMessage?: string;
+    successMessage?: string;
+    errorMessage?: string;
+    additionalFeatureQueue?: readonly AdditionalFeature[];
+}, middleware?: {
+    onMessage(message: SDKMessage): void;
+    finalize(resultMessage: SDKMessage, totalDurationMs: number): unknown;
+}): Promise<{
+    error?: AgentErrorType;
+    message?: string;
+}>;
+export {};