niceeval 0.18.0 → 0.19.0

package/dist/plugin/contracts.d.cts

@@ -1,8 +1,14 @@
 import type { ExperimentHookContext } from "../runner/types.cjs";
 import type { JsonValue, ScopedFeedback } from "../shared/types.cjs";
 import { type SandboxLayer } from "../sandbox/layer.cjs";
+import type { SandboxAction, SandboxAfterAction } from "../sandbox/action.cjs";
+import type { SandboxCommandContext, SandboxCommandTarget } from "../sandbox/commands.cjs";
+import type { CodexConfig } from "../agents/codex.cjs";
+import type { ClaudeCodeConfig } from "../agents/claude-code.cjs";
+import type { BubConfig } from "../agents/bub.cjs";
+import type { SkillSpec, McpServer } from "../agents/types.cjs";
 export type PluginOwner = "experiment" | "group" | "eval";
-export type PluginScope = PluginOwner | "sandbox";
+export type PluginScope = "experiment" | "group" | "sandbox" | "attempt";
 export type PluginOnUnavailable = "stop-group" | "replace-sandbox";
 declare const PLUGIN_INSTANCE: unique symbol;
 export interface PluginInstance<Owners extends PluginOwner = PluginOwner> {
@@ -14,124 +20,130 @@ export interface GroupPluginContext extends ScopedFeedback {
     readonly evalGroupId: string;
     readonly signal: AbortSignal;
 }
-export interface EvalPluginContext extends ScopedFeedback {
+type EvalGroupRef = NonNullable<SandboxCommandContext["evalGroup"]>;
+export interface AttemptPluginContext extends ScopedFeedback {
     readonly experimentId: string;
     readonly evalId: string;
     readonly attempt: number;
-    readonly evalGroupId?: string;
+    readonly evalGroup?: EvalGroupRef;
     readonly signal: AbortSignal;
 }
 export type ExperimentPluginContext = ExperimentHookContext;
+export type PluginElements<Element> = Element | readonly Element[];
 export type PluginLifecycleFragment<Hook> = Readonly<{
-    readonly identity?: Readonly<globalThis.Record<string, JsonValue>>;
-} & ({
-    readonly setup: Hook;
-    readonly teardown?: Hook;
-} | {
-    readonly setup?: Hook;
-    readonly teardown: Hook;
-})>;
+    readonly before?: PluginElements<Hook>;
+    readonly after?: PluginElements<Hook>;
+}>;
 export type ExperimentPluginFragment = PluginLifecycleFragment<PluginHook<ExperimentHookContext>>;
 export type GroupPluginFragment = PluginLifecycleFragment<PluginHook<GroupPluginContext>>;
-export type SandboxPluginFragment = SandboxLayer<"command-only">;
-export type EvalPluginFragment = PluginLifecycleFragment<PluginHook<EvalPluginContext>>;
-export interface PluginDefinition<Options> {
-    readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey?: (options: Options) => string;
-    readonly experiment?: (options: Options) => ExperimentPluginFragment;
-    readonly group?: (options: Options) => GroupPluginFragment;
-    readonly sandbox?: (options: Options) => SandboxPluginFragment;
-    readonly eval?: (options: Options) => EvalPluginFragment;
+type GroupContext<Context, Required extends boolean> = Required extends true ? Omit<Context, "evalGroup"> & {
+    readonly evalGroup: EvalGroupRef;
+} : Context;
+export type AttemptPluginFragment<Required extends boolean = false> = PluginLifecycleFragment<PluginHook<GroupContext<AttemptPluginContext, Required>>>;
+export interface SandboxPluginFragment<Required extends boolean = false> {
+    readonly before?: PluginElements<SandboxAction | ((sandbox: SandboxCommandTarget, context: GroupContext<SandboxCommandContext, Required>) => void | Promise<void>)>;
+    readonly after?: PluginElements<SandboxAfterAction | ((sandbox: SandboxCommandTarget, context: GroupContext<Omit<SandboxCommandContext, "onCleanup">, Required>) => void | Promise<void>)>;
+}
+export interface PluginAgentExtensions {
+    readonly skills?: readonly SkillSpec[];
+    readonly mcpServers?: readonly McpServer[];
+    readonly codex?: Pick<CodexConfig, "plugins" | "configFile" | "before" | "after">;
+    readonly claudeCode?: Pick<ClaudeCodeConfig, "plugins" | "settingsFile" | "before" | "after">;
+    readonly bub?: Pick<BubConfig, "pythonPlugins" | "before" | "after">;
 }
-type AtLeastOneScope<Options> = {
-    readonly experiment: (options: Options) => ExperimentPluginFragment;
+interface PluginFields<Required extends boolean> {
+    readonly agent?: PluginAgentExtensions;
+    readonly experiment?: ExperimentPluginFragment;
+    readonly group?: GroupPluginFragment;
+    readonly sandbox?: SandboxPluginFragment<Required>;
+    readonly attempt?: AttemptPluginFragment<Required>;
+}
+type NonEmptyFields<Required extends boolean> = PluginFields<Required> & ({
+    readonly agent: PluginAgentExtensions;
 } | {
-    readonly group: (options: Options) => GroupPluginFragment;
+    readonly experiment: ExperimentPluginFragment;
 } | {
-    readonly sandbox: (options: Options) => SandboxPluginFragment;
+    readonly group: GroupPluginFragment;
 } | {
-    readonly eval: (options: Options) => EvalPluginFragment;
-};
-type HostFragmentFactories<Options> = Readonly<{
-    experiment: (options: Options) => ExperimentPluginFragment;
-    group: (options: Options) => GroupPluginFragment;
-    eval: (options: Options) => EvalPluginFragment;
-}>;
-type ExactHostFragments<Options, Owners extends PluginOwner> = {
-    readonly [Owner in Owners]-?: HostFragmentFactories<Options>[Owner];
-} & {
-    readonly [Owner in Exclude<PluginOwner, Owners>]?: never;
-};
-type OptionedPluginDefinition<Options, Owners extends PluginOwner> = Omit<PluginDefinition<Options>, PluginOwner | "instanceKey"> & ExactHostFragments<Options, Owners> & {
-    readonly instanceKey: (options: Options) => string;
-};
-type OptionedSandboxOnlyPluginDefinition<Options> = Omit<PluginDefinition<Options>, PluginOwner | "sandbox" | "instanceKey"> & {
-    readonly [Owner in PluginOwner]?: never;
-} & {
-    readonly sandbox: (options: Options) => SandboxPluginFragment;
-    readonly instanceKey: (options: Options) => string;
-};
-type HostScopesOf<Definition> = (Definition extends {
-    readonly experiment: (...args: any[]) => unknown;
-} ? "experiment" : never) | (Definition extends {
-    readonly group: (...args: any[]) => unknown;
-} ? "group" : never) | (Definition extends {
-    readonly eval: (...args: any[]) => unknown;
-} ? "eval" : never);
-type ScopesOf<Definition> = [HostScopesOf<Definition>] extends [never] ? Definition extends {
-    readonly sandbox: (...args: any[]) => unknown;
-} ? PluginOwner : never : HostScopesOf<Definition>;
-type NormalizedPluginLifecycleFragment<Hook> = Readonly<{
+    readonly sandbox: SandboxPluginFragment<Required>;
+} | {
+    readonly attempt: AttemptPluginFragment<Required>;
+});
+interface PluginIdentity {
+    readonly behaviorRevision?: never;
+    readonly instanceKey?: never;
+    readonly eval?: never;
+    readonly name: string;
+    readonly key?: string;
     readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
-    readonly setup?: Hook;
-    readonly teardown?: Hook;
-    readonly hostDeclared: boolean;
-}>;
+}
+type GroupRequiredPluginDefinition = PluginIdentity & {
+    readonly requires: {
+        readonly evalGroup: true;
+    };
+} & NonEmptyFields<true>;
+type OptionalGroupPluginDefinition = PluginIdentity & {
+    readonly requires?: {
+        readonly evalGroup?: false;
+    };
+} & NonEmptyFields<false>;
+export type PluginDefinition = GroupRequiredPluginDefinition | OptionalGroupPluginDefinition;
+type OwnersOf<Definition> = Definition extends {
+    readonly agent: unknown;
+} | {
+    readonly experiment: unknown;
+} ? "experiment" : Definition extends {
+    readonly group: unknown;
+} ? "experiment" | "group" : PluginOwner;
+interface NormalizedLifecycle<Context> {
+    readonly before: readonly PluginHook<Context>[];
+    readonly after: readonly PluginHook<Context>[];
+}
 export interface PluginInstanceData {
     readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey: string;
-    readonly experiment?: NormalizedPluginLifecycleFragment<PluginHook<ExperimentHookContext>>;
-    readonly group?: NormalizedPluginLifecycleFragment<PluginHook<GroupPluginContext>>;
-    readonly sandbox?: SandboxPluginFragment;
-    readonly eval?: NormalizedPluginLifecycleFragment<PluginHook<EvalPluginContext>>;
+    readonly key: string;
+    readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
+    readonly requires: Readonly<{
+        evalGroup?: true;
+    }>;
+    readonly agent?: PluginAgentExtensions;
+    readonly experiment?: NormalizedLifecycle<ExperimentHookContext>;
+    readonly group?: NormalizedLifecycle<GroupPluginContext>;
+    readonly attempt?: NormalizedLifecycle<AttemptPluginContext>;
+    readonly sandbox?: SandboxLayer<"command-only">;
+    readonly shape: JsonValue;
+    readonly agentProjection?: JsonValue;
 }
 export interface LinkedPluginLifecycle {
     readonly scope: PluginOwner;
     readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey: string;
+    readonly key: string;
     readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
+    readonly requires: PluginInstanceData["requires"];
+    readonly shape: JsonValue;
+    readonly agentProjection?: JsonValue;
     readonly arrayPosition: number;
+    readonly beforeCount: number;
+    readonly afterCount: number;
     readonly hasSetup: boolean;
     readonly hasTeardown: boolean;
     readonly hostDeclared: boolean;
-    readonly sandboxLayer?: SandboxPluginFragment;
+    readonly sandboxLayer?: SandboxLayer<"command-only">;
     readonly setup?: PluginHook<any>;
     readonly teardown?: PluginHook<any>;
 }
-export declare function definePlugin<Options, const Definition extends PluginDefinition<Options> & AtLeastOneScope<Options>>(definition: Definition & {
-    readonly instanceKey: (options: Options) => string;
-}): (options: Options) => PluginInstance<ScopesOf<Definition>>;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, PluginOwner>): (options: Options) => PluginInstance<PluginOwner>;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment" | "group">): (options: Options) => PluginInstance<"experiment" | "group">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment" | "eval">): (options: Options) => PluginInstance<"experiment" | "eval">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "group" | "eval">): (options: Options) => PluginInstance<"group" | "eval">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment">): (options: Options) => PluginInstance<"experiment">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "group">): (options: Options) => PluginInstance<"group">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "eval">): (options: Options) => PluginInstance<"eval">;
-export declare function definePlugin<Options>(definition: OptionedSandboxOnlyPluginDefinition<Options>): (options: Options) => PluginInstance<PluginOwner>;
-/** Broadly annotated dynamic definitions retain runtime owner validation. */
-export declare function definePlugin<Options>(definition: PluginDefinition<Options> & AtLeastOneScope<Options> & {
-    readonly instanceKey: (options: Options) => string;
-}): (options: Options) => PluginInstance<PluginOwner>;
-export declare function definePlugin<const Definition extends PluginDefinition<void> & AtLeastOneScope<void>>(definition: Definition & {
-    readonly instanceKey?: never;
-}): () => PluginInstance<ScopesOf<Definition>>;
+export declare function pluginSourceOf(declaration: object): string | undefined;
+export declare function definePlugin<const Definition extends GroupRequiredPluginDefinition>(spec: Definition): PluginInstance<OwnersOf<Definition>>;
+export declare function definePlugin<const Definition extends OptionalGroupPluginDefinition>(spec: Definition): PluginInstance<OwnersOf<Definition>>;
+export declare function definePlugin<Options, const Required extends boolean = false, const Definition extends PluginIdentity = PluginIdentity>(factory: (options: Options) => Definition & {
+    readonly requires?: {
+        readonly evalGroup: Required;
+    };
+} & NonEmptyFields<Required>): (options: Options) => PluginInstance<OwnersOf<Definition>>;
 export declare function isPluginInstance(value: unknown): value is PluginInstance;
 export declare function pluginInstanceDataOf(value: PluginInstance<any>): PluginInstanceData;
