@rizom/brain 0.2.0-alpha.62 → 0.2.0-alpha.63

package/dist/plugins.d.ts

@@ -1,5 +1,63 @@
 import { z } from 'zod';
 
+/**
+ * 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>;
+}
+
 /**
  * Options for entity mutation operations (create, update, upsert)
  */
@@ -116,6 +174,7 @@ type CreateInterceptionResult = {
     kind: "continue";
     input: CreateInput;
 };
+type CreateInterceptor = (input: CreateInput, executionContext: CreateExecutionContext) => Promise<CreateInterceptionResult>;
 /**
  * Interface for entity adapter - handles conversion between entities and markdown
  * following the hybrid storage model
@@ -192,21 +251,24 @@ interface EntityTypeConfig {
     /** 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;
+    /** Whether this entity type may be used as source material for derived projections (default: true).
+     *  Set to false for projection outputs that would create feedback loops. */
+    projectionSource?: boolean;
 }
 /**
  * Core entity service interface for read-only operations
  * Used by core plugins that need entity access but shouldn't modify entities
  */
-interface GetEntityRequest$1 {
+interface GetEntityRequest {
     entityType: string;
     id: string;
 }
-type GetEntityRawRequest = GetEntityRequest$1;
-interface ListEntitiesRequest$1 {
+type GetEntityRawRequest = GetEntityRequest;
+interface ListEntitiesRequest {
     entityType: string;
     options?: ListOptions | undefined;
 }
-interface CountEntitiesRequest$1 {
+interface CountEntitiesRequest {
     entityType: string;
     options?: Pick<ListOptions, "publishedOnly" | "filter"> | undefined;
 }
@@ -230,7 +292,7 @@ interface UpsertEntityRequest<T extends BaseEntity> {
     entity: T;
     options?: EntityJobOptions | undefined;
 }
-interface EntitySearchRequest$1 {
+interface EntitySearchRequest {
     query: string;
     options?: SearchOptions | undefined;
 }
@@ -238,27 +300,48 @@ interface SearchWithDistancesRequest {
     query: string;
 }
 interface ICoreEntityService {
-    getEntity<T extends BaseEntity>(request: GetEntityRequest$1): Promise<T | null>;
+    getEntity<T extends BaseEntity>(request: GetEntityRequest): Promise<T | null>;
     /**
      * Get entity without content resolution (raw)
      * Used internally to avoid recursion when resolving image references
      */
     getEntityRaw<T extends BaseEntity>(request: GetEntityRawRequest): Promise<T | null>;
-    listEntities<T extends BaseEntity>(request: ListEntitiesRequest$1): Promise<T[]>;
-    search<T extends BaseEntity = BaseEntity>(request: EntitySearchRequest$1): Promise<SearchResult<T>[]>;
+    listEntities<T extends BaseEntity>(request: ListEntitiesRequest): Promise<T[]>;
+    search<T extends BaseEntity = BaseEntity>(request: EntitySearchRequest): Promise<SearchResult<T>[]>;
     getEntityTypes(): string[];
     hasEntityType(type: string): boolean;
-    countEntities(request: CountEntitiesRequest$1): Promise<number>;
+    countEntities(request: CountEntitiesRequest): Promise<number>;
     getEntityCounts(): Promise<Array<{
         entityType: string;
         count: number;
     }>>;
+    /** Get configuration for a specific entity type */
+    getEntityTypeConfig(type: string): EntityTypeConfig;
     /** Get weight map for all registered entity types with non-default weights */
     getWeightMap(): Record<string, number>;
 }
 /**
  * Entity service interface for managing brain entities
  */
+interface IEntitiesNamespace {
+    /** Register a new entity type with schema and adapter */
+    register<TEntity extends BaseEntity>(entityType: string, schema: z.ZodSchema<TEntity>, adapter: EntityAdapter<TEntity>, config?: EntityTypeConfig): void;
+    /** Get the adapter for an entity type */
+    getAdapter<TEntity extends BaseEntity>(entityType: string): EntityAdapter<TEntity> | undefined;
+    /** Extend an adapter's frontmatterSchema with additional fields */
+    extendFrontmatterSchema(type: string, extension: z.ZodObject<z.ZodRawShape>): void;
+    /** Get effective frontmatter schema (base + extensions) for an entity type */
+    getEffectiveFrontmatterSchema(type: string): z.ZodObject<z.ZodRawShape> | undefined;
+    /** Update an existing entity */
+    update<TEntity extends BaseEntity>(entity: TEntity): Promise<{
+        entityId: string;
+        jobId: string;
+    }>;
+    /** Register a data source for dynamic content */
+    registerDataSource(dataSource: DataSource): void;
+    /** Register a create interceptor for this plugin's entity type */
+    registerCreateInterceptor(entityType: string, interceptor: CreateInterceptor): void;
+}
 interface EntityService extends ICoreEntityService {
     createEntity<T extends BaseEntity>(request: CreateEntityRequest<T>): Promise<EntityMutationResult>;
     createEntityFromMarkdown(request: CreateEntityFromMarkdownRequest): Promise<EntityMutationResult>;
@@ -284,78 +367,102 @@ interface EntityService extends ICoreEntityService {
 }
 
 /**
- * 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.
+ * User permission level schema
  */
-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 UserPermissionLevelSchema: z.ZodEnum<["anchor", "trusted", "public"]>;
+type UserPermissionLevel = z.infer<typeof UserPermissionLevelSchema>;
 
 declare const ChatContextSchema: z.ZodObject<{
-    userPermissionLevel: z.ZodOptional<z.ZodEnum<["public", "trusted", "anchor"]>>;
+    userPermissionLevel: z.ZodOptional<z.ZodEnum<["anchor", "trusted", "public"]>>;
     interfaceType: z.ZodOptional<z.ZodString>;
     channelId: z.ZodOptional<z.ZodString>;
     channelName: z.ZodOptional<z.ZodString>;
+    actor: z.ZodOptional<z.ZodObject<{
+        actorId: z.ZodString;
+        canonicalId: z.ZodOptional<z.ZodString>;
+        interfaceType: z.ZodString;
+        role: z.ZodEnum<["user", "assistant", "system"]>;
+        displayName: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        isBot: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        interfaceType: string;
+        actorId: string;
+        role: "user" | "assistant" | "system";
+        canonicalId?: string | undefined;
+        displayName?: string | undefined;
+        username?: string | undefined;
+        isBot?: boolean | undefined;
+    }, {
+        interfaceType: string;
+        actorId: string;
+        role: "user" | "assistant" | "system";
+        canonicalId?: string | undefined;
+        displayName?: string | undefined;
+        username?: string | undefined;
+        isBot?: boolean | undefined;
+    }>>;
+    source: z.ZodOptional<z.ZodObject<{
+        messageId: z.ZodOptional<z.ZodString>;
+        channelId: z.ZodOptional<z.ZodString>;
+        channelName: z.ZodOptional<z.ZodString>;
+        threadId: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        channelId?: string | undefined;
+        channelName?: string | undefined;
+        messageId?: string | undefined;
+        threadId?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        channelId?: string | undefined;
+        channelName?: string | undefined;
+        messageId?: string | undefined;
+        threadId?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    userPermissionLevel?: "public" | "trusted" | "anchor" | undefined;
+    userPermissionLevel?: "anchor" | "trusted" | "public" | undefined;
     interfaceType?: string | undefined;
     channelId?: string | undefined;
     channelName?: string | undefined;
+    actor?: {
+        interfaceType: string;
+        actorId: string;
+        role: "user" | "assistant" | "system";
+        canonicalId?: string | undefined;
+        displayName?: string | undefined;
+        username?: string | undefined;
+        isBot?: boolean | undefined;
+    } | undefined;
+    source?: {
+        channelId?: string | undefined;
+        channelName?: string | undefined;
+        messageId?: string | undefined;
+        threadId?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    } | undefined;
 }, {
-    userPermissionLevel?: "public" | "trusted" | "anchor" | undefined;
+    userPermissionLevel?: "anchor" | "trusted" | "public" | undefined;
     interfaceType?: string | undefined;
     channelId?: string | undefined;
     channelName?: string | undefined;
+    actor?: {
+        interfaceType: string;
+        actorId: string;
+        role: "user" | "assistant" | "system";
+        canonicalId?: string | undefined;
+        displayName?: string | undefined;
+        username?: string | undefined;
+        isBot?: boolean | undefined;
+    } | undefined;
+    source?: {
+        channelId?: string | undefined;
+        channelName?: string | undefined;
+        messageId?: string | undefined;
+        threadId?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    } | undefined;
 }>;
 type ChatContext = z.infer<typeof ChatContextSchema>;
 declare const PendingConfirmationSchema: z.ZodObject<{
@@ -621,24 +728,24 @@ declare const ConversationSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     interfaceType: string;
     channelId: string;
+    metadata: Record<string, unknown>;
     id: string;
     sessionId: string;
     startedAt: string;
     lastActiveAt: string;
     createdAt: string;
     updatedAt: string;
-    metadata: Record<string, unknown>;
     channelName?: string | undefined;
 }, {
     interfaceType: string;
     channelId: string;
+    metadata: Record<string, unknown>;
     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>;
@@ -652,17 +759,17 @@ declare const MessageSchema: z.ZodObject<{
     timestamp: z.ZodString;
     metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
+    role: "user" | "assistant" | "system";
     metadata: Record<string, unknown>;
+    id: string;
     conversationId: string;
-    role: "user" | "assistant" | "system";
     content: string;
     timestamp: string;
 }, {
-    id: string;
+    role: "user" | "assistant" | "system";
     metadata: Record<string, unknown>;
+    id: string;
     conversationId: string;
-    role: "user" | "assistant" | "system";
     content: string;
     timestamp: string;
 }>;
@@ -674,14 +781,14 @@ declare const BrainCharacterSchema: z.ZodObject<{
     purpose: z.ZodString;
     values: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
+    role: string;
     values: string[];
     name: string;
-    role: string;
     purpose: string;
 }, {
+    role: string;
     values: string[];
     name: string;
-    role: string;
     purpose: string;
 }>;
 type BrainCharacter = z.infer<typeof BrainCharacterSchema>;
@@ -781,16 +888,16 @@ declare const BaseMessageSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     type: string;
+    source: string;
     id: string;
     timestamp: string;
-    source: string;
     metadata?: Record<string, unknown> | undefined;
     target?: string | undefined;
 }, {
     type: string;
+    source: string;
     id: string;
     timestamp: string;
-    source: string;
     metadata?: Record<string, unknown> | undefined;
     target?: string | undefined;
 }>;
@@ -814,7 +921,7 @@ interface MessageContext {
     messageId?: string;
     timestamp?: string;
     interfaceType?: string;
-    userPermissionLevel?: "public" | "trusted" | "anchor";
+    userPermissionLevel?: UserPermissionLevel;
     threadId?: string;
 }
 
@@ -856,7 +963,7 @@ interface ToolResponse<T = unknown> {
     data?: T;
     error?: string;
 }
-type ToolVisibility = "public" | "trusted" | "anchor";
+type ToolVisibility = UserPermissionLevel;
 interface ToolConfirmation {
     required: boolean;
     message?: string;
@@ -953,34 +1060,9 @@ interface Channel<TPayload, TResponse = unknown> {
     readonly _response?: TResponse;
 }
 declare function defineChannel<TPayload, TResponse = unknown>(name: string, schema: z.ZodType<TPayload>): Channel<TPayload, TResponse>;
-interface GetEntityRequest {
-    entityType: string;
-    id: string;
-}
-interface ListEntitiesRequest {
-    entityType: string;
-    options?: unknown;
-}
-interface CountEntitiesRequest {
-    entityType: string;
-    options?: unknown;
-}
-interface EntitySearchRequest {
-    query: string;
-    options?: unknown;
-}
-interface IEntityService {
-    getEntity<T = unknown>(request: GetEntityRequest): Promise<T | null>;
-    listEntities<T = unknown>(request: ListEntitiesRequest): Promise<T[]>;
-    search<T = unknown>(request: EntitySearchRequest): Promise<T[]>;
-    getEntityTypes(): string[];
-    hasEntityType(type: string): boolean;
-    countEntities(request: CountEntitiesRequest): Promise<number>;
-    getEntityCounts(): Promise<Array<{
-        entityType: string;
-        count: number;
-    }>>;
-}
+type PublicEntityServiceMethods = "getEntity" | "listEntities" | "search" | "getEntityTypes" | "hasEntityType" | "countEntities" | "getEntityCounts" | "getEntityTypeConfig";
+type IEntityService = Pick<ICoreEntityService, PublicEntityServiceMethods>;
+
 interface IIdentityNamespace {
     get: () => BrainCharacter;
     getProfile: () => AnchorProfile;
@@ -1008,7 +1090,7 @@ interface IMessagingNamespace {
 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;
+    registerHandler(handlerId: string, handler: EvalHandler): void;
 }
 interface IInsightsNamespace {
     register(type: string, handler: InsightHandler): void;
@@ -1028,16 +1110,6 @@ interface BasePluginContext {
     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>;
 }
@@ -1045,7 +1117,11 @@ interface IServiceTemplatesNamespace {
     register(templates: unknown): void;
 }
 interface IViewsNamespace {
-    register(views: unknown): void;
+    get(name: string): unknown | undefined;
+    list(): unknown[];
+    hasRenderer(templateName: string): boolean;
+    getRenderer(templateName: string): unknown | undefined;
+    validate(templateName: string, content: unknown): boolean;
 }
 interface ServicePluginContext extends BasePluginContext {
     readonly entities: IEntitiesNamespace;
@@ -1192,4 +1268,4 @@ declare abstract class ServicePlugin<TConfig = unknown> implements Plugin {
 }
 
 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 };
+export type { AgentNamespace, AgentResponse, AnchorProfile, AppInfo, BaseJobTrackingInfo, BaseMessage, BasePluginContext, BrainCharacter, Channel, ChatContext, Conversation, EntityPluginContext, ExtensionMetadata, IConversationsNamespace, IEntitiesNamespace, IEntityService, 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 };