import type { Character } from "./agent";
import type { Action, AgentContext, Evaluator, Provider } from "./components";
import type { IDatabaseAdapter } from "./database";
import type { EventHandler, EventPayload, EventPayloadMap } from "./events";
import type { ModelParamsMap, PluginModelResult } from "./model";
import type { UUID } from "./primitives";
import type { JsonValue, ComponentTypeDefinition as ProtoComponentTypeDefinition, JSONSchemaDefinition as ProtoJSONSchemaDefinition, RouteManifest as ProtoRouteManifest } from "./proto.js";
import type { IAgentRuntime } from "./runtime";
import type { Service } from "./service";
import type { TestSuite } from "./testing";
/**
 * Type for a service class constructor.
 * This is more flexible than `typeof Service` to allow for:
 * - Service classes with more specific `serviceType` values (e.g., "task" instead of string)
 * - Service classes that properly extend the base Service class
 */
export interface ServiceClass {
    /** The service type identifier */
    serviceType: string;
    /** Factory method to create and start the service */
    start(runtime: IAgentRuntime): Promise<Service>;
    /** Stop service for a runtime - optional as not all services implement this */
    stopRuntime?(runtime: IAgentRuntime): Promise<void>;
    /** Optional static method to register send handlers */
    registerSendHandlers?(runtime: IAgentRuntime, service: Service): void;
    /** Constructor (optional runtime parameter) */
    new (runtime?: IAgentRuntime): Service;
}
/**
 * Supported types for route request body fields
 */
export type RouteBodyValue = JsonValue;
/**
 * Minimal request interface
 * Plugins can use this type for route handlers
 */
export interface RouteRequest {
    body?: Record<string, RouteBodyValue>;
    params?: Record<string, string>;
    query?: Record<string, string | string[]>;
    headers?: Record<string, string | string[] | undefined>;
    method?: string;
    path?: string;
    url?: string;
}
/**
 * Minimal response interface
 * Plugins can use this type for route handlers
 */
export interface RouteResponse {
    status: (code: number) => RouteResponse;
    json: (data: unknown) => RouteResponse;
    send: (data: unknown) => RouteResponse;
    end: () => RouteResponse;
    setHeader?: (name: string, value: string | string[]) => RouteResponse;
    sendFile?: (path: string) => RouteResponse;
    headersSent?: boolean;
}
interface BaseRoute {
    type: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "STATIC";
    path: string;
    filePath?: string;
    handler?: (req: RouteRequest, res: RouteResponse, runtime: IAgentRuntime) => Promise<void>;
    isMultipart?: boolean;
    /**
     * When true, the route path is used as-is without the plugin-name prefix.
     * Use for legacy API paths that must remain stable (e.g. `/api/telegram-setup/status`).
     */
    rawPath?: boolean;
}
interface PublicRoute extends BaseRoute {
    public: true;
    name: string;
}
interface PrivateRoute extends BaseRoute {
    public?: false;
    name?: string;
}
export type Route = PublicRoute | PrivateRoute;
/**
 * JSON Schema type definition for component validation
 */
export type JSONSchemaDefinition = ProtoJSONSchemaDefinition;
/**
 * Component type definition for entity components
 */
export interface ComponentTypeDefinition extends Omit<ProtoComponentTypeDefinition, "schema"> {
    schema: JSONSchemaDefinition;
    validator?: (data: Record<string, RouteBodyValue>) => boolean;
}
/**
 * Plugin for extending agent functionality
 */
export type PluginEvents = {
    [K in keyof EventPayloadMap]?: EventHandler<K>[];
};
/** Internal type for runtime event storage - allows dynamic access for event registration */
export type RuntimeEventStorage = PluginEvents & {
    [key: string]: ((params: EventPayloadMap[keyof EventPayloadMap] | EventPayload) => Promise<void>)[] | undefined;
};
/**
 * Database adapter factory. When set on a plugin, this plugin provides the
 * database adapter. Called before runtime construction with agentId and basic-capabilities
 * settings (character + env, not DB). Only one plugin per character should set this.
 */
