@dollhousemcp/mcp-server/dist/types/elements/IElement.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Core element interface that all element types must implement.
 * This provides the foundation for the portfolio system with support for:
 * - Identity and versioning
 * - References to external/internal resources
 * - Extensibility for future features
 * - Ratings and feedback mechanisms
 * - Lifecycle management
 */
import { ElementType } from '../../portfolio/types.js';
import type { ElementGatekeeperPolicy } from '../../handlers/mcp-aql/GatekeeperTypes.js';
export interface IElement {
    id: string;
    type: ElementType;
    version: string;
    metadata: IElementMetadata;
    references?: Reference[];
    extensions?: Record<string, any>;
    ratings?: ElementRatings;
    validate(): ElementValidationResult;
    serialize(): string;
    deserialize(data: string): void;
    receiveFeedback?(feedback: string, context?: FeedbackContext): void;
    beforeActivate?(): Promise<void>;
    activate?(): Promise<void>;
    afterActivate?(): Promise<void>;
    deactivate?(): Promise<void>;
    getStatus(): ElementStatus;
}
export interface IElementMetadata {
    name: string;
    description: string;
    type?: ElementType;
    author?: string;
    version?: string;
    created?: string;
    modified?: string;
    tags?: string[];
    dependencies?: ElementDependency[];
    custom?: Record<string, any>;
    /**
     * v2.0 dual-field architecture: behavioral directives loaded from YAML frontmatter.
     *
     * During deserialization, managers extract `instructions` from the parsed YAML
     * metadata and assign it to `element.instructions`. This field is then deleted
     * from the metadata object to avoid duplication. Its presence in YAML frontmatter
     * is used to detect v2 format vs v1 (body-text-only) format.
     *
     * @since Issue #602 — Dual-field element architecture
     */
    instructions?: string;
    /**
     * Gatekeeper access-control policy for this element.
     *
     * When the element is active, its policy participates in Layer 2
     * (element policy resolution) of the Gatekeeper enforcement pipeline.
     * {@link resolveElementPolicy} iterates all active elements and evaluates
     * their `gatekeeper` field to determine whether an MCP-AQL operation
     * should be allowed, denied, or require confirmation.
     *
     * Policy fields (all optional):
     * - `allow`  — Operations auto-approved when this element is active
     * - `confirm` — Operations requiring user confirmation
     * - `deny`   — Operations blocked outright
     * - `scopeRestrictions` — Restrict operations to/from specific element types
     *
     * Defined in YAML front matter and validated at both write time
     * ({@link validateGatekeeperPolicy}) and read time via
     * {@link parseElementPolicy}. Malformed policies are logged and stripped.
     *
     * @since Issue #524 — Extended from agents to all element types
     * @see ElementGatekeeperPolicy
     * @see resolveElementPolicy
     */
    gatekeeper?: ElementGatekeeperPolicy;
    /**
     * Runtime-only diagnostics for malformed gatekeeper policy discovered during load.
     * This is reporting state, not enforceable policy, and must never be persisted.
     */
    gatekeeperDiagnostics?: {
        valid: false;
        enforceable: false;
        message: string;
    };
}
export interface Reference {
    type: ReferenceType;
    uri: string;
    title: string;
    description?: string;
    required?: boolean;
    ragEnabled?: boolean;
    cacheable?: boolean;
    refreshInterval?: number;
}
export declare enum ReferenceType {
    INTERNAL = "internal",// Reference to another element
    EXTERNAL = "external",// Web URL
    DOCUMENT = "document",// Local or RAG document
    REPOSITORY = "repository",// Git repository
    API = "api",// API endpoint
    PORTFOLIO = "portfolio"
}
export interface ElementDependency {
    elementId: string;
    elementType: ElementType;
    versionConstraint?: string;
    optional?: boolean;
}
export interface ElementValidationResult {
    valid: boolean;
    errors?: ValidationError[];
    warnings?: ValidationWarning[];
    suggestions?: string[];
}
export interface ValidationError {
    field: string;
    message: string;
    code?: string;
}
export interface ValidationWarning {
    field: string;
    message: string;
    severity?: 'low' | 'medium' | 'high';
}
export declare enum ElementStatus {
    INACTIVE = "inactive",
    ACTIVATING = "activating",
    ACTIVE = "active",
    DEACTIVATING = "deactivating",
    ERROR = "error",
    SUSPENDED = "suspended"
}
export interface ElementRatings {
    aiRating: number;
    userRating?: number;
    ratingCount: number;
    lastEvaluated: Date;
    confidence: number;
    breakdown?: RatingBreakdown;
    ratingDelta?: number;
    trend: 'improving' | 'declining' | 'stable';
    feedbackHistory?: UserFeedback[];
}
export interface RatingBreakdown {
    effectiveness: number;
    reliability: number;
    usability: number;
    [key: string]: number;
}
export interface UserFeedback {
    timestamp: Date;
    feedback: string;
    sentiment: 'positive' | 'negative' | 'neutral';
    inferredRating?: number;
    context?: FeedbackContext;
    elementVersion?: string;
}
export interface FeedbackContext {
    task?: string;
    relatedElements?: string[];
    sessionId?: string;
    environmentData?: Record<string, any>;
}
export interface ISchemaVersion {
    schemaVersion?: string;
    migrate?(fromVersion: string): void;
}
//# sourceMappingURL=IElement.d.ts.map