/**
 * Agent Role Definition Types
 *
 * This module defines the types for agent role definitions, which store
 * system prompts and behavioral configurations for agents.
 *
 * Role definitions allow agents to be configured with:
 * - System prompts stored as Documents
 * - Behavioral hooks for startup, task assignment, and stuck scenarios
 *
 * The system prompt is stored as a Document element, allowing versioning
 * and easy editing. The role definition references this document via its ID.
 */
import type { DocumentId, EntityId, Timestamp, ElementId } from '@stoneforge/core';
import type { AgentRole, WorkerMode, StewardFocus } from './agent.js';
/**
 * Behavioral hooks for agents - scripts or prompts to execute on specific events
 */
export interface AgentBehaviors {
    /**
     * Instruction/prompt fragment appended to the agent's context on startup.
     * This can include workspace-specific context, conventions, or guidelines.
     */
    readonly onStartup?: string;
    /**
     * Instruction/prompt fragment appended when a task is assigned to the agent.
     * Can include task-specific guidelines or workflow requirements.
     */
    readonly onTaskAssigned?: string;
    /**
     * Instruction/prompt fragment appended when the agent appears stuck
     * (detected by monitoring). Can include debugging hints or escalation paths.
     */
    readonly onStuck?: string;
    /**
     * Instruction/prompt fragment appended before the agent creates a handoff.
     * Can include guidelines for context preservation.
     */
    readonly onHandoff?: string;
    /**
     * Instruction/prompt fragment for handling errors or failures.
     */
    readonly onError?: string;
}
/**
 * Base interface for all role definitions
 */
export interface BaseRoleDefinition {
    /**
     * The role type this definition applies to
     */
    readonly role: AgentRole;
    /**
     * Human-readable name for this role definition (e.g., "Default Director", "Frontend Worker")
     */
    readonly name: string;
    /**
     * Optional description of this role definition
     */
    readonly description?: string;
    /**
     * Reference to the Document containing the system prompt for this role.
     * The document should contain the full system prompt text.
     */
    readonly systemPromptRef: DocumentId;
    /**
     * Maximum number of concurrent tasks for agents using this role.
     * Default is 1.
     */
    readonly maxConcurrentTasks?: number;
    /**
     * Behavioral hooks - prompts/instructions for specific events
     */
    readonly behaviors?: AgentBehaviors;
    /**
     * Optional tags for categorization
     */
    readonly tags?: readonly string[];
    /**
     * When this role definition was created
     */
    readonly createdAt: Timestamp;
    /**
     * Who created this role definition
     */
    readonly createdBy: EntityId;
    /**
     * When this role definition was last updated
     */
    readonly updatedAt: Timestamp;
}
/**
 * Director-specific role definition
 */
export interface DirectorRoleDefinition extends BaseRoleDefinition {
    readonly role: 'director';
}
/**
 * Worker-specific role definition
 */
export interface WorkerRoleDefinition extends BaseRoleDefinition {
    readonly role: 'worker';
    /**
     * The worker mode this definition is designed for.
     * If not specified, applies to both ephemeral and persistent workers.
     */
    readonly workerMode?: WorkerMode;
}
/**
 * Steward-specific role definition
 */
export interface StewardRoleDefinition extends BaseRoleDefinition {
    readonly role: 'steward';
    /**
     * The steward focus area this definition is designed for.
     * If not specified, applies to all steward types.
     */
    readonly stewardFocus?: StewardFocus;
}
/**
 * Union type for all role definitions
 */
export type AgentRoleDefinition = DirectorRoleDefinition | WorkerRoleDefinition | StewardRoleDefinition;
/**
 * Input for creating a role definition
 */
export interface CreateRoleDefinitionInput {
    /**
     * The role type this definition applies to
     */
    readonly role: AgentRole;
    /**
     * Human-readable name for this role definition
     */
    readonly name: string;
    /**
     * Optional description
     */
    readonly description?: string;
    /**
     * The system prompt content (will be stored as a Document)
     */
    readonly systemPrompt: string;
    /**
     * Maximum number of concurrent tasks (default: 1)
     */
    readonly maxConcurrentTasks?: number;
    /**
     * Behavioral hooks
     */
    readonly behaviors?: AgentBehaviors;
    /**
     * Optional tags
     */
    readonly tags?: string[];
    /**
     * Who is creating this definition
     */
    readonly createdBy: EntityId;
    /**
     * For workers: the specific worker mode this applies to
     */
    readonly workerMode?: WorkerMode;
    /**
     * For stewards: the specific steward focus this applies to
     */
    readonly stewardFocus?: StewardFocus;
}
/**
 * Input for updating a role definition
 */
export interface UpdateRoleDefinitionInput {
    /**
     * New name
     */
    readonly name?: string;
    /**
     * New description
     */
    readonly description?: string;
    /**
     * New system prompt content (will create new Document version)
     */
    readonly systemPrompt?: string;
    /**
     * Updated max concurrent tasks
     */
    readonly maxConcurrentTasks?: number;
    /**
     * Updated behaviors (merged with existing)
     */
    readonly behaviors?: Partial<AgentBehaviors>;
    /**
     * New tags (replaces existing)
     */
    readonly tags?: string[];
}
/**
 * A role definition as stored in the database.
 * Role definitions are stored as Documents with JSON content type.
 */
export interface StoredRoleDefinition {
    /**
     * The element ID of the Document storing this role definition
     */
    readonly id: ElementId;
    /**
     * The role definition data
     */
    readonly definition: AgentRoleDefinition;
}
/**
 * Type guard for AgentBehaviors
 */
export declare function isAgentBehaviors(value: unknown): value is AgentBehaviors;
/**
 * Type guard for DirectorRoleDefinition
 */
export declare function isDirectorRoleDefinition(value: unknown): value is DirectorRoleDefinition;
/**
 * Type guard for WorkerRoleDefinition
 */
export declare function isWorkerRoleDefinition(value: unknown): value is WorkerRoleDefinition;
/**
 * Type guard for StewardRoleDefinition
 */
export declare function isStewardRoleDefinition(value: unknown): value is StewardRoleDefinition;
/**
 * Type guard for any AgentRoleDefinition
 */
export declare function isAgentRoleDefinition(value: unknown): value is AgentRoleDefinition;
/**
 * Filter options for querying role definitions
 */
export interface RoleDefinitionFilter {
    /**
     * Filter by role type
     */
    readonly role?: AgentRole;
    /**
     * Filter by worker mode (only applies when role is 'worker')
     */
    readonly workerMode?: WorkerMode;
    /**
     * Filter by steward focus (only applies when role is 'steward')
     */
    readonly stewardFocus?: StewardFocus;
    /**
     * Filter by tags (must have ALL specified tags)
     */
    readonly tags?: readonly string[];
    /**
     * Filter by name (partial match, case-insensitive)
     */
    readonly nameContains?: string;
}
/**
 * Tags used to identify role definition documents
 */
export declare const ROLE_DEFINITION_TAGS: {
    /** Main tag for all role definition documents */
    readonly ROLE_DEFINITION: "role-definition";
    /** Tag prefix for role type (e.g., 'role:director') */
    readonly ROLE_PREFIX: "role:";
    /** Tag prefix for agent prompt documents */
    readonly AGENT_PROMPT: "agent-prompt";
};
/**
 * Generates tags for a role definition document
 */
export declare function generateRoleDefinitionTags(role: AgentRole, additionalTags?: string[]): string[];
//# sourceMappingURL=role-definition.d.ts.map