-export declare function linkPluginLifecycles<Scope extends PluginOwner>(plugins: readonly PluginInstance<Scope>[], scope: Scope): readonly LinkedPluginLifecycle[];
-export declare function pluginLifecycleIdentity({ scope, name, behaviorRevision, instanceKey, identity, arrayPosition, hasSetup, hasTeardown }: LinkedPluginLifecycle): JsonValue;
+export declare function assertPluginOwner(plugin: PluginInstance<any>, scope: PluginOwner, label: string): void;
+export declare function linkPluginLifecycles<Scope extends PluginOwner>(plugins: readonly PluginInstance<Scope>[], scope: Scope, field?: "experiment" | "group" | "attempt"): readonly LinkedPluginLifecycle[];
+export declare function pluginLifecycleIdentity({ scope, name, key, identity, requires, shape, agentProjection, arrayPosition }: LinkedPluginLifecycle): JsonValue;
 export declare function pluginLifecycleProjection(lifecycles: readonly LinkedPluginLifecycle[]): JsonValue;
 export {};

package/dist/plugin/contracts.d.mts

@@ -1,8 +1,14 @@
 import type { ExperimentHookContext } from "../runner/types.mjs";
 import type { JsonValue, ScopedFeedback } from "../shared/types.mjs";
 import { type SandboxLayer } from "../sandbox/layer.mjs";
