evalution 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,1440 @@
+import { Tracer } from "@opentelemetry/api";
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { CalleeBinding, ExtractedProps, PropDefinition, PropDefinition as PropDefinition$1, PropValue, PropValue as PropValue$1, SourceSpan } from "ts-proppy";
+import { GoogleGenAI } from "@google/genai";
+
+//#region src/shared/types.d.ts
+/**
+ * A reference to a prompt.
+ *
+ * `id` is interpreted as a globally-unique prompt ID unless `providerId` is
+ * present, in which case `id` is scoped to that specific prompt provider. This
+ * mirrors the OpenTelemetry attributes `evalution.prompt.id` (always present)
+ * and `evalution.prompt.provider.id` (optional, scoping).
+ */
+interface PromptID {
+  /** The prompt ID — global unless {@link providerId} scopes it. */
+  id: string;
+  /** When set, {@link id} is scoped to this prompt provider. */
+  providerId?: string;
+}
+/**
+ * Low-level prompt representation produced by a
+ * {@link PromptFileType}. It exposes the raw `extractedProps` from the parser
+ * and uses SDK-specific property names (e.g. `model`, `system`, `messages`).
+ *
+ * Not intended for public consumption — {@link PromptProvider} implementations
+ * convert this into a {@link NormalizedPrompt} via an {@link SDKAdapter} before
+ * returning it to callers.
+ */
+interface ParsedPrompt {
+  id: string;
+  providerId?: string;
+  /**
+   * Author-supplied stable alias for this prompt, globally unique across
+   * providers. Survives file moves/renames and is registered in the prompt
+   * registry so runtime traces can resolve back to this prompt.
+   */
+  globalId?: string;
+  name: string;
+  functionParameters: PropDefinition[];
+  extractedProps: ExtractedProps;
+  metadata?: unknown;
+  treePath?: string[];
+}
+/**
+ * A single message in a conversation, in a form that is independent of any
+ * particular SDK's message shape.
+ */
+interface NormalizedMessage {
+  /** Role identifier (`'system'`, `'user'`, `'assistant'`, `'tool'`, …). */
+  role: string;
+  /** Message content. Typically a primitive or template string, but any
+   * {@link PropValue} is allowed so non-string content (e.g. structured
+   * content arrays) can round-trip through the editor. */
+  content: PropValue;
+  /** Optional tool calls attached to an assistant message. */
+  toolCalls?: NormalizedToolCall[];
+}
+/** A tool invocation emitted by an assistant message. */
+interface NormalizedToolCall {
+  /** The name of the tool / function to invoke. */
+  toolName: string;
+  /** Arguments to the tool, as a JSON string. */
+  args: string;
+}
+/**
+ * A model parameter (`temperature`, `maxTokens`, …) attached to a prompt.
+ * Mirrors the `PropDefinition` + current value pair that the playground UI
+ * needs for rendering a parameter editor.
+ */
+interface NormalizedParameter {
+  /** Describes the parameter's name, type, and documentation. */
+  def: PropDefinition;
+  /** The parameter's current value, or `undefined` if not set on the prompt. */
+  value?: PropValue;
+  /** Whether the current value can be edited from the UI. */
+  editable: boolean;
+}
+/**
+ * Prompt representation used by {@link PromptProvider} public methods and by
+ * the playground UI. It hides SDK-specific property names behind a stable
+ * shape — `model`, `system`, `messages`, and the rest as `parameters`.
+ *
+ * {@link SDKAdapter.normalizePrompt} converts a {@link ParsedPrompt} produced
+ * by a {@link PromptFileType} into this form.
+ */
+interface NormalizedPrompt {
+  id: string;
+  providerId?: string;
+  /**
+   * Author-supplied stable alias for this prompt, globally unique across
+   * providers. Survives file moves/renames and is registered in the prompt
+   * registry so runtime traces can resolve back to this prompt.
+   */
+  globalId?: string;
+  name: string;
+  functionParameters: PropDefinition[];
+  metadata?: unknown;
+  /**
+   * Controls where this prompt appears in the sidebar tree.
+   *
+   * Each element is a path segment. The last segment is treated as the leaf
+   * group label (analogous to a file name) and all preceding segments are
+   * rendered as collapsible directory nodes.
+   *
+   * Prompts that share the same `treePath` are grouped under the same leaf
+   * node. When omitted, the prompt is placed at the root level.
+   *
+   * @example ['src', 'prompts', 'greeting.prompt.ts']
+   */
+  treePath?: string[];
+  /** The model reference (e.g. a provider call or gateway string). */
+  model?: PropValue;
+  /** Whether {@link model} can be edited in the UI. */
+  modelEditable: boolean;
+  /** Top-level system prompt, if the SDK supports one. */
+  system?: PropValue;
+  /** Whether {@link system} can be edited in the UI. */
+  systemEditable: boolean;
+  /** Conversation messages. */
+  messages: NormalizedMessage[];
+  /** Whether {@link messages} can be edited in the UI. */
+  messagesEditable: boolean;
+  /**
+   * Model parameters currently set on the prompt (everything other than
+   * `model`, `system`, and `messages`).
+   */
+  modelParameters: NormalizedParameter[];
+}
+/**
+ * Updates that can be applied to a {@link NormalizedPrompt} via
+ * {@link PromptProvider.updatePromptProperties}. A value of `null` removes
+ * that field from the underlying source.
+ */
+interface NormalizedPromptUpdates {
+  model?: ModelPropValue | null;
+  system?: PropValue | null;
+  messages?: NormalizedMessage[] | null;
+  /** Per-parameter updates, keyed by parameter name. `null` removes. */
+  modelParameters?: Record<string, PropValue | null>;
+}
+/** The kind of change that occurred to a prompt. */
+type ChangeEventType = "change" | "add" | "remove";
+/**
+ * Describes a single change emitted by {@link PromptProvider.watch}.
+ */
+interface PromptChangeEvent {
+  /** Whether the prompt was added, modified, or removed. */
+  type: ChangeEventType;
+  /** The ID of the affected prompt ({@link ParsedPrompt.id}) */
+  promptId: string;
+}
+/** Describes a single form field rendered by the Add Prompt dialog. */
+interface AddPromptField {
+  /** Key used to identify this field's value (e.g. `'name'`). */
+  name: string;
+  /** Human-readable label shown next to the input. */
+  label: string;
+  /** The kind of input control to render. */
+  type: "text" | "select";
+  /** Whether the field must be filled before submission. */
+  required?: boolean;
+  /** Pre-filled value. */
+  defaultValue?: string;
+  /** Placeholder text shown when the field is empty. */
+  placeholder?: string;
+  /** Available choices when `type` is `'select'`. */
+  options?: {
+    label: string;
+    value: string;
+  }[];
+}
+/**
+ * Returned by {@link PromptProvider.addPrompt} when additional user input is
+ * needed before the prompt can be created.
+ */
+interface AddPromptContext {
+  /** The form fields the provider needs the user to fill in. */
+  fields: AddPromptField[];
+}
+/** Information about a registered provider, returned by `GET /api/providers`. */
+interface PromptProviderInfo {
+  id: string;
+  displayName?: string;
+  description?: string;
+  icon?: string;
+  hasAddPrompt: boolean;
+}
+interface ExecuteRequest {
+  stream?: boolean;
+  functionParams?: any[];
+}
+/**
+ * Response body of `POST /api/prompts/:providerId/:id/execute`.
+ *
+ * The endpoint returns immediately after the trace has been registered; the
+ * real output is streamed as span events via
+ * `GET /api/traces/:tracerProviderId/:traceId/events`.
+ */
+interface ExecuteResponse {
+  /** ID of the trace that tracks this execution. */
+  traceId: string;
+  /** ID of the trace provider that owns the trace. */
+  tracerProviderId: string;
+  /** Span ID of the root span for this execution. */
+  rootSpanId: string;
+}
+/**
+ * Classification of a {@link Span}. See also:
+ * - `lmnr.span.type` from https://laminar.sh/docs/tracing/otel
+ * - `mlflow.spanType` from https://mlflow.org/docs/latest/genai/tracing/opentelemetry/attribute-mapping/#translated-span-attributes
+ *
+ * Mapped from `gen_ai.operation.name`.
+ */
+type SpanKind = "LLM" | "TOOL" | "AGENT" | "EMBEDDING" | "DEFAULT";
+/** A single message within an LLM span's input/output. */
+interface SpanMessage {
+  role: string;
+  content: string;
+}
+/** LLM-specific attributes attached to `LLM` spans. */
+interface LLMSpanDetails {
+  provider?: string;
+  model?: string;
+  messages?: SpanMessage[];
+  output?: string;
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  /** Dollar cost of the call, if known. */
+  cost?: number;
+  /** Model parameters (temperature, max_tokens, …). */
+  parameters?: Record<string, unknown>;
+}
+/**
+ * A span in a {@link Trace}. Spans form a tree via {@link parentId}.
+ * Durations are derived from `startTime` and `endTime`; an in-progress span has
+ * no `endTime` yet.
+ */
+interface Span {
+  id: string;
+  traceId: string;
+  /** `undefined` for the root span of the trace. */
+  parentId?: string;
+  name: string;
+  kind: SpanKind;
+  /** Start timestamp in milliseconds since epoch. */
+  startTime: number;
+  /** End timestamp in milliseconds since epoch, or `undefined` while running. */
+  endTime?: number;
+  status?: "ok" | "error";
+  /** Error message if `status` is `'error'`. */
+  errorMessage?: string;
+  /** Free-form attributes to show in the span's details pane. */
+  attributes?: Record<string, unknown>;
+  /** LLM-specific details (present for `chat`/`completion`/`embedding` spans). */
+  llm?: LLMSpanDetails;
+  /**
+   * The prompt this span is attributed to, if any.
+   *
+   * Stored as emitted (`evalution.prompt.id` plus optional
+   * `evalution.prompt.provider.id`): a {@link PromptID} whose `id` is global
+   * unless `providerId` is set. The server resolves it against the prompt
+   * registry to a provider-scoped reference when a trace is served.
+   */
+  prompt?: PromptID;
+}
+/**
+ * Top-level trace for a single invocation (e.g. one prompt execution).
+ */
+interface Trace {
+  id: string;
+  providerId?: string;
+  name: string;
+  /** Start timestamp (ms). */
+  startTime: number;
+  /** End timestamp (ms), or `undefined` while the trace is still running. */
+  endTime?: number;
+  status: "running" | "ok" | "error";
+  /** Free-form attributes (e.g. prompt ID, function params). */
+  attributes?: Record<string, unknown>;
+}
+/** Compact trace entry for listings (sidebar / `GET /api/traces`). */
+interface TraceSummary {
+  id: string;
+  providerId: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  status: "running" | "ok" | "error";
+  /** Number of spans currently associated with the trace. */
+  spanCount: number;
+}
+/** A trace together with all of its spans. */
+interface TraceWithSpans {
+  trace: Trace;
+  spans: Span[];
+}
+/** The kind of change that occurred to a trace. */
+type TraceChangeType = "add" | "update" | "remove";
+/** Describes a single change emitted by `TraceProvider.watch`. */
+interface TraceChangeEvent {
+  type: TraceChangeType;
+  traceId: string;
+}
+/** Real-time event pushed over the per-trace SSE subscription. */
+type TraceStreamEvent = {
+  type: "span-start";
+  span: Span;
+} | {
+  type: "span-end";
+  span: Span;
+} | {
+  type: "span-update";
+  span: Span;
+} | {
+  type: "trace-update";
+  trace: Trace;
+} | {
+  type: "trace-end";
+  trace: Trace;
+};
+/** Information about a registered trace provider, returned by `GET /api/trace-providers`. */
+interface TraceProviderInfo {
+  id: string;
+  displayName?: string;
+  description?: string;
+}
+/**
+ * Catalog-only variant of {@link PropValue} where `functionCall.binding` may
+ * carry multiple candidate bindings (e.g. a parameter-destructure form *and* a
+ * top-level-import form). The {@link PromptFileType} resolves these candidates
+ * against the target file's structure at edit time.
+ *
+ * Plain {@link PropValue} is assignable to `ModelPropValue` (single binding ⊆ array).
+ */
+type ModelPropValue = Exclude<PropValue, {
+  kind: "functionCall" | "object" | "array" | "tuple";
+}> | (Omit<Extract<PropValue, {
+  kind: "functionCall";
+}>, "binding" | "args"> & {
+  binding?: CalleeBinding | CalleeBinding[];
+  args: ModelPropValue[];
+}) | (Omit<Extract<PropValue, {
+  kind: "object";
+}>, "properties"> & {
+  properties: Record<string, ModelPropValue>;
+}) | (Omit<Extract<PropValue, {
+  kind: "array" | "tuple";
+}>, "elements"> & {
+  elements: ModelPropValue[];
+});
+/** A pre-defined model option shown in quick-select UIs. */
+interface ModelInfo {
+  /** Model ID (e.g. `'gpt-4o'`). */
+  id: string;
+  /** Human-readable label shown in the UI (e.g. `'GPT-4o (OpenAI)'`). */
+  label: string;
+  /** Optional category for grouping related models together in the UI (usually provider name). */
+  group?: string;
+  /**
+   * Values to use when selecting this model in different modes (as defined by {@link ModelCatalog.modelValueTypes}).
+   * If a value is undefined for a particular mode, this model is not offered as a quick-select option in that mode.
+   */
+  values: Record<string, ModelPropValue | undefined>;
+}
+/** Describes a model selection mode exposed by the SDK adapter (e.g. "Provider" or "Gateway"). */
+interface ModelValueType {
+  /** Label shown in the UI toggle (e.g. "Provider", "Gateway"). */
+  readonly label: string;
+  /** Optional tooltip / helper text. */
+  readonly description?: string;
+}
+/**
+ * Per-group metadata for constructing custom model values in the UI.
+ *
+ * `customValueTemplates` is a `PropValue` template per mode. Any primitive
+ * string value containing `$input` is replaced with the user's custom model
+ * ID at runtime.
+ */
+interface ModelGroupInfo {
+  customValueTemplates?: Record<string, ModelPropValue>;
+}
+/**
+ * Model catalog returned by {@link SDKAdapter.getModelCatalog}.
+ * Contains the set of known providers and a curated list of models.
+ */
+interface ModelCatalog {
+  /** List of known models. */
+  models: readonly ModelInfo[];
+  /**
+   * Available model selection modes.
+   *
+   * When this is an object, the UI renders a toggle so the user can switch between them.
+   * The keys of this object are used in {@link ModelInfo.values}, and the values provide
+   * metadata for how to render each mode in the UI.
+   */
+  modelValueTypes?: Record<string, ModelValueType>;
+  /** Per-group metadata for constructing custom model PropValues. Keyed by group name. */
+  groups?: Record<string, ModelGroupInfo>;
+}
+//#endregion
+//#region src/prompt/prompt-provider.d.ts
+/**
+ * A source of prompts that the playground can display and execute.
+ *
+ * Implement this interface to add a custom prompt source — for example,
+ * prompts stored in a database or fetched from a remote API. If you simply
+ * need to support a file format other than TypeScript, use {@link FilePromptProvider}
+ * with a custom {@link PromptFileType}.
+ */
+interface PromptProvider<TPrompt extends NormalizedPrompt = NormalizedPrompt> {
+  /** Uniquely identifies this provider when multiple providers are used. */
+  readonly id: string;
+  /** Human-readable name shown when choosing between providers. */
+  readonly displayName?: string;
+  /** Short description of what this provider offers. */
+  readonly description?: string;
+  /** SVG icon markup for this provider. */
+  readonly icon?: string;
+  /** Returns all prompts currently available from this provider. */
+  getAllPrompts(): Promise<TPrompt[]>;
+  /**
+   * Returns the prompt with the given ID, or `null` if not found.
+   * @param id - The prompt's unique identifier.
+   */
+  getPrompt(id: string): Promise<TPrompt | null>;
+  /**
+   * Applies normalized updates to a prompt's source and returns the fresh
+   * prompt. Setting any field of `updates` to `null` removes the corresponding
+   * property from the underlying source.
+   *
+   * This method is optional; providers that do not support in-place editing
+   * may omit it.
+   *
+   * @param promptId - ID of the prompt to update.
+   * @param updates - Updates expressed in the normalized vocabulary.
+   */
+  updatePromptProperties?(promptId: string, updates: NormalizedPromptUpdates): Promise<TPrompt>;
+  /**
+   * Executes a prompt and returns either a result object (when `stream` is
+   * `false`) or an async text iterable (when `stream` is `true`).
+   *
+   * @param promptId - ID of the prompt to run.
+   * @param params - Positional arguments forwarded to the prompt function.
+   * @param stream - When `true`, the return value is an async text iterator.
+   */
+  execute(promptId: string, params: any[], stream: boolean): Promise<any>;
+  /**
+   * Returns the model catalog (known providers and popular models) for this
+   * provider's underlying SDK.
+   *
+   * Optional — providers that do not expose model info may omit it.
+   */
+  getModelCatalog?(): Promise<ModelCatalog>;
+  /**
+   * Returns the list of editable model parameters exposed by this provider's
+   * underlying SDK (e.g. `temperature`, `maxTokens`).
+   *
+   * Optional — providers that do not expose model parameters may omit it.
+   */
+  getModelParameters?(): PropDefinition[];
+  /**
+   * Registers a callback that is invoked whenever a prompt changes.
+   * Returns a cleanup function that stops the watcher when called.
+   *
+   * Optional — providers that cannot detect live changes may omit it.
+   *
+   * @param callback - Invoked with a {@link PromptChangeEvent} for each change.
+   * @returns A no-argument function that unregisters the watcher.
+   */
+  watch?(callback: (event: PromptChangeEvent) => void): () => void;
+  /**
+   * Creates a new prompt from the given partial, or returns an
+   * {@link AddPromptContext} describing what additional inputs are needed.
+   *
+   * When `partial` contains enough information the provider creates the
+   * prompt and returns the full {@link NormalizedPrompt}. Otherwise it returns
+   * an {@link AddPromptContext} whose `fields` describe the form the UI
+   * should present to the user.
+   *
+   * Optional — providers that do not support creating prompts may omit it.
+   *
+   * @param partial - Partially filled prompt data.
+   */
+  addPrompt?(partial: Partial<TPrompt>): Promise<TPrompt | AddPromptContext>;
+  /**
+   * Renames a prompt and returns the updated prompt with its new ID.
+   *
+   * Optional — providers that do not support renaming may omit it.
+   *
+   * @param promptId - ID of the prompt to rename.
+   * @param newName - The new name for the prompt.
+   */
+  renamePrompt?(promptId: string, newName: string): Promise<TPrompt>;
+}
+//#endregion
+//#region src/trace/prompt-tracer.d.ts
+/**
+ * Attribute name a span can set to pick one of evalution's span-kind values
+ * (`'LLM'`, `'TOOL'`, `'AGENT'`, `'EMBEDDING'`, `'DEFAULT'`). Falls back to
+ * `'DEFAULT'` when absent or unrecognised.
+ */
+declare const SPAN_KIND_ATTRIBUTE = "evalution.span.type";
+/**
+ * Attribute name a span can set to scope its {@link PROMPT_ID_ATTRIBUTE} to a
+ * specific prompt provider. When absent, the prompt ID is treated as global.
+ */
+declare const PROMPT_PROVIDER_ID_ATTRIBUTE = "evalution.prompt.provider.id";
+/**
+ * Attribute name a span can set to link itself to a specific prompt. The value
+ * is a globally-unique prompt ID unless {@link PROMPT_PROVIDER_ID_ATTRIBUTE} is
+ * also set, in which case it is scoped to that provider.
+ */
+declare const PROMPT_ID_ATTRIBUTE = "evalution.prompt.id";
+/**
+ * Attribute name a span can set to give a human-readable name to the prompt.
+ */
+declare const PROMPT_NAME_ATTRIBUTE = "gen_ai.prompt.name";
+/**
+ * Wraps a {@link Tracer} so that every span it produces is tagged with the
+ * attributes that associate it with a prompt — the prompt's name
+ * ({@link PROMPT_NAME_ATTRIBUTE}), an optional global prompt ID
+ * ({@link PROMPT_ID_ATTRIBUTE}), and an `'LLM'` span kind
+ * ({@link SPAN_KIND_ATTRIBUTE}). Attributes set explicitly on an individual
+ * span take precedence over these defaults.
+ *
+ * This depends only on `@opentelemetry/api`, so it can be re-used by SDK
+ * adapter packages (e.g. `@evalution/vercel-ai-sdk`) without pulling in the
+ * rest of evalution.
+ *
+ * @param prompt - The prompt to attribute spans to. `name` is a human-readable
+ *   name; the optional `id` is a globally-unique prompt ID used to resolve
+ *   runtime traces back to the prompt.
+ * @param tracer - Tracer to wrap. Defaults to a tracer from the globally
+ *   registered tracer provider.
+ * @returns A tracer that forwards to `tracer` while attaching the prompt
+ *   attributes to each span it creates.
+ */
+declare function createTracerForPrompt(prompt: {
+  name: string;
+  id?: string;
+}, tracer?: Tracer): Tracer;
+//#endregion
+//#region src/trace/trace-provider.d.ts
+/**
+ * A read-only store of execution traces that the playground can display and
+ * subscribe to in real time. Implement this interface to integrate a tracing
+ * backend.
+ *
+ * Traces and spans are created via the OpenTelemetry API
+ * (`@opentelemetry/api`). A `TraceProvider` implementation's job is to expose
+ * the traces a backend knows about; populating the store from OTel spans is
+ * an implementation detail (e.g. by registering a
+ * `@opentelemetry/sdk-trace-base` `SpanProcessor`).
+ */
+interface TraceProvider {
+  /** Uniquely identifies this provider when multiple providers are used. */
+  readonly id: string;
+  /** Human-readable name shown when choosing between providers. */
+  readonly displayName?: string;
+  /** Short description of what this provider offers. */
+  readonly description?: string;
+  /**
+   * Returns compact summaries for every trace known to this provider, newest
+   * first. Used to populate the Traces sidebar.
+   */
+  getAllTraces(): Promise<TraceSummary[]>;
+  /**
+   * Returns the trace with the given ID together with all of its spans, or
+   * `undefined` when the trace is unknown.
+   */
+  getTrace(traceId: string): Promise<TraceWithSpans | undefined>;
+  /**
+   * Subscribes to real-time updates for a specific trace. The callback is
+   * invoked for every {@link Span} change on this trace, for as long as the
+   * returned cleanup function has not been called.
+   *
+   * @returns A no-argument function that cancels the subscription.
+   */
+  subscribeTrace(traceId: string, callback: (event: TraceStreamEvent) => void): () => void;
+  /**
+   * Registers a callback invoked whenever a trace is added, updated, or
+   * removed. Used by the sidebar to stay in sync without polling.
+   *
+   * Optional — providers that cannot detect live changes may omit it.
+   *
+   * @returns A no-argument function that unregisters the watcher.
+   */
+  watch?(callback: (event: TraceChangeEvent) => void): () => void;
+  /**
+   * Returns a `SpanProcessor` (from `@opentelemetry/sdk-trace-base`) that
+   * feeds OpenTelemetry spans into this provider's store. The playground
+   * registers it on a shared `BasicTracerProvider` so spans produced by the
+   * server's tracer land here.
+   *
+   * Optional — providers backed by an external backend (LangSmith, a
+   * collector, …) typically receive spans out-of-band and can omit this.
+   */
+  getSpanProcessor?(): SpanProcessor;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Top-level configuration for an Evalution instance.
+ *
+ * Place a default export of this type in `.evalution/config.ts` at the root
+ * of your project to customise how Evalution discovers and serves prompts
+ * and traces.
+ *
+ * If no config file is found, Evalution will show an onboarding wizard
+ * to help you create one.
+ *
+ * @example
+ * ```ts
+ * // .evalution/config.ts
+ * import type { EvalutionConfig } from 'evalution';
+ * import { FilePromptProvider, VercelAISDK } from 'evalution';
+ *
+ * export default {
+ *   promptProviders: [
+ *     new FilePromptProvider({
+ *       sdk: new VercelAISDK(),
+ *     }),
+ *   ],
+ * } satisfies EvalutionConfig;
+ * ```
+ */
+interface EvalutionConfig {
+  /**
+   * Whether to load a `.env` file from the directory Evalution is launched
+   * from before starting the server.
+   *
+   * @default true
+   */
+  useDotenv?: boolean;
+  /**
+   * One or more providers that supply prompts to the playground.
+   *
+   * If omitted, a {@link FilePromptProvider} rooted at the current working
+   * directory is used automatically.
+   */
+  promptProviders?: PromptProvider[];
+  /**
+   * One or more providers that supply execution traces to the playground.
+   *
+   * If omitted, a {@link MemoryTraceProvider} is used automatically so the
+   * Traces tab can still be exercised without wiring a real tracing backend.
+   */
+  traceProviders?: TraceProvider[];
+}
+//#endregion
+//#region src/file-provider.d.ts
+/** Options accepted by {@link FileProvider.glob}. */
+interface GlobOptions {
+  /** The directory to search from. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Glob patterns whose matches are excluded from results. */
+  ignore?: readonly string[];
+  /** When `true`, yielded paths are absolute; otherwise they are relative to `cwd`. */
+  absolute?: boolean;
+}
+/** Options accepted by {@link FileProvider.watch}. */
+interface FileWatchOptions {
+  /** The directory from which relative file paths are resolved. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Glob patterns whose matches are excluded from the watcher. */
+  ignored?: readonly string[];
+  /**
+   * When `true`, the watcher does not emit events for files that already exist
+   * at startup. Defaults to `true`.
+   */
+  ignoreInitial?: boolean;
+}
+/**
+ * Callback invoked by {@link FileProvider.watch} when a watched file changes.
+ * @param eventType - The kind of change: `'add'`, `'change'`, or `'remove'`.
+ * @param filePath - The affected file path, relative to the watcher's `cwd`.
+ */
+type FileWatchCallback = (eventType: ChangeEventType, filePath: string) => void;
+/**
+ * Abstraction over file system I/O used throughout Evalution.
+ *
+ * Swap in a different implementation to adapt Evalution to non-local
+ * environments or to make tests fully in-memory (see {@link MemoryFileProvider}).
+ * {@link LocalFileProvider} is the default implementation for production use.
+ */
+interface FileProvider {
+  /**
+   * Reads the file at `filePath` and returns its content as a UTF-8 string.
+   * Rejects if the file does not exist.
+   */
+  readFile(filePath: string): Promise<string>;
+  /**
+   * Writes `content` to `filePath`, creating or overwriting the file.
+   * When the path falls inside an active {@link watch} scope, the watcher
+   * callback is invoked automatically.
+   */
+  writeFile(filePath: string, content: string): Promise<void>;
+  /**
+   * Deletes the file at `filePath`.
+   * When the path falls inside an active {@link watch} scope, the watcher
+   * callback is invoked automatically with `'remove'`.
+   */
+  deleteFile(filePath: string): Promise<void>;
+  /**
+   * Dynamically imports the module at `filePath` and returns its namespace
+   * object. Rejects if the file does not exist.
+   */
+  import(filePath: string): Promise<any>;
+  /**
+   * Returns an async iterator that yields paths matching `pattern`.
+   * @param pattern - A glob pattern (e.g. `'**\/*.prompt.ts'`).
+   * @param options - See {@link GlobOptions}.
+   */
+  glob(pattern: string, options?: GlobOptions): AsyncIterableIterator<string>;
+  /**
+   * Starts watching for changes to files that match `patterns` and calls
+   * `callback` on each relevant event.
+   *
+   * @param patterns - Glob patterns that select which files to watch.
+   * @param options - See {@link FileWatchOptions}.
+   * @param callback - Called for each matching file event.
+   * @returns A cleanup function; call it to stop watching.
+   */
+  watch(patterns: readonly string[], options: FileWatchOptions, callback: FileWatchCallback): () => void;
+}
+/**
+ * An in-memory {@link FileProvider} backed by a `Map<string, string>`.
+ *
+ * Intended for unit tests — all file I/O stays in-process with no disk access.
+ * Calling {@link writeFile} triggers any active {@link watch} callbacks
+ * synchronously, making it easy to test reactive code paths.
+ *
+ * @example
+ * ```ts
+ * const provider = new MemoryFileProvider({
+ *   '/virtual/prompt.ts': 'export function myPrompt() { ... }',
+ * });
+ * const content = await provider.readFile('/virtual/prompt.ts');
+ * ```
+ */
+declare class MemoryFileProvider implements FileProvider {
+  private files;
+  private watchers;
+  /**
+   * @param files - Initial file contents keyed by absolute path.
+   */
+  constructor(files?: Record<string, string>);
+  readFile(filePath: string): Promise<string>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  deleteFile(filePath: string): Promise<void>;
+  import(filePath: string): Promise<any>;
+  glob(pattern: string, options?: GlobOptions): AsyncIterableIterator<string>;
+  watch(patterns: readonly string[], options: FileWatchOptions, callback: FileWatchCallback): () => void;
+  private notifyWatchers;
+}
+/**
+ * A {@link FileProvider} backed by the local file system.
+ *
+ * Uses `fs/promises` for I/O, `fs/promises.glob` (Node.js ≥ 22) for pattern
+ * matching, and [chokidar](https://github.com/paulmillr/chokidar) for file
+ * watching.
+ *
+ * This is the default implementation used by {@link FilePromptProvider} and
+ * {@link TSPromptFileType} when no custom provider is supplied.
+ */
+declare class LocalFileProvider implements FileProvider {
+  readFile(filePath: string): Promise<string>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  deleteFile(filePath: string): Promise<void>;
+  import(filePath: string): Promise<any>;
+  glob(pattern: string, options?: GlobOptions): AsyncIterableIterator<string>;
+  watch(patterns: readonly string[], options: FileWatchOptions, callback: FileWatchCallback): () => void;
+}
+//#endregion
+//#region src/sdk/sdk-adapter.d.ts
+/**
+ * Adapter that provides values and execution for a particular AI SDK.
+ *
+ * Pass an instance of this to {@link FilePromptProvider} via the
+ * `sdk` option.
+ */
+interface SDKAdapter {
+  /**
+   * The package that exports the `prompts()` helper used in new prompt files
+   * (e.g. `'@evalution/vercel-ai-sdk'`). Used by {@link PromptFileType.newPromptSkeleton}.
+   */
+  promptsHelperImport: string;
+  /**
+   * Returns model catalog information: the set of known providers and a
+   * curated list of popular models for this SDK.
+   */
+  getModelCatalog(): Promise<ModelCatalog>;
+  /**
+   * Returns the list of model parameters that can be edited in the playground
+   * UI for projects rooted at `rootDir`. Typically extracted from the SDK's
+   * published TypeScript type definitions.
+   *
+   * @param rootDir - Absolute path to the project root.
+   */
+  getModelParameters(rootDir: string): PropDefinition$1[];
+  /**
+   * Executes a prompt config object and returns either a result object (when
+   * `stream` is `false`) or an async text iterable (when `stream` is `true`).
+   *
+   * @param config - The config object returned by the prompt function.
+   * @param stream - When `true`, returns a streaming text iterator.
+   */
+  executeConfig(config: any, stream: boolean): Promise<any>;
+  /**
+   * Convert a low-level {@link ParsedPrompt} produced by a
+   * {@link PromptFileType} into a {@link NormalizedPrompt} that the UI can
+   * consume without knowing the SDK's specific property names or message shape.
+   *
+   * @param prompt - The raw parsed prompt.
+   */
+  normalizePrompt(prompt: ParsedPrompt): NormalizedPrompt;
+  /**
+   * Convert {@link NormalizedPromptUpdates} (what the UI sends back) into the
+   * raw property-name-keyed updates that {@link PromptFileType.updateProperty}
+   * and friends operate on.
+   *
+   * @param updates - Updates expressed in the normalized vocabulary.
+   * @returns A `Record` keyed by the SDK's actual property names. Values may
+   *   be `null` (to remove) or a `PropValue`.
+   */
+  denormalizeUpdates(updates: NormalizedPromptUpdates, currentValues?: Record<string, PropValue$1>): Record<string, ModelPropValue | null>;
+}
+//#endregion
+//#region src/prompt/file/prompt-file-type.d.ts
+/** Metadata attached to prompts that originate from a file on disk. */
+interface FilePromptMetadata {
+  /** Path to the source file relative to the {@link FilePromptProviderOptions.rootDir}. */
+  relativeFilePath: string;
+}
+/**
+ * A {@link ParsedPrompt} produced by the file-based parser, with
+ * {@link FilePromptMetadata} guaranteed to be present on `metadata`.
+ *
+ * This is the low-level form emitted by {@link PromptFileType.parsePrompts};
+ * {@link FilePromptProvider} converts it to a {@link NormalizedFilePrompt}
+ * before exposing it publicly.
+ */
+interface ParsedFilePrompt extends ParsedPrompt {
+  metadata: FilePromptMetadata;
+}
+/**
+ * A {@link NormalizedPrompt} whose `metadata` field is guaranteed to carry
+ * {@link FilePromptMetadata}. This is the public-facing prompt type returned
+ * by {@link FilePromptProvider}.
+ */
+interface NormalizedFilePrompt extends NormalizedPrompt {
+  metadata: FilePromptMetadata;
+}
+/**
+ * Strategy object that knows how to parse, edit, and execute a specific
+ * prompt file format.
+ *
+ * The default implementation is {@link TSPromptFileType}, which handles
+ * TypeScript `.prompt.ts` files. Provide a custom implementation to support
+ * other file formats, then pass it to {@link FilePromptProvider} via its
+ * `fileType` option.
+ */
+interface PromptFileType {
+  /**
+   * Glob patterns used by {@link FilePromptProvider} when no explicit
+   * `includePatterns` option is provided.
+   */
+  defaultIncludePatterns: readonly string[];
+  /**
+   * File extension appended to a new prompt's filename when the user does not
+   * supply one (e.g. `'.prompt.ts'`). Includes the leading dot.
+   */
+  defaultFileExtension: string;
+  /**
+   * Generates the starter source code for a new prompt file.
+   * @param promptsId - The module ID passed to the `prompts()` helper (typically derived from the file name).
+   * @param name - The initial prompt function name.
+   * @param importPath - The package path to import the `prompts()` helper from.
+   */
+  newPromptSkeleton(promptsId: string, name: string, importPath: string): string;
+  /**
+   * Parses the given files and returns all discovered prompts.
+   * Reads fresh file content at the time of the call.
+   * @param files - Absolute paths of the files to parse.
+   * @param rootDir - The project root; used to compute relative prompt IDs.
+   */
+  parsePrompts(files: string[], rootDir: string): Promise<ParsedFilePrompt[]>;
+  /**
+   * Updates the value of an existing property in a prompt source file.
+   * @param filePath - Absolute path to the file to edit.
+   * @param propDef - The property definition to update (must carry source-position metadata).
+   * @param value - The new value to write.
+   * @param promptId - The prompt ID, used to re-parse for fresh spans.
+   */
+  updateProperty(filePath: string, propDef: PropDefinition$1, value: ModelPropValue, promptId?: string): Promise<void>;
+  /**
+   * Removes a property from a prompt source file entirely.
+   * @param filePath - Absolute path to the file to edit.
+   * @param propDef - The property definition to remove.
+   */
+  removeProperty(filePath: string, propDef: PropDefinition$1): Promise<void>;
+  /**
+   * Adds a new property to a prompt in a source file.
+   * @param filePath - Absolute path to the file to edit.
+   * @param promptName - Name of the exported function to add the property to.
+   * @param propertyName - The key to add.
+   * @param value - The value to assign.
+   */
+  addProperty(filePath: string, promptName: string, propertyName: string, value: ModelPropValue): Promise<void>;
+  /**
+   * Renames an exported prompt in a source file.
+   * @param filePath - Absolute path to the file to edit.
+   * @param oldName - Current prompt name.
+   * @param newName - New prompt name.
+   */
+  renamePrompt(filePath: string, oldName: string, newName: string): Promise<void>;
+  /**
+   * Dynamically imports `filePath`, calls the exported function named
+   * `promptName` with `params`, and returns the resulting config object.
+   *
+   * @param filePath - Absolute path to the prompt file.
+   * @param promptName - Name of the exported function to invoke.
+   * @param params - Positional arguments forwarded to the function.
+   */
+  loadConfig(filePath: string, promptName: string, params: any[]): Promise<any>;
+}
+//#endregion
+//#region src/prompt/file/file-prompt-provider.d.ts
+/**
+ * Configuration options for the {@link FilePromptProvider}.
+ */
+interface FilePromptProviderOptions {
+  /**
+   * Uniquely identifies this provider instance when multiple providers are used together. Defaults to 'fs' + an incrementing number.
+   */
+  id?: string;
+  /**
+   * The root directory to scan recursively for prompt files. Defaults to the current working directory.
+   */
+  rootDir?: string;
+  /**
+   * Glob patterns to include when scanning for prompt files. Defaults to {@link PromptFileType.defaultIncludePatterns}.
+   */
+  includePatterns?: readonly string[];
+  /**
+   * Glob patterns to exclude when scanning for prompt files. Defaults to ['\*\*\/node_modules/\*\*', '\*\*\/dist/\*\*', '\*\*\/.git/**'].
+   */
+  ignorePatterns?: readonly string[];
+  /**
+   * Optional custom file provider that abstracts file system access, useful for testing or non-local environments. Defaults to an instance of {@link LocalFileProvider}.
+   */
+  fileProvider?: FileProvider;
+  /**
+   * Optional custom file type handler that defines how to parse prompt files and manipulate properties. Defaults to an instance of {@link TSPromptFileType}.
+   */
+  fileType?: PromptFileType;
+  /**
+   * SDK adapter that governs prompt structure and execution.
+   */
+  sdk: SDKAdapter;
+}
+/**
+ * A {@link PromptProvider} that discovers and serves prompts from
+ * files on the local file system (or any {@link FileProvider}).
+ *
+ * Out of the box it scans for `**\/*.prompt.ts` files and parses them with
+ * {@link TSPromptFileType}. Pass a {@link FilePromptProviderOptions} to the
+ * constructor to customize this behavior. You must specify at least
+ * {@link FilePromptProviderOptions.sdk}.
+ *
+ * @example
+ * ```ts
+ * const provider = new FilePromptProvider({ rootDir: '/my/project', sdk: new VercelAISDK() });
+ * const prompts = await provider.getAllPrompts();
+ * ```
+ */
+declare class FilePromptProvider implements PromptProvider<NormalizedFilePrompt> {
+  readonly id: string;
+  readonly displayName = "File System";
+  readonly description = "Create a .prompt.ts file";
+  readonly icon = "<svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"currentColor\"><path d=\"M1.5 3A1.5 1.5 0 000 4.5v8A1.5 1.5 0 001.5 14h13a1.5 1.5 0 001.5-1.5v-7A1.5 1.5 0 0014.5 4H8L6.5 2.5h-5z\"/></svg>";
+  private files;
+  private rootDir;
+  private fileType;
+  private fileProvider;
+  private includePatterns;
+  private ignorePatterns;
+  private sdkAdapter;
+  private suppressedWatchEvents;
+  constructor({
+    id,
+    rootDir,
+    fileProvider,
+    fileType,
+    includePatterns,
+    ignorePatterns,
+    sdk
+  }: FilePromptProviderOptions);
+  getAllPrompts(): Promise<NormalizedFilePrompt[]>;
+  getPrompt(id: string): Promise<NormalizedFilePrompt | null>;
+  updatePromptProperties(promptId: string, updates: NormalizedPromptUpdates): Promise<NormalizedFilePrompt>;
+  private getParsedPrompt;
+  private normalizeFilePrompt;
+  getModelCatalog(): Promise<ModelCatalog>;
+  getModelParameters(): PropDefinition[];
+  execute(promptId: string, params: any[], stream: boolean): Promise<any>;
+  renamePrompt(promptId: string, newName: string): Promise<NormalizedFilePrompt>;
+  addPrompt(partial: Partial<NormalizedFilePrompt>): Promise<NormalizedFilePrompt | AddPromptContext>;
+  watch(callback: (event: PromptChangeEvent) => void): () => void;
+  private ensureFiles;
+  private suppressNextWatchEvent;
+  private consumeSuppressedWatchEvent;
+  private findPromptFiles;
+  private parsePromptId;
+  private listDirectories;
+  private resolveFilePath;
+}
+//#endregion
+//#region src/prompt/file/ts/ts-prompt-file-type.d.ts
+declare class TSPromptFileType implements PromptFileType {
+  defaultIncludePatterns: string[];
+  defaultFileExtension: string;
+  newPromptSkeleton(promptsId: string, name: string, importPath: string): string;
+  private fileProvider;
+  constructor(fileProvider?: FileProvider);
+  parsePrompts(files: string[], rootDir?: string): Promise<ParsedFilePrompt[]>;
+  updateProperty(filePath: string, propDef: PropDefinition$1, value: ModelPropValue, promptId?: string): Promise<void>;
+  removeProperty(filePath: string, propDef: PropDefinition$1): Promise<void>;
+  addProperty(filePath: string, promptName: string, propertyName: string, value: ModelPropValue): Promise<void>;
+  renamePrompt(filePath: string, oldName: string, newName: string): Promise<void>;
+  loadConfig(filePath: string, promptName: string, params: any[]): Promise<any>;
+  private parseFileContent;
+  private parseHelperProperty;
+  private parseFunctionDeclaration;
+  private findFreshDefinition;
+  private findReturnObjectInFunction;
+  private findReturnObjectInSource;
+}
+//#endregion
+//#region src/sdk/gemini-interactions-sdk.d.ts
+type BaseCreateInteractionParams = Parameters<typeof GoogleGenAI.prototype.interactions.create>[0];
+/**
+ * {@link SDKAdapter} implementation for the Google GenAI
+ * [Interactions API](https://ai.google.dev/gemini-api/docs/interactions)
+ * (`@google/genai` package). Currently experimental and untested.
+ */
+declare class GeminiInteractionsSDK implements SDKAdapter {
+  readonly promptsHelperImport = "FIXME";
+  getModelCatalog(): Promise<{
+    readonly modelValueTypes: {
+      readonly model: {
+        readonly label: "Models";
+        readonly description: "Models";
+      };
+      readonly agent: {
+        readonly label: "Agents";
+        readonly description: "Agents";
+      };
+    };
+    readonly groups: {
+      readonly Google: {
+        readonly customValueTemplates: {
+          readonly model: {
+            readonly kind: "object";
+            readonly properties: {
+              readonly key: {
+                readonly kind: "primitive";
+                readonly value: "model";
+              };
+              readonly value: {
+                readonly kind: "primitive";
+                readonly value: "$input";
+              };
+            };
+          };
+          readonly agent: {
+            readonly kind: "object";
+            readonly properties: {
+              readonly key: {
+                readonly kind: "primitive";
+                readonly value: "agent";
+              };
+              readonly value: {
+                readonly kind: "primitive";
+                readonly value: "$input";
+              };
+            };
+          };
+        };
+      };
+    };
+    readonly models: readonly [{
+      readonly id: "gemini-3.1-pro-preview";
+      readonly label: "Gemini 3.1 Pro Preview";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-3.1-pro-preview";
+            };
+          };
+          readonly displayValue: "gemini-3.1-pro-preview";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "gemini-3-flash-preview";
+      readonly label: "Gemini 3 Flash Preview";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-3-flash-preview";
+            };
+          };
+          readonly displayValue: "gemini-3-flash-preview";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "gemini-3.1-flash-lite-preview";
+      readonly label: "Gemini 3.1 Flash-Lite Preview";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-3.1-flash-lite-preview";
+            };
+          };
+          readonly displayValue: "gemini-3.1-flash-lite-preview";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "gemini-2.5-pro";
+      readonly label: "Gemini 2.5 Pro";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-2.5-pro";
+            };
+          };
+          readonly displayValue: "gemini-2.5-pro";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "gemini-2.5-flash";
+      readonly label: "Gemini 2.5 Flash";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-2.5-flash";
+            };
+          };
+          readonly displayValue: "gemini-2.5-flash";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "gemini-2.5-flash-lite";
+      readonly label: "Gemini 2.5 Flash-lite";
+      readonly values: {
+        readonly model: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "model";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "gemini-2.5-flash-lite";
+            };
+          };
+          readonly displayValue: "gemini-2.5-flash-lite";
+        };
+      };
+      readonly group: "Google";
+    }, {
+      readonly id: "deep-research-pro-preview-12-2025";
+      readonly label: "Deep Research Preview";
+      readonly values: {
+        readonly agent: {
+          readonly kind: "object";
+          readonly properties: {
+            readonly key: {
+              readonly kind: "primitive";
+              readonly value: "agent";
+            };
+            readonly value: {
+              readonly kind: "primitive";
+              readonly value: "deep-research-pro-preview-12-2025";
+            };
+          };
+          readonly displayValue: "deep-research-pro-preview-12-2025";
+        };
+      };
+      readonly group: "Google";
+    }];
+  }>;
+  getModelParameters(rootDir: string): PropDefinition$1[];
+  executeConfig(config: BaseCreateInteractionParams, stream: boolean): Promise<any>;
+  normalizePrompt(prompt: ParsedPrompt): NormalizedPrompt;
+  denormalizeUpdates(updates: NormalizedPromptUpdates, currentValues?: Record<string, PropValue$1>): Record<string, ModelPropValue | null>;
+}
+//#endregion
+//#region src/shared/setup-task.d.ts
+/** Fields shared by every {@link SetupStep} kind. */
+interface SetupStepBase {
+  /** Stable identifier, unique within the owning {@link SetupTask}. */
+  id: string;
+  /**
+   * Runtime completion status, populated by the server when listing tasks
+   * (e.g. the config file already exists, or the package is installed). Absent
+   * in the static step definitions held by the registry.
+   */
+  completed?: boolean;
+}
+/** Writes evalution's starter config file. */
+interface SetupCreateConfigStep extends SetupStepBase {
+  /** Discriminant: this step creates the project config file. */
+  kind: "create_config";
+  /** Project-relative path the file will be written to. */
+  path: string;
+  /**
+   * Full contents of the file. Shown to the user as a copyable snippet and
+   * written verbatim by the server. This is display data: the server reads it
+   * from its own registry, never from a client request.
+   */
+  contents: string;
+}
+/**
+ * Runs a shell command in the project root, streamed to an interactive
+ * terminal so the user can watch it and respond to prompts.
+ */
+interface SetupRunCommandStep extends SetupStepBase {
+  /** Discriminant: this step runs a shell command. */
+  kind: "run_command";
+  /** The command line to run, e.g. `npm run build`. */
+  command: string;
+  /** Optional human-friendly label shown alongside the command. */
+  label?: string;
+}
+/**
+ * Installs an npm package — a specialization of {@link SetupRunCommandStep}
+ * that runs `npm i <package>`. The server reports it as already
+ * {@link SetupStepBase.completed | completed} when the package is present in
+ * the project, so the user can skip it.
+ */
+interface SetupInstallPackageStep extends SetupStepBase {
+  /** Discriminant: this step installs an npm package. */
+  kind: "install_package";
+  /** The npm package to install, e.g. `@evalution/vercel-ai-sdk`. */
+  package: string;
+}
+/**
+ * A single executable step within a {@link SetupTask}.
+ *
+ * Steps are defined server-side and addressed by {@link SetupTask.id} plus the
+ * step's `id`; the client references a step only by those ids when asking the
+ * server to run it.
+ */
+type SetupStep = SetupCreateConfigStep | SetupRunCommandStep | SetupInstallPackageStep;
+/**
+ * The shell command a run-style step executes. `install_package` steps map to
+ * `npm i <package>`; `run_command` steps carry their command verbatim.
+ */
+declare function setupStepCommand(step: SetupRunCommandStep | SetupInstallPackageStep): string;
+/**
+ * A named onboarding task for a single AI SDK: what to show in the manual-setup
+ * picker, plus the ordered steps that wire the SDK up.
+ */
+interface SetupTask {
+  /** Stable identifier, also used as the wire id for this SDK choice. */
+  id: string;
+  /** Display label for the picker (typically the SDK's product name). */
+  label: string;
+  /** Icon identifier, mapped to a bundled asset on the client. */
+  icon: string;
+  /** Ordered steps to run, in display order. */
+  steps: SetupStep[];
+}
+//#endregion
+//#region src/sdk/vercel-ai-sdk.d.ts
+/**
+ * {@link SDKAdapter} implementation for the
+ * [Vercel AI SDK](https://sdk.vercel.ai/).
+ *
+ * - `getModelParameters` reads `CallSettings` from the SDK's `.d.ts` bundle
+ *   and surfaces parameters with simple types that can be edited in the UI.
+ * - `executeConfig` delegates to `generateText`.
+ */
+declare class VercelAISDK implements SDKAdapter {
+  readonly promptsHelperImport: "@evalution/vercel-ai-sdk";
+  /** Onboarding task: install the SDK package, then drop a starter config. */
+  static readonly setupTask: SetupTask;
+  getModelCatalog(): Promise<{
+    modelValueTypes: {
+      function: {
+        label: string;
+        description: string;
+      };
+      string: {
+        label: string;
+        description: string;
+      };
+    };
+    groups: {
+      OpenAI: {
+        customValueTemplates: {
+          function: ModelPropValue;
+        };
+      };
+      Anthropic: {
+        customValueTemplates: {
+          function: ModelPropValue;
+        };
+      };
+      Google: {
+        customValueTemplates: {
+          function: ModelPropValue;
+        };
+      };
+    };
+    models: ModelInfo[];
+  }>;
+  getModelParameters(rootDir: string): PropDefinition$1[];
+  executeConfig(config: any, stream: boolean): Promise<any>;
+  normalizePrompt(prompt: ParsedPrompt): NormalizedPrompt;
+  denormalizeUpdates(updates: NormalizedPromptUpdates, _currentValues?: Record<string, PropValue$1>): Record<string, ModelPropValue | null>;
+}
+//#endregion
+//#region src/trace/base-otel-trace-provider.d.ts
+/**
+ * Base class for a {@link TraceProvider} populated by OpenTelemetry spans.
+ *
+ * Register the processor returned by {@link getSpanProcessor} on a
+ * `BasicTracerProvider` (from `@opentelemetry/sdk-trace-base`).
+ */
+declare abstract class BaseOTelTraceProvider implements TraceProvider {
+  readonly id: string;
+  readonly displayName?: string;
+  readonly description?: string;
+  private subscribers;
+  private watchers;
+  private spanPromises;
+  constructor(options: {
+    id: string;
+    displayName: string;
+    description: string;
+  });
+  abstract getAllTraces(): Promise<TraceSummary[]>;
+  abstract hasTrace(traceId: string): Promise<boolean>;
+  protected abstract getTraceWithoutSpans(traceId: string): Promise<Trace | undefined>;
+  protected abstract getTraceSpans(traceId: string): Promise<Span[]>;
+  protected abstract addOrUpdateTrace(trace: Trace): Promise<void>;
+  /**
+   * Stores a span, merging it into any existing span with the same ID (via the
+   * internal `mergeSpans` helper). Returns the resulting stored span so callers can
+   * stream the merged view rather than the partial snapshot they passed in.
+   */
+  protected abstract addOrUpdateSpan(span: Span): Promise<Span>;
+  getTrace(traceId: string): Promise<TraceWithSpans | undefined>;
+  subscribeTrace(traceId: string, callback: (event: TraceStreamEvent) => void): () => void;
+  watch(callback: (event: TraceChangeEvent) => void): () => void;
+  /**
+   * Returns a `SpanProcessor` that funnels every OpenTelemetry span the
+   * caller's tracer produces into this provider's in-memory store.
+   */
+  getSpanProcessor(): SpanProcessor;
+  private handleStart;
+  private handleEnd;
+  private emitStream;
+  private emitChange;
+  drainPendingHandlers(): Promise<void>;
+}
+//#endregion
+//#region src/trace/memory-trace-provider.d.ts
+/**
+ * In-memory {@link TraceProvider} populated by OpenTelemetry spans.
+ *
+ * Register the processor returned by {@link getSpanProcessor} on a
+ * `BasicTracerProvider` (from `@opentelemetry/sdk-trace-base`).
+ */
+declare class MemoryTraceProvider extends BaseOTelTraceProvider {
+  private traces;
+  private spansByTrace;
+  constructor({
+    id,
+    displayName,
+    description
+  }?: {
+    id?: string;
+    displayName?: string;
+    description?: string;
+  });
+  getAllTraces(): Promise<TraceSummary[]>;
+  hasTrace(traceId: string): Promise<boolean>;
+  protected getTraceWithoutSpans(traceId: string): Promise<Trace | undefined>;
+  protected getTraceSpans(traceId: string): Promise<Span[]>;
+  protected addOrUpdateTrace(trace: Trace): Promise<void>;
+  protected addOrUpdateSpan(span: Span): Promise<Span>;
+}
+//#endregion
+export { type AddPromptContext, type AddPromptField, type CalleeBinding, type ChangeEventType, type EvalutionConfig, type ExecuteRequest, type ExecuteResponse, type ExtractedProps, type FilePromptMetadata, FilePromptProvider, type FilePromptProviderOptions, type FileProvider, type FileWatchCallback, type FileWatchOptions, GeminiInteractionsSDK, type GlobOptions, type LLMSpanDetails, LocalFileProvider, MemoryFileProvider, MemoryTraceProvider, type ModelCatalog, type ModelGroupInfo, type ModelInfo, type ModelPropValue, type ModelValueType, type NormalizedFilePrompt, type NormalizedMessage, type NormalizedParameter, type NormalizedPrompt, type NormalizedPromptUpdates, type NormalizedToolCall, PROMPT_ID_ATTRIBUTE, PROMPT_NAME_ATTRIBUTE, PROMPT_PROVIDER_ID_ATTRIBUTE, type ParsedFilePrompt, type ParsedPrompt, type PromptChangeEvent, type PromptFileType, type PromptID, type PromptProvider, type PromptProviderInfo, type PropDefinition, type PropValue, type SDKAdapter, SPAN_KIND_ATTRIBUTE, type SetupCreateConfigStep, type SetupInstallPackageStep, type SetupRunCommandStep, type SetupStep, type SetupStepBase, type SetupTask, type SourceSpan, type Span, type SpanKind, type SpanMessage, TSPromptFileType, type Trace, type TraceChangeEvent, type TraceChangeType, type TraceProvider, type TraceProviderInfo, type TraceStreamEvent, type TraceSummary, type TraceWithSpans, VercelAISDK, createTracerForPrompt, setupStepCommand };