export type AdapterFactory = (agentId: UUID, settings: Record<string, string>) => IDatabaseAdapter | Promise<IDatabaseAdapter>;
export type PluginAppSessionMode = "viewer" | "spectate-and-steer" | "external";
export type PluginAppSessionFeature = "commands" | "telemetry" | "pause" | "resume" | "suggestions";
export type PluginAppControlAction = "pause" | "resume";
export type PluginAppTelemetryValue = JsonValue | PluginAppTelemetryValue[] | {
    [key: string]: PluginAppTelemetryValue;
};
export interface PluginAppViewer {
    url: string;
    embedParams?: Record<string, string>;
    postMessageAuth?: boolean;
    sandbox?: string;
}
export interface PluginAppViewerAuthMessage {
    type: string;
    authToken?: string;
    characterId?: string;
    sessionToken?: string;
    agentId?: string;
    followEntity?: string;
}
export interface PluginAppSession {
    mode: PluginAppSessionMode;
    features?: PluginAppSessionFeature[];
}
export interface PluginAppRecommendation {
    id: string;
    label: string;
    type?: string;
    reason?: string | null;
    priority?: number | null;
    command?: string | null;
}
export interface PluginAppActivityItem {
    id: string;
    type: string;
    message: string;
    timestamp?: number | null;
    severity?: "info" | "warning" | "error";
}
export interface PluginAppSessionState {
    sessionId: string;
    appName: string;
    mode: PluginAppSessionMode;
    status: string;
    displayName?: string;
    agentId?: string;
    characterId?: string;
    followEntity?: string;
    canSendCommands?: boolean;
    controls?: PluginAppControlAction[];
    summary?: string | null;
    goalLabel?: string | null;
    suggestedPrompts?: string[];
    recommendations?: PluginAppRecommendation[];
    activity?: PluginAppActivityItem[];
    telemetry?: Record<string, PluginAppTelemetryValue> | null;
}
export interface PluginAppLaunchDiagnostic {
    code: string;
    severity: "info" | "warning" | "error";
    message: string;
}
export interface PluginAppBridgeLaunchContext {
    appName?: string;
    launchUrl?: string | null;
    runtime?: IAgentRuntime | null;
    app?: PluginApp | null;
    viewer?: (PluginAppViewer & {
        authMessage?: PluginAppViewerAuthMessage;
    }) | null;
}
export interface PluginAppBridgeRunContext extends PluginAppBridgeLaunchContext {
    runId?: string;
    session?: PluginAppSessionState | null;
}
export interface PluginAppLaunchPreparation {
    diagnostics?: PluginAppLaunchDiagnostic[];
    launchUrl?: string | null;
    viewer?: PluginAppViewer | null;
}
export interface PluginAppBridge {
    handleAppRoutes?: (ctx: unknown) => Promise<boolean>;
    prepareLaunch?: (ctx: PluginAppBridgeLaunchContext) => Promise<PluginAppLaunchPreparation | null>;
    resolveViewerAuthMessage?: (ctx: PluginAppBridgeLaunchContext) => Promise<PluginAppViewerAuthMessage | null>;
    ensureRuntimeReady?: (ctx: PluginAppBridgeLaunchContext) => Promise<void>;
    collectLaunchDiagnostics?: (ctx: PluginAppBridgeRunContext) => Promise<PluginAppLaunchDiagnostic[]>;
    resolveLaunchSession?: (ctx: PluginAppBridgeLaunchContext) => Promise<PluginAppSessionState | null>;
    refreshRunSession?: (ctx: PluginAppBridgeRunContext) => Promise<PluginAppSessionState | null>;
}
export interface PluginApp {
    displayName?: string;
    category?: string;
    launchType?: string;
    launchUrl?: string | null;
    icon?: string | null;
    capabilities?: string[];
    minPlayers?: number | null;
    maxPlayers?: number | null;
    runtimePlugin?: string;
    viewer?: PluginAppViewer;
    session?: PluginAppSession;
    bridgeExport?: string;
}
export interface PluginEventRegistration {
    eventName: string;
    handler: (params: EventPayloadMap[keyof EventPayloadMap] | EventPayload) => Promise<void> | void;
}
export interface PluginModelRegistration {
    modelType: string;
    handler: (runtime: IAgentRuntime, params: Record<string, JsonValue | object>) => Promise<JsonValue | object>;
    provider: string;
}
export interface PluginServiceRegistration {
    serviceType: string;
    serviceClass: ServiceClass;
}
export interface PluginOwnership {
    pluginName: string;
    plugin: Plugin;
    registeredPlugin: Plugin | null;
    actions: Action[];
    providers: Provider[];
    evaluators: Evaluator[];
    routes: Route[];
    events: PluginEventRegistration[];
    models: PluginModelRegistration[];
    services: PluginServiceRegistration[];
    sendHandlerSources: string[];
    hasAdapter: boolean;
    registeredAt: number;
}
export interface Plugin {
    name: string;
    description: string;
    init?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void> | void;
    /**
     * Optional lifecycle hook invoked before a plugin is unloaded from a running runtime.
     * Use this to clean up timers, sockets, or other plugin-owned resources.
     */
    dispose?: (runtime: IAgentRuntime) => Promise<void> | void;
    /**
     * Optional lifecycle hook invoked for config-only updates that do not require
     * a full plugin reload.
     */
    applyConfig?: (config: Record<string, string>, runtime: IAgentRuntime) => Promise<void> | void;
    /** Plugin configuration - string keys to primitive values */
    config?: Record<string, string | number | boolean | null>;
    /**
     * Service classes to be registered with the runtime.
     * Uses ServiceClass interface which is more flexible than `typeof Service`
     * to allow service classes with specific serviceType values.
     */
    services?: ServiceClass[];
    /** Entity component definitions with JSON schema */
    componentTypes?: ComponentTypeDefinition[];
    actions?: Action[];
    providers?: Provider[];
    evaluators?: Evaluator[];
    /**
     * Database adapter factory. When set, this plugin provides the database
     * adapter. Called before runtime construction with agentId and basic-capabilities
     * settings (character + env, not DB). Only one plugin per character should
     * set this.
     */
    adapter?: AdapterFactory;
    models?: {
        [K in keyof ModelParamsMap]?: (runtime: IAgentRuntime, params: ModelParamsMap[K]) => Promise<PluginModelResult<K>>;
    };
    events?: PluginEvents;
    routes?: Route[];
    tests?: TestSuite[];
    dependencies?: string[];
    testDependencies?: string[];
    priority?: number;
    schema?: Record<string, JsonValue | object>;
    app?: PluginApp;
    appBridge?: PluginAppBridge;
    /**
     * Domain contexts this plugin's components belong to.
     * Acts as a default for all actions/providers/evaluators in the plugin
     * unless they declare their own contexts.
     */
    contexts?: AgentContext[];
    /**
     * Declarative auto-enable conditions. When present, the plugin self-describes
     * when it should be activated — replacing (or supplementing) the hardcoded
     * maps in `plugin-auto-enable.ts`.
     *
     * The runtime evaluates these after initial plugin resolution:
     * - `envKeys`: enable when ANY of these env vars are set and non-empty.
     * - `connectorKeys`: enable when ANY of these connector names appear and
     *   are configured in `config.connectors`.
     * - `shouldEnable`: custom predicate for complex enable logic.
     *
     * All three are OR'd — if any condition is met the plugin is auto-enabled.
     * The hardcoded map in `plugin-auto-enable.ts` still serves as a fallback
     * for plugins that have not yet adopted `autoEnable`.
     */
    autoEnable?: {
        /** Enable when any of these env vars are set and non-empty. */
        envKeys?: string[];
        /** Enable when any of these connector names appear in config.connectors. */
        connectorKeys?: string[];
        /** Custom predicate for complex enable logic. */
        shouldEnable?: (env: Record<string, string | undefined>, config: Record<string, unknown>) => boolean;
    };
}
export interface ProjectAgent {
    character: Character;
    init?: (runtime: IAgentRuntime) => Promise<void>;
    plugins?: Plugin[];
    tests?: TestSuite | TestSuite[];
}
export interface Project {
    agents: ProjectAgent[];
}
export type RouteManifest = ProtoRouteManifest;
export {};
//# sourceMappingURL=plugin.d.ts.map