+import type { SandboxAction, SandboxAfterAction } from "../sandbox/action.mjs";
+import type { SandboxCommandContext, SandboxCommandTarget } from "../sandbox/commands.mjs";
+import type { CodexConfig } from "../agents/codex.mjs";
+import type { ClaudeCodeConfig } from "../agents/claude-code.mjs";
+import type { BubConfig } from "../agents/bub.mjs";
+import type { SkillSpec, McpServer } from "../agents/types.mjs";
 export type PluginOwner = "experiment" | "group" | "eval";
-export type PluginScope = PluginOwner | "sandbox";
+export type PluginScope = "experiment" | "group" | "sandbox" | "attempt";
 export type PluginOnUnavailable = "stop-group" | "replace-sandbox";
 declare const PLUGIN_INSTANCE: unique symbol;
 export interface PluginInstance<Owners extends PluginOwner = PluginOwner> {
@@ -14,124 +20,130 @@ export interface GroupPluginContext extends ScopedFeedback {
     readonly evalGroupId: string;
     readonly signal: AbortSignal;
 }
-export interface EvalPluginContext extends ScopedFeedback {
+type EvalGroupRef = NonNullable<SandboxCommandContext["evalGroup"]>;
+export interface AttemptPluginContext extends ScopedFeedback {
     readonly experimentId: string;
     readonly evalId: string;
     readonly attempt: number;
-    readonly evalGroupId?: string;
+    readonly evalGroup?: EvalGroupRef;
     readonly signal: AbortSignal;
 }
 export type ExperimentPluginContext = ExperimentHookContext;
+export type PluginElements<Element> = Element | readonly Element[];
 export type PluginLifecycleFragment<Hook> = Readonly<{
-    readonly identity?: Readonly<globalThis.Record<string, JsonValue>>;
-} & ({
-    readonly setup: Hook;
-    readonly teardown?: Hook;
-} | {
-    readonly setup?: Hook;
-    readonly teardown: Hook;
-})>;
+    readonly before?: PluginElements<Hook>;
+    readonly after?: PluginElements<Hook>;
+}>;
 export type ExperimentPluginFragment = PluginLifecycleFragment<PluginHook<ExperimentHookContext>>;
 export type GroupPluginFragment = PluginLifecycleFragment<PluginHook<GroupPluginContext>>;
-export type SandboxPluginFragment = SandboxLayer<"command-only">;
-export type EvalPluginFragment = PluginLifecycleFragment<PluginHook<EvalPluginContext>>;
-export interface PluginDefinition<Options> {
-    readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey?: (options: Options) => string;
-    readonly experiment?: (options: Options) => ExperimentPluginFragment;
-    readonly group?: (options: Options) => GroupPluginFragment;
-    readonly sandbox?: (options: Options) => SandboxPluginFragment;
-    readonly eval?: (options: Options) => EvalPluginFragment;
+type GroupContext<Context, Required extends boolean> = Required extends true ? Omit<Context, "evalGroup"> & {
+    readonly evalGroup: EvalGroupRef;
+} : Context;
+export type AttemptPluginFragment<Required extends boolean = false> = PluginLifecycleFragment<PluginHook<GroupContext<AttemptPluginContext, Required>>>;
+export interface SandboxPluginFragment<Required extends boolean = false> {
+    readonly before?: PluginElements<SandboxAction | ((sandbox: SandboxCommandTarget, context: GroupContext<SandboxCommandContext, Required>) => void | Promise<void>)>;
+    readonly after?: PluginElements<SandboxAfterAction | ((sandbox: SandboxCommandTarget, context: GroupContext<Omit<SandboxCommandContext, "onCleanup">, Required>) => void | Promise<void>)>;
+}
+export interface PluginAgentExtensions {
+    readonly skills?: readonly SkillSpec[];
+    readonly mcpServers?: readonly McpServer[];
+    readonly codex?: Pick<CodexConfig, "plugins" | "configFile" | "before" | "after">;
+    readonly claudeCode?: Pick<ClaudeCodeConfig, "plugins" | "settingsFile" | "before" | "after">;
+    readonly bub?: Pick<BubConfig, "pythonPlugins" | "before" | "after">;
 }
-type AtLeastOneScope<Options> = {
-    readonly experiment: (options: Options) => ExperimentPluginFragment;
+interface PluginFields<Required extends boolean> {
+    readonly agent?: PluginAgentExtensions;
+    readonly experiment?: ExperimentPluginFragment;
+    readonly group?: GroupPluginFragment;
+    readonly sandbox?: SandboxPluginFragment<Required>;
+    readonly attempt?: AttemptPluginFragment<Required>;
+}
+type NonEmptyFields<Required extends boolean> = PluginFields<Required> & ({
+    readonly agent: PluginAgentExtensions;
 } | {
-    readonly group: (options: Options) => GroupPluginFragment;
+    readonly experiment: ExperimentPluginFragment;
 } | {
-    readonly sandbox: (options: Options) => SandboxPluginFragment;
+    readonly group: GroupPluginFragment;
 } | {
-    readonly eval: (options: Options) => EvalPluginFragment;
-};
-type HostFragmentFactories<Options> = Readonly<{
-    experiment: (options: Options) => ExperimentPluginFragment;
-    group: (options: Options) => GroupPluginFragment;
-    eval: (options: Options) => EvalPluginFragment;
-}>;
-type ExactHostFragments<Options, Owners extends PluginOwner> = {
-    readonly [Owner in Owners]-?: HostFragmentFactories<Options>[Owner];
-} & {
-    readonly [Owner in Exclude<PluginOwner, Owners>]?: never;
-};
-type OptionedPluginDefinition<Options, Owners extends PluginOwner> = Omit<PluginDefinition<Options>, PluginOwner | "instanceKey"> & ExactHostFragments<Options, Owners> & {
-    readonly instanceKey: (options: Options) => string;
-};
-type OptionedSandboxOnlyPluginDefinition<Options> = Omit<PluginDefinition<Options>, PluginOwner | "sandbox" | "instanceKey"> & {
-    readonly [Owner in PluginOwner]?: never;
-} & {
-    readonly sandbox: (options: Options) => SandboxPluginFragment;
-    readonly instanceKey: (options: Options) => string;
-};
-type HostScopesOf<Definition> = (Definition extends {
-    readonly experiment: (...args: any[]) => unknown;
-} ? "experiment" : never) | (Definition extends {
-    readonly group: (...args: any[]) => unknown;
-} ? "group" : never) | (Definition extends {
-    readonly eval: (...args: any[]) => unknown;
-} ? "eval" : never);
-type ScopesOf<Definition> = [HostScopesOf<Definition>] extends [never] ? Definition extends {
-    readonly sandbox: (...args: any[]) => unknown;
-} ? PluginOwner : never : HostScopesOf<Definition>;
-type NormalizedPluginLifecycleFragment<Hook> = Readonly<{
+    readonly sandbox: SandboxPluginFragment<Required>;
+} | {
+    readonly attempt: AttemptPluginFragment<Required>;
+});
+interface PluginIdentity {
+    readonly behaviorRevision?: never;
+    readonly instanceKey?: never;
+    readonly eval?: never;
+    readonly name: string;
+    readonly key?: string;
     readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
-    readonly setup?: Hook;
-    readonly teardown?: Hook;
-    readonly hostDeclared: boolean;
-}>;
+}
+type GroupRequiredPluginDefinition = PluginIdentity & {
+    readonly requires: {
+        readonly evalGroup: true;
+    };
+} & NonEmptyFields<true>;
+type OptionalGroupPluginDefinition = PluginIdentity & {
+    readonly requires?: {
+        readonly evalGroup?: false;
+    };
+} & NonEmptyFields<false>;
+export type PluginDefinition = GroupRequiredPluginDefinition | OptionalGroupPluginDefinition;
+type OwnersOf<Definition> = Definition extends {
+    readonly agent: unknown;
+} | {
+    readonly experiment: unknown;
+} ? "experiment" : Definition extends {
+    readonly group: unknown;
+} ? "experiment" | "group" : PluginOwner;
+interface NormalizedLifecycle<Context> {
+    readonly before: readonly PluginHook<Context>[];
+    readonly after: readonly PluginHook<Context>[];
+}
 export interface PluginInstanceData {
     readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey: string;
-    readonly experiment?: NormalizedPluginLifecycleFragment<PluginHook<ExperimentHookContext>>;
-    readonly group?: NormalizedPluginLifecycleFragment<PluginHook<GroupPluginContext>>;
-    readonly sandbox?: SandboxPluginFragment;
-    readonly eval?: NormalizedPluginLifecycleFragment<PluginHook<EvalPluginContext>>;
+    readonly key: string;
+    readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
+    readonly requires: Readonly<{
+        evalGroup?: true;
+    }>;
+    readonly agent?: PluginAgentExtensions;
+    readonly experiment?: NormalizedLifecycle<ExperimentHookContext>;
+    readonly group?: NormalizedLifecycle<GroupPluginContext>;
+    readonly attempt?: NormalizedLifecycle<AttemptPluginContext>;
+    readonly sandbox?: SandboxLayer<"command-only">;
+    readonly shape: JsonValue;
+    readonly agentProjection?: JsonValue;
 }
 export interface LinkedPluginLifecycle {
     readonly scope: PluginOwner;
     readonly name: string;
-    readonly behaviorRevision: string;
-    readonly instanceKey: string;
+    readonly key: string;
     readonly identity: Readonly<globalThis.Record<string, JsonValue>>;
+    readonly requires: PluginInstanceData["requires"];
+    readonly shape: JsonValue;
+    readonly agentProjection?: JsonValue;
     readonly arrayPosition: number;
+    readonly beforeCount: number;
+    readonly afterCount: number;
     readonly hasSetup: boolean;
     readonly hasTeardown: boolean;
     readonly hostDeclared: boolean;
-    readonly sandboxLayer?: SandboxPluginFragment;
+    readonly sandboxLayer?: SandboxLayer<"command-only">;
     readonly setup?: PluginHook<any>;
     readonly teardown?: PluginHook<any>;
 }
-export declare function definePlugin<Options, const Definition extends PluginDefinition<Options> & AtLeastOneScope<Options>>(definition: Definition & {
-    readonly instanceKey: (options: Options) => string;
-}): (options: Options) => PluginInstance<ScopesOf<Definition>>;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, PluginOwner>): (options: Options) => PluginInstance<PluginOwner>;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment" | "group">): (options: Options) => PluginInstance<"experiment" | "group">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment" | "eval">): (options: Options) => PluginInstance<"experiment" | "eval">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "group" | "eval">): (options: Options) => PluginInstance<"group" | "eval">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "experiment">): (options: Options) => PluginInstance<"experiment">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "group">): (options: Options) => PluginInstance<"group">;
-export declare function definePlugin<Options>(definition: OptionedPluginDefinition<Options, "eval">): (options: Options) => PluginInstance<"eval">;
-export declare function definePlugin<Options>(definition: OptionedSandboxOnlyPluginDefinition<Options>): (options: Options) => PluginInstance<PluginOwner>;
-/** Broadly annotated dynamic definitions retain runtime owner validation. */
-export declare function definePlugin<Options>(definition: PluginDefinition<Options> & AtLeastOneScope<Options> & {
-    readonly instanceKey: (options: Options) => string;
-}): (options: Options) => PluginInstance<PluginOwner>;
-export declare function definePlugin<const Definition extends PluginDefinition<void> & AtLeastOneScope<void>>(definition: Definition & {
-    readonly instanceKey?: never;
-}): () => PluginInstance<ScopesOf<Definition>>;
+export declare function pluginSourceOf(declaration: object): string | undefined;
+export declare function definePlugin<const Definition extends GroupRequiredPluginDefinition>(spec: Definition): PluginInstance<OwnersOf<Definition>>;
+export declare function definePlugin<const Definition extends OptionalGroupPluginDefinition>(spec: Definition): PluginInstance<OwnersOf<Definition>>;
+export declare function definePlugin<Options, const Required extends boolean = false, const Definition extends PluginIdentity = PluginIdentity>(factory: (options: Options) => Definition & {
+    readonly requires?: {
+        readonly evalGroup: Required;
+    };
+} & NonEmptyFields<Required>): (options: Options) => PluginInstance<OwnersOf<Definition>>;
 export declare function isPluginInstance(value: unknown): value is PluginInstance;
 export declare function pluginInstanceDataOf(value: PluginInstance<any>): PluginInstanceData;
-export declare function linkPluginLifecycles<Scope extends PluginOwner>(plugins: readonly PluginInstance<Scope>[], scope: Scope): readonly LinkedPluginLifecycle[];
-export declare function pluginLifecycleIdentity({ scope, name, behaviorRevision, instanceKey, identity, arrayPosition, hasSetup, hasTeardown }: LinkedPluginLifecycle): JsonValue;
+export declare function assertPluginOwner(plugin: PluginInstance<any>, scope: PluginOwner, label: string): void;
+export declare function linkPluginLifecycles<Scope extends PluginOwner>(plugins: readonly PluginInstance<Scope>[], scope: Scope, field?: "experiment" | "group" | "attempt"): readonly LinkedPluginLifecycle[];
+export declare function pluginLifecycleIdentity({ scope, name, key, identity, requires, shape, agentProjection, arrayPosition }: LinkedPluginLifecycle): JsonValue;
 export declare function pluginLifecycleProjection(lifecycles: readonly LinkedPluginLifecycle[]): JsonValue;
 export {};