@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.
613 lines • 21.7 kB
TypeScript
/**
* Type definitions for Agent elements
*/
import { ElementType } from '../../portfolio/types.js';
import { IElementMetadata } from '../../types/elements/index.js';
import type { ElementGatekeeperPolicy } from '../../handlers/mcp-aql/GatekeeperTypes.js';
import { DecisionFramework, RiskTolerance, GoalPriority, GoalStatus, EisenhowerQuadrant, DecisionOutcome, RiskLevel } from './constants.js';
import type { SafetyTier as _SafetyTier, VerificationChallengeType as _VerificationChallengeType, SafetyConfig as _SafetyConfig, VerificationChallenge as _VerificationChallenge, ConfirmationRequest as _ConfirmationRequest, DangerZoneOperation as _DangerZoneOperation, ExecutionContext as _ExecutionContext, SafetyTierResult as _SafetyTierResult } from '@dollhousemcp/safety';
export type SafetyTier = _SafetyTier;
export type VerificationChallengeType = _VerificationChallengeType;
export type SafetyConfig = _SafetyConfig;
export type VerificationChallenge = _VerificationChallenge;
export type ConfirmationRequest = _ConfirmationRequest;
export type DangerZoneOperation = _DangerZoneOperation;
export type ExecutionContext = _ExecutionContext;
export type SafetyTierResult = _SafetyTierResult;
export declare const DEFAULT_SAFETY_CONFIG: _SafetyConfig;
export type { DecisionFramework, RiskTolerance, GoalPriority, GoalStatus, EisenhowerQuadrant, DecisionOutcome, RiskLevel } from './constants.js';
/**
* Agent goal structure
*/
export interface AgentGoal {
id: string;
description: string;
priority: GoalPriority;
status: GoalStatus;
importance: number;
urgency: number;
eisenhowerQuadrant?: EisenhowerQuadrant;
createdAt: Date;
updatedAt: Date;
completedAt?: Date;
dependencies?: string[];
riskLevel?: RiskLevel;
estimatedEffort?: number;
actualEffort?: number;
notes?: string;
/**
* Security warnings from goal validation (advisory, not blocking)
* Informs LLM of potential security concerns without preventing goal creation
* @since v2.0.0 - Advisory security pattern (Issue #112)
*/
securityWarnings?: string[];
}
/**
* Agent decision structure
*/
export interface AgentDecision {
id: string;
goalId: string;
timestamp: Date;
decision: string;
reasoning: string;
framework: DecisionFramework;
confidence: number;
riskAssessment: {
level: RiskLevel;
factors: string[];
mitigations?: string[];
};
outcome?: DecisionOutcome;
impact?: string;
performanceMetrics?: {
decisionTimeMs?: number;
frameworkTimeMs?: number;
riskAssessmentTimeMs?: number;
};
}
/**
* Agent state structure
*
* IMPROVEMENT: Added version field for optimistic locking (Issue #24)
*/
export interface AgentState {
goals: AgentGoal[];
decisions: AgentDecision[];
context: Record<string, any>;
lastActive: Date;
sessionCount: number;
successRate?: number;
averageDecisionTime?: number;
/**
* State version for optimistic locking
* Incremented on each state update to detect concurrent modifications
* @since Issue #24 - Medium Priority Fix
*/
stateVersion?: number;
}
/**
* Agent metadata extends base element metadata
*/
export interface AgentMetadata extends IElementMetadata {
type?: ElementType.AGENT;
decisionFramework?: DecisionFramework;
specializations?: string[];
riskTolerance?: RiskTolerance;
learningEnabled?: boolean;
maxConcurrentGoals?: number;
ruleEngineConfig?: any;
/**
* Action verbs that trigger this agent (e.g., "automate", "orchestrate", "delegate")
* Used by Enhanced Capability Index for intelligent agent suggestions
* @since v1.9.10
*/
triggers?: string[];
}
/**
* Performance metrics for agents
*/
export interface AgentPerformanceMetrics {
successRate: number;
averageCompletionTime: number;
goalsCompleted: number;
goalsInProgress: number;
decisionAccuracy: number;
}
/**
* Input structure for creating goals
*/
export interface AgentGoalInput {
description: string;
priority?: GoalPriority;
importance?: number;
urgency?: number;
dependencies?: string[];
riskLevel?: RiskLevel;
estimatedEffort?: number;
notes?: string;
}
/**
* Agent v2.0 goal configuration
*
* Defines a goal template with parameters that can be filled when executing
* the agent. This replaces freeform goal strings with structured templates.
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface AgentGoalConfig {
/** Goal template with {parameter} placeholders */
template: string;
/** Parameters that can be passed to fill the template */
parameters: AgentGoalParameter[];
/** Success criteria the LLM uses to determine goal completion */
successCriteria?: string[];
}
/**
* Parameter definition for goal templates
*/
export interface AgentGoalParameter {
name: string;
type: 'string' | 'number' | 'boolean';
required: boolean;
description?: string;
default?: string | number | boolean;
}
/**
* Agent v2.0 element activation configuration
*
* Defines which elements to activate when the agent executes.
* Element-agnostic: supports any current or future element type.
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface AgentActivates {
personas?: string[];
skills?: string[];
memories?: string[];
templates?: string[];
ensembles?: string[];
/** Extensible for future element types */
[key: string]: string[] | undefined;
}
/**
* Agent v2.0 tool configuration
*
* Specifies which MCP-AQL tool endpoints an agent is allowed or denied access to.
* Tool names follow the format `mcp_aql_{endpoint}` (e.g., `mcp_aql_read`,
* `mcp_aql_create`, `mcp_aql_delete`).
*
* When no explicit {@link ElementGatekeeperPolicy} is provided on the agent,
* this config is translated into an enforceable deny policy by
* `AgentToolPolicyTranslator` during agent execution (Issue #449).
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface AgentToolConfig {
/** MCP-AQL tool endpoint names the agent is allowed to use */
allowed: string[];
/** MCP-AQL tool endpoint names the agent should not use (translated to deny list) */
denied?: string[];
}
/**
* Agent resilience policy configuration
*
* Defines how an agent recovers from step limits and execution failures.
* When not specified, all behaviors default to 'pause' (current behavior).
*
* @since v2.1.0 - Agent Execution Resilience (Issue #526)
*
* @example Auto-continue with limited continuations
* ```typescript
* const policy: AgentResiliencePolicy = {
* onStepLimitReached: 'continue',
* maxContinuations: 5,
* preserveState: true,
* };
* ```
*
* @example Retry failures with exponential backoff
* ```typescript
* const policy: AgentResiliencePolicy = {
* onExecutionFailure: 'retry',
* maxRetries: 3,
* retryBackoff: 'exponential',
* };
* ```
*
* @example Aggressive: auto-continue + retry + high limits
* ```typescript
* const policy: AgentResiliencePolicy = {
* onStepLimitReached: 'continue',
* onExecutionFailure: 'retry',
* maxRetries: 5,
* maxContinuations: 0, // unlimited
* retryBackoff: 'exponential',
* preserveState: true,
* };
* ```
*/
export interface AgentResiliencePolicy {
/** Behavior when maxAutonomousSteps is reached (default: 'pause') */
onStepLimitReached?: 'pause' | 'continue' | 'restart';
/** Behavior when a step fails (default: 'pause') */
onExecutionFailure?: 'pause' | 'retry' | 'restart-fresh';
/** Maximum retry attempts for failed steps (default: 3) */
maxRetries?: number;
/** Maximum auto-continuations before mandatory pause (default: 10, 0 = unlimited) */
maxContinuations?: number;
/** Backoff strategy for retries (default: 'exponential') */
retryBackoff?: 'none' | 'linear' | 'exponential';
/** Whether to preserve gathered data across continuations (default: true) */
preserveState?: boolean;
}
/**
* Agent v2.0 autonomy configuration
*
* Defines when an agent should continue autonomously vs pause for human input.
* Used by AutonomyEvaluator to determine continue/pause decisions.
*
* @since v2.0.0 - Agentic Loop Redesign (Epic #380)
*/
export interface AgentAutonomyConfig {
/** Risk tolerance level for autonomous decisions */
riskTolerance?: RiskTolerance;
/** Maximum steps before mandatory pause (0 = unlimited) */
maxAutonomousSteps?: number;
/** Action patterns that always require human approval (glob patterns) */
requiresApproval?: string[];
/** Action patterns that are auto-approved (glob patterns, overridden by requiresApproval) */
autoApprove?: string[];
/** Minutes before a verification challenge expires (default: 5). Issue #142. */
verificationTimeoutMinutes?: number;
}
/**
* Agent v2.0 metadata (simplified for LLM-first approach)
*
* Extends base element metadata with v2.0 fields.
* v1.x fields remain optional for backward compatibility.
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface AgentMetadataV2 extends IElementMetadata {
type?: ElementType.AGENT;
/** Goal configuration with template and parameters */
goal: AgentGoalConfig;
/** Elements to activate when agent executes */
activates?: AgentActivates;
/** Tool configuration — enforced via AgentToolPolicyTranslator when no explicit gatekeeper policy */
tools?: AgentToolConfig;
/** Custom system prompt for LLM context */
systemPrompt?: string;
/** Autonomy configuration for continue/pause decisions */
autonomy?: AgentAutonomyConfig;
/** Gatekeeper policy for restricting operations during agent execution (Issue #449) */
gatekeeper?: ElementGatekeeperPolicy;
/** Resilience policy for automatic recovery from step limits and failures (Issue #526) */
resilience?: AgentResiliencePolicy;
/** @deprecated v1.x - Use LLM judgment instead */
decisionFramework?: DecisionFramework;
specializations?: string[];
riskTolerance?: RiskTolerance;
/** @deprecated v1.x - LLM handles learning naturally */
learningEnabled?: boolean;
maxConcurrentGoals?: number;
/** @deprecated v1.x - Constraints handled by evaluateConstraints() */
ruleEngineConfig?: unknown;
triggers?: string[];
}
/**
* Result returned by execute_agent tool
*
* Provides all context the LLM needs to drive the agentic loop.
* Includes the goal, active elements, advisory signals, and safety tier.
*
* @since v2.0.0 - Agentic Loop Redesign
* @since v2.0.0 - Tiered Safety System (RFC #97)
*/
export interface ExecuteAgentResult {
/** Name of the executed agent */
agentName: string;
/** Rendered goal with parameters filled in */
goal: string;
/** ID of the persisted goal (for tracking with record_agent_step) */
goalId?: string;
/** State version after execution for optimistic locking (Issue #445) */
stateVersion?: number;
/** Active elements and their context contributions */
activeElements: Record<string, Array<{
name: string;
content: string;
}>>;
/** Tools available for this agent (informational) */
availableTools: string[];
/** Success criteria from goal definition */
successCriteria: string[];
/** Security warnings from validateGoalSecurity() */
securityWarnings?: string[];
/** Template rendering warnings (e.g. unmatched placeholders) (Issue #126) */
templateWarnings?: string[];
/**
* Element activation failures that occurred during setup (#116).
*
* When present, one or more elements failed to activate. The agent
* execution continues with available elements, but context may be
* incomplete. Circular activation errors are NOT included here —
* they throw immediately as configuration errors.
*/
activationWarnings?: Array<{
/** Type of element that failed (e.g., "personas", "skills", "memories") */
elementType: string;
/** Name of the specific element that failed */
elementName: string;
/** Error message describing why activation failed */
error: string;
}>;
/** Constraint evaluation from evaluateConstraints() */
constraints?: ConstraintResult;
/** Risk assessment from assessRisk() */
riskAssessment?: RiskAssessmentResult;
/** Priority score from calculatePriorityScore() */
priorityScore?: PriorityScoreResult;
/** Custom system prompt for LLM context */
systemPrompt?: string;
/** Safety tier for this execution */
safetyTier: SafetyTier;
/** Safety tier determination details */
safetyTierResult?: SafetyTierResult;
/** For CONFIRM tier: confirmation request details */
confirmationRequired?: ConfirmationRequest;
/** For VERIFY tier: verification challenge details */
verificationRequired?: VerificationChallenge;
/** For DANGER_ZONE tier: danger zone operation details */
dangerZoneBlocked?: DangerZoneOperation;
/** Execution context for agent chain tracking */
executionContext?: ExecutionContext;
}
/**
* Result of constraint evaluation
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface ConstraintResult {
/** Whether the agent can proceed (no blockers) */
canProceed: boolean;
/** Hard blockers that prevent execution */
blockers: string[];
/** Soft warnings to consider */
warnings: string[];
}
/**
* Result of risk assessment
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface RiskAssessmentResult {
/** Risk level category */
level: 'low' | 'medium' | 'high';
/** Numeric risk score (0-100) */
score: number;
/** Factors contributing to the risk score */
factors: string[];
/** Suggested mitigations */
mitigations: string[];
}
/**
* Result of priority scoring
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface PriorityScoreResult {
/** Overall priority score */
score: number;
/** Factors that contributed to the score */
factors: string[];
/** Score breakdown by category */
breakdown: Record<string, number>;
}
/**
* Security validation result
*
* @since v2.0.0 - Agentic Loop Redesign
*/
export interface SecurityValidationResult {
/** Whether the goal passed security validation */
safe: boolean;
/** Warning messages for flagged patterns */
warnings?: string[];
/** Names of patterns that were flagged */
flagged?: string[];
}
/**
* Minimal interface for danger zone enforcement (DI decoupling).
* Allows autonomy evaluator to block agents without depending on
* the full DangerZoneEnforcer class.
*
* @since v2.1.0 - Issue #402
*/
export interface DangerZoneBlocker {
block(agentName: string, reason: string, triggeredPatterns: string[], verificationId?: string,
/** Audit context for post-hoc investigation (Issue #404).
* Must stay structurally in sync with DangerZoneAuditContext in DangerZoneEnforcer.ts */
auditContext?: {
stepNumber?: number;
currentStepDescription?: string;
currentStepOutcome?: string;
nextActionHint?: string;
riskScore?: number;
goalDescription?: string;
goalId?: string;
safetyFactors?: string[];
}): void;
}
/**
* Context for autonomy evaluation
*
* Provides all information needed to determine whether an agent
* should continue autonomously or pause for human input.
*
* @since v2.0.0 - Agentic Loop Completion (Epic #380)
*/
export interface AutonomyContext {
/** The agent being evaluated */
agentName: string;
/** Agent's autonomy configuration */
autonomyConfig?: AgentAutonomyConfig;
/** Current step count in this execution */
stepCount: number;
/** Description of the just-completed step */
currentStepDescription: string;
/** Outcome of the just-completed step */
currentStepOutcome: 'success' | 'failure' | 'partial';
/** Optional hint about what the LLM plans to do next */
nextActionHint?: string;
/** Current safety tier from the last evaluation */
currentSafetyTier?: SafetyTier;
/** Risk score from current step (0-100) */
riskScore?: number;
/** DI-injected danger zone enforcer for blocking agents (Issue #402) */
dangerZoneEnforcer?: DangerZoneBlocker;
/** Server-side verification store for challenge codes (Issue #142) */
verificationStore?: {
set: (id: string, challenge: {
code: string;
expiresAt: number;
reason: string;
}) => void;
};
/** Active goal description (Issue #404: forwarded for audit context) */
goalDescription?: string;
/** Active goal ID (Issue #404: forwarded for audit context) */
goalId?: string;
}
/**
* Verification request for VERIFY tier actions
*
* @since v2.0.0 - Agentic Loop Completion (Epic #380)
*/
export interface AutonomyVerification {
/** Unique identifier for this verification request */
verificationId: string;
/** Human-readable prompt for the user */
prompt: string;
/**
* Display code for verification — intentionally stripped before returning to LLM.
* Only present internally during challenge creation; shown via OS dialog only (Issue #142).
* @internal
*/
displayCode?: string;
/** Type of verification required */
challengeType: VerificationChallengeType;
/** When this verification expires */
expiresAt: string;
}
/**
* Result of autonomy evaluation
*
* Tells the LLM whether to continue autonomously or pause for human input.
* Returned by AutonomyEvaluator.evaluate() and included in record_agent_step response.
*
* @since v2.0.0 - Agentic Loop Completion (Epic #380)
*/
export interface AutonomyDirective {
/** Whether the LLM can proceed autonomously */
continue: boolean;
/** Reason for pausing (if continue=false) */
reason?: string;
/** Safety tier of the next likely action */
nextStepRisk?: SafetyTier;
/** Steps remaining before mandatory pause (if maxAutonomousSteps configured) */
stepsRemaining?: number;
/** Verification required (if VERIFY tier triggered) */
verification?: AutonomyVerification;
/** Whether the agent was stopped due to DENY tier */
stopped?: boolean;
/** Factors that influenced the decision */
factors: string[];
/** Resilience action metadata when auto-continuation or retry is triggered (Issue #526) */
resilienceAction?: ResilienceAction;
/**
* Notifications about execution events (gatekeeper blocks, autonomy pauses, danger zone alerts).
* Present only when there are events to report. Bridge agents should check this array on
* every record_execution_step response to discover and relay events to human operators.
*
* @since v2.1.0 - Agent Notification System
*/
notifications?: AgentNotification[];
}
/**
* Resilience action returned by the resilience evaluator
*
* Describes what recovery action the server took (or recommends the LLM take)
* when a step limit or failure triggers the resilience policy.
*
* @since v2.1.0 - Agent Execution Resilience (Issue #526)
*
* @example Continue action (step limit reached)
* ```typescript
* const action: ResilienceAction = {
* action: 'continue',
* reason: 'Step limit reached; auto-continuing per policy',
* continuationCount: 2,
* maxContinuations: 5,
* };
* ```
*
* @example Retry action (step failure with backoff)
* ```typescript
* const action: ResilienceAction = {
* action: 'retry',
* reason: 'Step failed; retrying with exponential backoff',
* retryCount: 1,
* backoffMs: 2000,
* };
* ```
*/
export interface ResilienceAction {
/** The action type */
action: 'pause' | 'continue' | 'retry' | 'restart';
/** Human-readable reason for the action */
reason: string;
/** For retry actions: recommended backoff in milliseconds */
backoffMs?: number;
/** Current retry count (for retry actions) */
retryCount?: number;
/** Current continuation count (for continue/restart actions) */
continuationCount?: number;
/** Maximum continuations allowed (0 = unlimited) */
maxContinuations?: number;
}
/**
* Notification for agent execution events
*
* Enables bridge agents to discover gatekeeper blocks, autonomy pauses,
* danger zone triggers, and other execution events without polling.
* Notifications are included in the AutonomyDirective response from
* record_execution_step.
*
* @since v2.1.0 - Agent Notification System
*/
export interface AgentNotification {
/** Notification category */
type: 'permission_pending' | 'autonomy_pause' | 'danger_zone' | 'status' | 'error';
/** Human-readable message describing the event */
message: string;
/** Structured metadata for programmatic consumption */
metadata?: {
/** The MCP-AQL operation that was blocked */
operation?: string;
/** Element type involved in the block */
element_type?: string;
/** Reason for the block/pause */
reason?: string;
/** Permission level that caused the block (DENY, CONFIRM_SESSION, CONFIRM_SINGLE_USE) */
level?: string;
/** Verification ID (for danger_zone blocks) */
verificationId?: string;
/** Agent name (used in danger_zone broadcasts to identify which agent is blocked) */
agentName?: string;
};
/** ISO 8601 timestamp when the event occurred */
timestamp: string;
}
//# sourceMappingURL=types.d.ts.map