@dollhousemcp/mcp-server
Version:
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.
209 lines • 7.45 kB
TypeScript
/**
* Agent element implementation.
* Autonomous goal-oriented actors with decision-making capabilities.
*
* SECURITY MEASURES IMPLEMENTED:
* 1. Goal validation to prevent malicious objectives
* 2. Decision framework sandboxing
* 3. State size limits to prevent DoS
* 4. Risk assessment for damage prevention
* 5. Audit logging for all decisions and actions
*/
import { BaseElement } from '../BaseElement.js';
import { IElement, ElementValidationResult } from '../../types/elements/index.js';
import { MetadataService } from '../../services/MetadataService.js';
import { AgentGoal, AgentDecision, AgentState, AgentMetadata, SecurityValidationResult, ConstraintResult, RiskAssessmentResult, PriorityScoreResult, DecisionOutcome } from './types.js';
import { COMMIT_PERSISTED_VERSION } from './constants.js';
import { RuleEngineConfig } from './ruleEngineConfig.js';
export declare class Agent extends BaseElement implements IElement {
metadata: AgentMetadata;
private state;
private isDirtyState;
private ruleEngineConfig;
private _decisionHistory;
constructor(metadata: Partial<AgentMetadata>, metadataService: MetadataService);
/**
* Add a new goal with security validation
*
* @param goal - Goal configuration
* @param options - Optional configuration for strict validation mode
* @returns The created goal with any security warnings attached
*
* @since v2.0.0 - Security validation is advisory by default (Issue #112)
*/
addGoal(goal: Partial<AgentGoal>, options?: {
strict?: boolean;
}): AgentGoal;
/**
* Record a decision made by the LLM (or programmatic guardrail)
*
* This is NOT a decision-maker, it's a decision RECORDER.
* The LLM makes decisions, this method just persists them for audit trail.
*
* @since v2.0.0 - Agentic Loop Redesign
*/
recordDecision(decision: {
goalId: string;
decision: string;
reasoning: string;
confidence: number;
riskAssessment?: RiskAssessmentResult;
outcome?: DecisionOutcome;
}): AgentDecision;
/**
* Assess risk for a decision or action
*
* This is a CHECKLIST, not a decision maker. It flags known risk factors
* that the LLM should consider when making decisions.
*
* Similar to how GitHub flags "this file is large" or "this PR changes many files" -
* programmatic signals that inform semantic judgment.
*
* @since v2.0.0 - Refactored for LLM-first agentic loop
*/
assessRisk(action: string, goal: AgentGoal, context: Record<string, any>): RiskAssessmentResult;
/**
* Evaluate programmatic constraints on a goal
*
* Returns blocking constraints that MUST be satisfied before proceeding.
* The LLM can see these and decide how to handle them.
*
* @since v2.0.0 - Extracted from ruleBasedDecision for LLM-first agentic loop
*/
evaluateConstraints(goal: AgentGoal): ConstraintResult;
/**
* Calculate a programmatic "priority score" for a goal
*
* This is a simple heuristic the LLM can consider when prioritizing.
* The LLM is free to ignore this score if it has better judgment.
*
* @since v2.0.0 - Extracted from programmaticDecision for LLM-first agentic loop
*/
calculatePriorityScore(goal: AgentGoal): PriorityScoreResult;
/**
* Validate goal for security threats
*
* IMPORTANT: This is a FIRST LINE OF DEFENSE, not a replacement for LLM judgment.
* False positives are acceptable - this flags potential issues for LLM review.
*
* Think of this like a spam filter: it catches obvious bad content but
* the LLM still needs to make final judgment calls.
*
* @since v2.0.0 - Refactored to return warnings instead of throwing errors
* @since v2.0.0 - Made public for use in AgentManager.executeAgent()
*/
validateGoalSecurity(goal: string): SecurityValidationResult;
/**
* Commit persisted state version after successful save.
*
* This Symbol-keyed method provides runtime privacy - it can only be called
* by code that has access to the COMMIT_PERSISTED_VERSION symbol (i.e., AgentManager).
* External code cannot call this method without the Symbol.
*
* @param version - The new version number to set
* @see Issue #24 - Optimistic locking implementation
* @see Issue #123 - Option C pattern: version increments only on successful save
*/
[COMMIT_PERSISTED_VERSION](version: number): void;
/**
* Get agent state
*/
getState(): Readonly<AgentState>;
/**
* Update agent context
*/
updateContext(key: string, value: any): void;
/**
* Complete a goal
*/
completeGoal(goalId: string, outcome?: 'success' | 'failure' | 'partial'): void;
/**
* Detect dependency cycles in goal dependencies
* MEDIUM PRIORITY IMPROVEMENT: Prevents circular dependencies between goals
*/
private detectDependencyCycle;
/**
* Get goals by status
*/
getGoalsByStatus(status: AgentGoal['status']): AgentGoal[];
/**
* Get goals by quadrant
*/
getGoalsByQuadrant(quadrant: AgentGoal['eisenhowerQuadrant']): AgentGoal[];
/**
* Calculate agent performance metrics
* MEDIUM PRIORITY IMPROVEMENT: Enhanced to include decision timing metrics
*/
getPerformanceMetrics(): {
successRate: number;
averageCompletionTime: number;
goalsCompleted: number;
goalsInProgress: number;
decisionAccuracy: number;
averageDecisionTimeMs?: number;
averageFrameworkTimeMs?: number;
averageRiskAssessmentTimeMs?: number;
};
/**
* Validate the agent
*/
validate(): ElementValidationResult;
/**
* Serialize to JSON format for internal use and testing
*/
serializeToJSON(): string;
/**
* Get content for serialization
*/
protected getContent(): string;
/**
* Serialize agent to markdown format with YAML frontmatter
* FIX: Changed from JSON to markdown for GitHub portfolio compatibility
*/
serialize(): string;
/**
* Deserialize agent including state
*/
deserialize(data: string): void;
/**
* Agent activation
*/
activate(): Promise<void>;
/**
* Agent deactivation
*/
deactivate(): Promise<void>;
/**
* Check if agent needs state persistence
*/
needsStatePersistence(): boolean;
/**
* Mark state as persisted
*/
markStatePersisted(): void;
/**
* Create a goal from a template
* LOW PRIORITY IMPROVEMENT: Goal template system for common patterns
*/
addGoalFromTemplate(templateId: string, customFields: Record<string, any>): AgentGoal;
/**
* Get template recommendations based on goal description
*/
getGoalTemplateRecommendations(description: string): string[];
/**
* Validate a goal against its template
*/
validateGoalTemplate(goalId: string): {
valid: boolean;
errors: string[];
};
/**
* Update rule engine configuration
*/
updateRuleEngineConfig(config: Partial<RuleEngineConfig>): void;
/**
* Get current rule engine configuration
*/
getRuleEngineConfig(): Readonly<RuleEngineConfig>;
}
//# sourceMappingURL=Agent.d.ts.map