@rizom/brain 0.2.0-alpha.5 → 0.2.0-alpha.50

package/dist/plugins.d.ts

@@ -0,0 +1,1120 @@
+import { z } from 'zod';
+
+/**
+ * Options for entity mutation operations (create, update, upsert)
+ */
+interface EntityJobOptions {
+    priority?: number;
+    maxRetries?: number;
+}
+/**
+ * Options for entity creation (extends EntityJobOptions with deduplication)
+ */
+interface CreateEntityOptions extends EntityJobOptions {
+    deduplicateId?: boolean;
+}
+/**
+ * Result of an entity mutation that triggers an embedding job.
+ * When skipped is true, content was unchanged — no DB write, no event, no embedding job.
+ */
+interface EntityMutationResult {
+    entityId: string;
+    jobId: string;
+    skipped: boolean;
+}
+/**
+ * Input for adapter-validated direct creation from finalized markdown.
+ */
+interface CreateEntityFromMarkdownInput {
+    entityType: string;
+    id: string;
+    markdown: string;
+}
+/**
+ * Data for storing an embedding for an entity
+ */
+interface StoreEmbeddingData {
+    entityId: string;
+    entityType: string;
+    embedding: Float32Array;
+    contentHash: string;
+}
+/**
+ * Base entity type - generic to support typed metadata
+ * TMetadata defaults to Record<string, unknown> for backward compatibility
+ */
+interface BaseEntity<TMetadata = Record<string, unknown>> {
+    id: string;
+    entityType: string;
+    content: string;
+    created: string;
+    updated: string;
+    metadata: TMetadata;
+    /** SHA256 hash of content for change detection */
+    contentHash: string;
+}
+/**
+ * Entity input type for creation - allows partial entities with optional system fields
+ * contentHash is excluded because it's computed automatically by the entity service
+ */
+type EntityInput<T extends BaseEntity> = Omit<T, "id" | "created" | "updated" | "contentHash"> & {
+    id?: string;
+    created?: string;
+    updated?: string;
+};
+/**
+ * Search result type
+ */
+interface SearchResult<T extends BaseEntity = BaseEntity> {
+    entity: T;
+    score: number;
+    excerpt: string;
+}
+/**
+ * Normalized system_create input shape used by plugin create interceptors.
+ */
+interface CreateInput {
+    entityType: string;
+    prompt?: string;
+    title?: string;
+    content?: string;
+    url?: string;
+    targetEntityType?: string;
+    targetEntityId?: string;
+}
+/**
+ * Minimal caller context forwarded to plugin create interceptors.
+ */
+interface CreateExecutionContext {
+    interfaceType: string;
+    userId: string;
+    channelId?: string;
+    channelName?: string;
+}
+/**
+ * Result returned to system_create when a plugin fully handles creation.
+ */
+type CreateResult = {
+    success: true;
+    data: {
+        entityId?: string;
+        jobId?: string;
+        status: string;
+    };
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Plugin create interceptors can either fully handle creation,
+ * or continue with a rewritten normalized input.
+ */
+type CreateInterceptionResult = {
+    kind: "handled";
+    result: CreateResult;
+} | {
+    kind: "continue";
+    input: CreateInput;
+};
+/**
+ * Interface for entity adapter - handles conversion between entities and markdown
+ * following the hybrid storage model
+ *
+ * @template TEntity - The full entity type
+ * @template TMetadata - The metadata type (defaults to Record<string, unknown>)
+ */
+interface EntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata = Record<string, unknown>> {
+    entityType: string;
+    schema: z.ZodSchema<TEntity>;
+    toMarkdown(entity: TEntity): string;
+    fromMarkdown(markdown: string): Partial<TEntity>;
+    extractMetadata(entity: TEntity): TMetadata;
+    parseFrontMatter<TFrontmatter>(markdown: string, schema: z.ZodSchema<TFrontmatter>): TFrontmatter;
+    generateFrontMatter(entity: TEntity): string;
+    /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */
+    frontmatterSchema?: z.ZodObject<z.ZodRawShape>;
+    /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */
+    isSingleton?: boolean;
+    /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */
+    hasBody?: boolean;
+    /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */
+    getBodyTemplate(): string;
+    /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */
+    supportsCoverImage?: boolean;
+    /** Optional: Extract coverImageId from entity content/frontmatter */
+    getCoverImageId?(entity: TEntity): string | undefined;
+}
+/**
+ * Sort field specification for multi-field sorting
+ */
+interface SortField {
+    /** Field to sort by - "created", "updated", or a metadata field name */
+    field: string;
+    /** Sort direction */
+    direction: "asc" | "desc";
+    /** Sort NULL values before non-NULL values (default: false / SQLite default) */
+    nullsFirst?: boolean;
+}
+/**
+ * List entities options
+ * Generic over metadata type for type-safe filtering
+ */
+interface ListOptions<TMetadata = Record<string, unknown>> {
+    limit?: number;
+    offset?: number;
+    /** Multi-field sorting - supports system fields (created, updated) and metadata fields */
+    sortFields?: SortField[];
+    filter?: {
+        metadata?: Partial<TMetadata>;
+    };
+    /** Filter to only entities with metadata.status = "published" */
+    publishedOnly?: boolean;
+}
+/**
+ * Search options
+ */
+interface SearchOptions {
+    limit?: number;
+    offset?: number;
+    types?: string[];
+    excludeTypes?: string[];
+    sortBy?: "relevance" | "created" | "updated";
+    sortDirection?: "asc" | "desc";
+    /** Score multipliers per entity type - applied after initial search */
+    weight?: Record<string, number>;
+}
+/**
+ * Configuration for entity type registration
+ */
+interface EntityTypeConfig {
+    /** Score multiplier for search results (default: 1.0) */
+    weight?: number;
+    /** Whether to generate embeddings for this entity type (default: true).
+     *  Set to false for entity types with non-textual content (e.g., images). */
+    embeddable?: boolean;
+}
+/**
+ * Core entity service interface for read-only operations
+ * Used by core plugins that need entity access but shouldn't modify entities
+ */
+interface ICoreEntityService {
+    getEntity<T extends BaseEntity>(entityType: string, id: string): Promise<T | null>;
+    /**
+     * Get entity without content resolution (raw)
+     * Used internally to avoid recursion when resolving image references
+     */
+    getEntityRaw<T extends BaseEntity>(entityType: string, id: string): Promise<T | null>;
+    listEntities<T extends BaseEntity>(type: string, options?: ListOptions): Promise<T[]>;
+    search<T extends BaseEntity = BaseEntity>(query: string, options?: SearchOptions): Promise<SearchResult<T>[]>;
+    getEntityTypes(): string[];
+    hasEntityType(type: string): boolean;
+    countEntities(entityType: string, options?: Pick<ListOptions, "publishedOnly" | "filter">): Promise<number>;
+    getEntityCounts(): Promise<Array<{
+        entityType: string;
+        count: number;
+    }>>;
+    /** Get weight map for all registered entity types with non-default weights */
+    getWeightMap(): Record<string, number>;
+}
+/**
+ * Entity service interface for managing brain entities
+ */
+interface EntityService extends ICoreEntityService {
+    createEntity<T extends BaseEntity>(entity: EntityInput<T>, options?: CreateEntityOptions): Promise<EntityMutationResult>;
+    createEntityFromMarkdown(input: CreateEntityFromMarkdownInput, options?: CreateEntityOptions): Promise<EntityMutationResult>;
+    updateEntity<T extends BaseEntity>(entity: T, options?: EntityJobOptions): Promise<EntityMutationResult>;
+    deleteEntity(entityType: string, id: string): Promise<boolean>;
+    upsertEntity<T extends BaseEntity>(entity: T, options?: EntityJobOptions): Promise<EntityMutationResult & {
+        created: boolean;
+    }>;
+    storeEmbedding(data: StoreEmbeddingData): Promise<void>;
+    serializeEntity(entity: BaseEntity): string;
+    deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;
+    countEmbeddings(): Promise<number>;
+    searchWithDistances(query: string): Promise<Array<{
+        entityId: string;
+        entityType: string;
+        distance: number;
+    }>>;
+    initialize(): Promise<void>;
+    getAsyncJobStatus(jobId: string): Promise<{
+        status: "pending" | "processing" | "completed" | "failed";
+        error?: string;
+    } | null>;
+}
+
+/**
+ * Context passed to all DataSource operations
+ * Contains internal state that should not be mixed with user query parameters
+ */
+interface BaseDataSourceContext {
+    /**
+     * Whether to filter to only published/complete content
+     * Set by site-builder: true for production, false for preview
+     */
+    publishedOnly?: boolean;
+    /**
+     * Scoped entity service that auto-applies publishedOnly filter
+     * Datasources should use this instead of their injected entityService
+     * to ensure consistent filtering behavior across environments
+     */
+    entityService: EntityService;
+}
+/**
+ * DataSource Interface
+ *
+ * Provides data for templates through fetch, generate, or transform operations.
+ * DataSources are registered in the DataSourceRegistry and referenced by templates
+ * via their dataSourceId property.
+ */
+interface DataSource {
+    /**
+     * Unique identifier for this data source
+     */
+    id: string;
+    /**
+     * Human-readable name for this data source
+     */
+    name: string;
+    /**
+     * Optional description of what this data source provides
+     */
+    description?: string;
+    /**
+     * Optional: Fetch existing data
+     * Used by data sources that aggregate or retrieve data (e.g., dashboard stats, API data)
+     * DataSources validate output using the provided schema
+     * @param query - Query parameters for fetching data
+     * @param outputSchema - Schema for validating output data
+     * @param context - Context with environment
+     */
+    fetch?: <T>(query: unknown, outputSchema: z.ZodSchema<T>, context: BaseDataSourceContext) => Promise<T>;
+    /**
+     * Optional: Generate new content
+     * Used by data sources that create content (e.g., AI-generated content, reports)
+     */
+    generate?: <T>(request: unknown, schema: z.ZodSchema<T>) => Promise<T>;
+    /**
+     * Optional: Transform content between formats
+     * Used by data sources that convert content (e.g., markdown to HTML, data formatting)
+     */
+    transform?: <T>(content: unknown, format: string, schema: z.ZodSchema<T>) => Promise<T>;
+}
+
+declare const ChatContextSchema: z.ZodObject<{
+    userPermissionLevel: z.ZodOptional<z.ZodEnum<["public", "trusted", "anchor"]>>;
+    interfaceType: z.ZodOptional<z.ZodString>;
+    channelId: z.ZodOptional<z.ZodString>;
+    channelName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    userPermissionLevel?: "public" | "trusted" | "anchor" | undefined;
+    interfaceType?: string | undefined;
+    channelId?: string | undefined;
+    channelName?: string | undefined;
+}, {
+    userPermissionLevel?: "public" | "trusted" | "anchor" | undefined;
+    interfaceType?: string | undefined;
+    channelId?: string | undefined;
+    channelName?: string | undefined;
+}>;
+type ChatContext = z.infer<typeof ChatContextSchema>;
+declare const PendingConfirmationSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    description: z.ZodString;
+    args: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    description: string;
+    args?: unknown;
+}, {
+    toolName: string;
+    description: string;
+    args?: unknown;
+}>;
+type PendingConfirmation = z.infer<typeof PendingConfirmationSchema>;
+declare const ToolResultDataSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    jobId: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    toolName: string;
+    args?: Record<string, unknown> | undefined;
+    jobId?: string | undefined;
+    data?: unknown;
+}, {
+    toolName: string;
+    args?: Record<string, unknown> | undefined;
+    jobId?: string | undefined;
+    data?: unknown;
+}>;
+type ToolResultData = z.infer<typeof ToolResultDataSchema>;
+declare const AgentResponseSchema: z.ZodObject<{
+    text: z.ZodString;
+    toolResults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        toolName: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        jobId: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        toolName: string;
+        args?: Record<string, unknown> | undefined;
+        jobId?: string | undefined;
+        data?: unknown;
+    }, {
+        toolName: string;
+        args?: Record<string, unknown> | undefined;
+        jobId?: string | undefined;
+        data?: unknown;
+    }>, "many">>;
+    pendingConfirmation: z.ZodOptional<z.ZodObject<{
+        toolName: z.ZodString;
+        description: z.ZodString;
+        args: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        toolName: string;
+        description: string;
+        args?: unknown;
+    }, {
+        toolName: string;
+        description: string;
+        args?: unknown;
+    }>>;
+    usage: z.ZodObject<{
+        promptTokens: z.ZodNumber;
+        completionTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }, {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    toolResults?: {
+        toolName: string;
+        args?: Record<string, unknown> | undefined;
+        jobId?: string | undefined;
+        data?: unknown;
+    }[] | undefined;
+    pendingConfirmation?: {
+        toolName: string;
+        description: string;
+        args?: unknown;
+    } | undefined;
+}, {
+    text: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    toolResults?: {
+        toolName: string;
+        args?: Record<string, unknown> | undefined;
+        jobId?: string | undefined;
+        data?: unknown;
+    }[] | undefined;
+    pendingConfirmation?: {
+        toolName: string;
+        description: string;
+        args?: unknown;
+    } | undefined;
+}>;
+type AgentResponse = z.infer<typeof AgentResponseSchema>;
+interface AgentNamespace {
+    chat(message: string, conversationId: string, context?: ChatContext): Promise<AgentResponse>;
+    confirmPendingAction(conversationId: string, confirmed: boolean): Promise<AgentResponse>;
+    invalidate(): void;
+}
+
+declare const AppInfoSchema: z.ZodObject<{
+    model: z.ZodString;
+    version: z.ZodString;
+    uptime: z.ZodNumber;
+    entities: z.ZodNumber;
+    embeddings: z.ZodNumber;
+    ai: z.ZodObject<{
+        model: z.ZodString;
+        embeddingModel: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        embeddingModel: string;
+    }, {
+        model: string;
+        embeddingModel: string;
+    }>;
+    daemons: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        pluginId: z.ZodString;
+        status: z.ZodString;
+        health: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<["healthy", "warning", "error", "unknown"]>;
+            message: z.ZodOptional<z.ZodString>;
+            lastCheck: z.ZodOptional<z.ZodString>;
+            details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        }, {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        status: string;
+        name: string;
+        pluginId: string;
+        health?: {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        } | undefined;
+    }, {
+        status: string;
+        name: string;
+        pluginId: string;
+        health?: {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>, "many">;
+    endpoints: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+        pluginId: z.ZodString;
+        priority: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        pluginId: string;
+        label: string;
+        url: string;
+        priority: number;
+    }, {
+        pluginId: string;
+        label: string;
+        url: string;
+        priority: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    version: string;
+    uptime: number;
+    entities: number;
+    embeddings: number;
+    ai: {
+        model: string;
+        embeddingModel: string;
+    };
+    daemons: {
+        status: string;
+        name: string;
+        pluginId: string;
+        health?: {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[];
+    endpoints: {
+        pluginId: string;
+        label: string;
+        url: string;
+        priority: number;
+    }[];
+}, {
+    model: string;
+    version: string;
+    uptime: number;
+    entities: number;
+    embeddings: number;
+    ai: {
+        model: string;
+        embeddingModel: string;
+    };
+    daemons: {
+        status: string;
+        name: string;
+        pluginId: string;
+        health?: {
+            status: "unknown" | "healthy" | "warning" | "error";
+            message?: string | undefined;
+            lastCheck?: string | undefined;
+            details?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[];
+    endpoints: {
+        pluginId: string;
+        label: string;
+        url: string;
+        priority: number;
+    }[];
+}>;
+type AppInfo = z.infer<typeof AppInfoSchema>;
+
+declare const ConversationSchema: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    interfaceType: z.ZodString;
+    channelId: z.ZodString;
+    channelName: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodString;
+    lastActiveAt: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    interfaceType: string;
+    channelId: string;
+    id: string;
+    sessionId: string;
+    startedAt: string;
+    lastActiveAt: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata: Record<string, unknown>;
+    channelName?: string | undefined;
+}, {
+    interfaceType: string;
+    channelId: string;
+    id: string;
+    sessionId: string;
+    startedAt: string;
+    lastActiveAt: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata: Record<string, unknown>;
+    channelName?: string | undefined;
+}>;
+type Conversation = z.infer<typeof ConversationSchema>;
+declare const messageRoleSchema: z.ZodEnum<["user", "assistant", "system"]>;
+type MessageRole = z.infer<typeof messageRoleSchema>;
+declare const MessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    conversationId: z.ZodString;
+    role: z.ZodEnum<["user", "assistant", "system"]>;
+    content: z.ZodString;
+    timestamp: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    metadata: Record<string, unknown>;
+    conversationId: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: string;
+}, {
+    id: string;
+    metadata: Record<string, unknown>;
+    conversationId: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: string;
+}>;
+type Message = z.infer<typeof MessageSchema>;
+
+declare const BrainCharacterSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodString;
+    purpose: z.ZodString;
+    values: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    values: string[];
+    name: string;
+    role: string;
+    purpose: string;
+}, {
+    values: string[];
+    name: string;
+    role: string;
+    purpose: string;
+}>;
+type BrainCharacter = z.infer<typeof BrainCharacterSchema>;
+declare const AnchorProfileSchema: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<["professional", "team", "collective"]>;
+    organization: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodOptional<z.ZodString>;
+    website: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    socialLinks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        platform: z.ZodEnum<["github", "instagram", "linkedin", "email", "website"]>;
+        url: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        platform: "website" | "email" | "github" | "instagram" | "linkedin";
+        label?: string | undefined;
+    }, {
+        url: string;
+        platform: "website" | "email" | "github" | "instagram" | "linkedin";
+        label?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    kind: "professional" | "team" | "collective";
+    description?: string | undefined;
+    organization?: string | undefined;
+    avatar?: string | undefined;
+    website?: string | undefined;
+    email?: string | undefined;
+    socialLinks?: {
+        url: string;
+        platform: "website" | "email" | "github" | "instagram" | "linkedin";
+        label?: string | undefined;
+    }[] | undefined;
+}, {
+    name: string;
+    kind: "professional" | "team" | "collective";
+    description?: string | undefined;
+    organization?: string | undefined;
+    avatar?: string | undefined;
+    website?: string | undefined;
+    email?: string | undefined;
+    socialLinks?: {
+        url: string;
+        platform: "website" | "email" | "github" | "instagram" | "linkedin";
+        label?: string | undefined;
+    }[] | undefined;
+}>;
+type AnchorProfile = z.infer<typeof AnchorProfileSchema>;
+
+declare const MessageResponseSchema: z.ZodUnion<[z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    data?: unknown;
+    error?: string | undefined;
+}, {
+    success: boolean;
+    data?: unknown;
+    error?: string | undefined;
+}>, z.ZodObject<{
+    noop: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    noop: true;
+}, {
+    noop: true;
+}>]>;
+type MessageResponse<T = unknown> = ({
+    success: boolean;
+    error?: string | undefined;
+} & {
+    data?: T | undefined;
+}) | {
+    noop: true;
+};
+declare const BaseMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodString;
+    source: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    timestamp: string;
+    source: string;
+    metadata?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+}, {
+    type: string;
+    id: string;
+    timestamp: string;
+    source: string;
+    metadata?: Record<string, unknown> | undefined;
+    target?: string | undefined;
+}>;
+type BaseMessage = z.infer<typeof BaseMessageSchema>;
+type MessageWithPayload<T = unknown> = BaseMessage & {
+    payload: T;
+};
+interface MessageSendOptions {
+    broadcast?: boolean;
+}
+type MessageSender<T = unknown, R = unknown> = (type: string, payload: T, options?: MessageSendOptions) => Promise<MessageResponse<R>>;
+interface MessageContext {
+    userId?: string;
+    channelId?: string;
+    messageId?: string;
+    timestamp?: string;
+    interfaceType?: string;
+    userPermissionLevel?: "public" | "trusted" | "anchor";
+    threadId?: string;
+}
+
+type PluginConfig = Record<string, unknown>;
+type PluginConfigInput<T extends z.ZodTypeAny> = z.input<T>;
+interface Plugin {
+    readonly id: string;
+    readonly version: string;
+    readonly type: "core" | "entity" | "service" | "interface";
+    readonly packageName: string;
+    readonly description?: string;
+    readonly dependencies?: string[];
+    ready?(): Promise<void>;
+    shutdown?(): Promise<void>;
+    requiresDaemonStartup?(): boolean;
+}
+type PluginFactory = (config: PluginConfig) => Plugin | Plugin[];
+interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    child(context: string): Logger;
+}
+interface ToolContext {
+    progressToken?: string | number;
+    sendProgress?: (notification: {
+        progress?: number;
+        total?: number;
+        message?: string;
+    }) => Promise<void>;
+    interfaceType?: string;
+    userId?: string;
+    channelId?: string;
+    channelName?: string;
+}
+interface ToolResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+type ToolVisibility = "public" | "trusted" | "anchor";
+interface ToolConfirmation {
+    required: boolean;
+    message?: string;
+}
+interface Tool<TArgs = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (args: TArgs, context: ToolContext) => Promise<TResult> | TResult;
+    visibility?: ToolVisibility;
+    confirmation?: ToolConfirmation;
+}
+interface Resource<TResult = unknown> {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    handler: () => Promise<TResult> | TResult;
+}
+interface ResourceTemplate<K extends string = string> {
+    uriTemplate: K;
+    name: string;
+    description?: string;
+    mimeType?: string;
+}
+interface Prompt {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+declare function createTool<TArgs = unknown, TResult = unknown>(tool: Tool<TArgs, TResult>): Tool<TArgs, TResult>;
+declare function createResource<TResult = unknown>(resource: Resource<TResult>): Resource<TResult>;
+declare function toolSuccess<T = unknown>(data?: T): ToolResponse<T>;
+declare function toolError(error: string): ToolResponse<never>;
+interface BaseJobTrackingInfo {
+    rootJobId: string;
+}
+interface MessageJobTrackingInfo extends BaseJobTrackingInfo {
+    messageId?: string;
+    channelId?: string;
+}
+type JobProgressStatus = "pending" | "processing" | "completed" | "failed";
+interface JobProgressContext {
+    rootJobId: string;
+    operationType: "file_operations" | "content_operations" | "data_processing" | "batch_processing";
+    pluginId?: string | undefined;
+    progressToken?: string | number | undefined;
+    operationTarget?: string | undefined;
+    interfaceType?: string | undefined;
+    channelId?: string | undefined;
+}
+interface JobProgressEvent {
+    id: string;
+    type: "job" | "batch";
+    status: JobProgressStatus;
+    message?: string | undefined;
+    progress?: {
+        current: number;
+        total: number;
+        percentage: number;
+    } | undefined;
+    aggregationKey?: string | undefined;
+    batchDetails?: {
+        totalOperations: number;
+        completedOperations: number;
+        failedOperations: number;
+        currentOperation?: string | undefined;
+        errors?: string[] | undefined;
+    } | undefined;
+    jobDetails?: {
+        jobType: string;
+        priority: number;
+        retryCount: number;
+    } | undefined;
+    metadata: JobProgressContext;
+}
+declare const urlCaptureConfigSchema: z.ZodObject<{
+    captureUrls: z.ZodDefault<z.ZodBoolean>;
+    blockedUrlDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    captureUrls: boolean;
+    blockedUrlDomains: string[];
+}, {
+    captureUrls?: boolean | undefined;
+    blockedUrlDomains?: string[] | undefined;
+}>;
+interface Channel<TPayload, TResponse = unknown> {
+    readonly name: string;
+    readonly schema: z.ZodType<TPayload>;
+    readonly _response?: TResponse;
+}
+declare function defineChannel<TPayload, TResponse = unknown>(name: string, schema: z.ZodType<TPayload>): Channel<TPayload, TResponse>;
+interface IEntityService {
+    getEntity<T = unknown>(entityType: string, id: string): Promise<T | null>;
+    listEntities<T = unknown>(type: string, options?: unknown): Promise<T[]>;
+    search<T = unknown>(query: string, options?: unknown): Promise<T[]>;
+    getEntityTypes(): string[];
+    hasEntityType(type: string): boolean;
+    countEntities(entityType: string, options?: unknown): Promise<number>;
+    getEntityCounts(): Promise<Array<{
+        entityType: string;
+        count: number;
+    }>>;
+}
+interface IIdentityNamespace {
+    get: () => BrainCharacter;
+    getProfile: () => AnchorProfile;
+    getAppInfo: () => Promise<AppInfo>;
+}
+interface IConversationsNamespace {
+    get(conversationId: string): Promise<Conversation | null>;
+    search(query: string): Promise<Conversation[]>;
+    list(options?: {
+        limit?: number;
+        updatedAfter?: string;
+    }): Promise<Conversation[]>;
+    getMessages(conversationId: string, options?: {
+        limit?: number;
+        range?: {
+            start: number;
+            end: number;
+        };
+    }): Promise<Message[]>;
+}
+interface IMessagingNamespace {
+    send: MessageSender;
+    subscribe<T = unknown, R = unknown>(channel: string | Channel<T, R>, handler: (message: MessageWithPayload<T>) => Promise<MessageResponse<R>>): () => void;
+}
+type EvalHandler<TInput = unknown, TOutput = unknown> = (input: TInput) => Promise<TOutput>;
+type InsightHandler = (entityService: IEntityService) => Promise<Record<string, unknown>>;
+interface IEvalNamespace {
+    registerHandler<TInput = unknown, TOutput = unknown>(handlerId: string, handler: EvalHandler<TInput, TOutput>): void;
+}
+interface IInsightsNamespace {
+    register(type: string, handler: InsightHandler): void;
+}
+interface BasePluginContext {
+    readonly pluginId: string;
+    readonly logger: Logger;
+    readonly dataDir: string;
+    readonly domain: string | undefined;
+    readonly siteUrl: string | undefined;
+    readonly previewUrl: string | undefined;
+    readonly appInfo: () => Promise<AppInfo>;
+    readonly entityService: IEntityService;
+    readonly identity: IIdentityNamespace;
+    readonly messaging: IMessagingNamespace;
+    readonly conversations: IConversationsNamespace;
+    readonly eval: IEvalNamespace;
+    readonly insights: IInsightsNamespace;
+}
+interface IEntitiesNamespace {
+    register<TEntity extends BaseEntity>(entityType: string, schema: z.ZodSchema<TEntity>, adapter: EntityAdapter<TEntity>, config?: EntityTypeConfig): void;
+    getAdapter<TEntity extends BaseEntity>(entityType: string): EntityAdapter<TEntity> | undefined;
+    update<TEntity extends BaseEntity>(entity: TEntity): Promise<{
+        entityId: string;
+        jobId: string;
+    }>;
+    registerDataSource(dataSource: DataSource): void;
+    registerCreateInterceptor(entityType: string, interceptor: (input: CreateInput, executionContext: CreateExecutionContext) => Promise<CreateInterceptionResult>): void;
+}
+interface IPromptsNamespace {
+    resolve(target: string, fallback: string): Promise<string>;
+}
+interface IServiceTemplatesNamespace {
+    register(templates: unknown): void;
+}
+interface IViewsNamespace {
+    register(views: unknown): void;
+}
+interface ServicePluginContext extends BasePluginContext {
+    readonly entities: IEntitiesNamespace;
+    readonly templates: IServiceTemplatesNamespace;
+    readonly views: IViewsNamespace;
+    readonly prompts: IPromptsNamespace;
+    registerInstructions(instructions: string): void;
+}
+interface EntityPluginContext extends BasePluginContext {
+    readonly entities: IEntitiesNamespace;
+    readonly prompts: IPromptsNamespace;
+}
+interface InterfacePluginContext extends BasePluginContext {
+    readonly agent: AgentNamespace;
+}
+
+declare abstract class EntityPlugin<TEntity extends BaseEntity = BaseEntity, TConfig = unknown> implements Plugin {
+    readonly type: "entity";
+    readonly id: string;
+    readonly version: string;
+    readonly packageName: string;
+    readonly description?: string;
+    abstract readonly entityType: string;
+    abstract readonly schema: z.ZodSchema<TEntity>;
+    abstract readonly adapter: EntityAdapter<TEntity>;
+    private readonly delegate;
+    protected constructor(id: string, packageJson: {
+        name: string;
+        version: string;
+        description?: string;
+    }, config: Partial<TConfig>, configSchema: z.ZodTypeAny);
+    protected onRegister(_context: EntityPluginContext): Promise<void>;
+    protected onReady(_context: EntityPluginContext): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    protected getInstructions(): Promise<string | undefined>;
+    protected getEntityTypeConfig(): EntityTypeConfig | undefined;
+    protected getDataSources(): DataSource[];
+    protected interceptCreate(input: CreateInput, _executionContext: CreateExecutionContext, _context: EntityPluginContext): Promise<CreateInterceptionResult>;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+declare const WebRouteMethods: readonly ["GET", "POST", "PUT", "DELETE", "OPTIONS"];
+type WebRouteMethod = (typeof WebRouteMethods)[number];
+type WebRouteHandler = (request: Request) => Response | Promise<Response>;
+interface WebRouteDefinition {
+    /** Absolute mounted path (e.g. "/cms" or "/cms-config") */
+    path: string;
+    /** HTTP method */
+    method?: WebRouteMethod;
+    /** Allow unauthenticated access */
+    public?: boolean;
+    /** Request handler */
+    handler: WebRouteHandler;
+}
+
+declare abstract class InterfacePlugin<TConfig = unknown, TTrackingInfo extends BaseJobTrackingInfo = BaseJobTrackingInfo> implements Plugin {
+    readonly type: "interface";
+    readonly id: string;
+    readonly version: string;
+    readonly packageName: string;
+    readonly description?: string;
+    private readonly delegate;
+    protected constructor(id: string, packageJson: {
+        name: string;
+        version: string;
+        description?: string;
+    }, config: Partial<TConfig>, configSchema: z.ZodTypeAny);
+    protected onRegister(_context: InterfacePluginContext): Promise<void>;
+    protected onReady(_context: InterfacePluginContext): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    protected getTools(): Promise<Tool[]>;
+    protected getResources(): Promise<Resource[]>;
+    protected getInstructions(): Promise<string | undefined>;
+    getWebRoutes(): WebRouteDefinition[];
+    requiresDaemonStartup(): boolean;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+declare abstract class MessageInterfacePlugin<TConfig = unknown, TTrackingInfo extends MessageJobTrackingInfo = MessageJobTrackingInfo> extends InterfacePlugin<TConfig, TTrackingInfo> {
+    private readonly messageDelegate;
+    protected constructor(id: string, packageJson: {
+        name: string;
+        version: string;
+        description?: string;
+    }, config: Partial<TConfig>, configSchema: z.ZodTypeAny);
+    protected abstract sendMessageToChannel(channelId: string | null, message: string): void;
+    protected onRegister(_context: InterfacePluginContext): Promise<void>;
+    protected onReady(_context: InterfacePluginContext): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    protected getTools(): Promise<Tool[]>;
+    protected getResources(): Promise<Resource[]>;
+    protected getInstructions(): Promise<string | undefined>;
+    protected sendMessageWithId(_channelId: string | null, _message: string): Promise<string | undefined>;
+    protected editMessage(_channelId: string, _messageId: string, _newMessage: string): Promise<boolean>;
+    protected supportsMessageEditing(): boolean;
+    protected onProgressUpdate(_event: JobProgressEvent): Promise<void>;
+    protected trackAgentResponseForJob(jobId: string, messageId: string, channelId: string): void;
+    registerProgressCallback(callback: (events: JobProgressEvent[]) => void): void;
+    unregisterProgressCallback(): void;
+    getProgressEvents(): JobProgressEvent[];
+    getActiveProgressEvents(): JobProgressEvent[];
+    startProcessingInput(channelId?: string | null): void;
+    endProcessingInput(): void;
+    protected getCurrentChannelId(): string | null;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+declare abstract class ServicePlugin<TConfig = unknown> implements Plugin {
+    readonly type: "service";
+    readonly id: string;
+    readonly version: string;
+    readonly packageName: string;
+    readonly description?: string;
+    private readonly delegate;
+    protected constructor(id: string, packageJson: {
+        name: string;
+        version: string;
+        description?: string;
+    }, config: Partial<TConfig>, configSchema: z.ZodTypeAny);
+    protected onRegister(_context: ServicePluginContext): Promise<void>;
+    protected onReady(_context: ServicePluginContext): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    protected getTools(): Promise<Tool[]>;
+    protected getResources(): Promise<Resource[]>;
+    protected getInstructions(): Promise<string | undefined>;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Best-effort extension metadata carried across public DTO boundaries.
+ *
+ * Individual keys are not stable public API. When a metadata value becomes a
+ * documented contract, hoist it to a typed top-level field on the owning DTO
+ * schema and keep this bag only as optional extension data.
+ */
+declare const ExtensionMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+type ExtensionMetadata = z.infer<typeof ExtensionMetadataSchema>;
+
+export { AgentResponseSchema, AnchorProfileSchema, AppInfoSchema, BaseMessageSchema, BrainCharacterSchema, ChatContextSchema, ConversationSchema, EntityPlugin, ExtensionMetadataSchema, InterfacePlugin, MessageInterfacePlugin, MessageResponseSchema, MessageSchema, PendingConfirmationSchema, ServicePlugin, ToolResultDataSchema, createResource, createTool, defineChannel, toolError, toolSuccess, urlCaptureConfigSchema };
+export type { AgentNamespace, AgentResponse, AnchorProfile, AppInfo, BaseJobTrackingInfo, BaseMessage, BasePluginContext, BrainCharacter, Channel, ChatContext, Conversation, EntityPluginContext, ExtensionMetadata, IConversationsNamespace, IEntitiesNamespace, IEvalNamespace, IIdentityNamespace, IInsightsNamespace, IMessagingNamespace, IPromptsNamespace, IServiceTemplatesNamespace, IViewsNamespace, InterfacePluginContext, JobProgressContext, JobProgressEvent, JobProgressStatus, Message, MessageContext, MessageJobTrackingInfo, MessageResponse, MessageRole, MessageSendOptions, MessageSender, MessageWithPayload, PendingConfirmation, Plugin, PluginConfig, PluginConfigInput, PluginFactory, Prompt, Resource, ResourceTemplate, ServicePluginContext, Tool, ToolConfirmation, ToolContext, ToolResponse, ToolResultData, ToolVisibility };