@elizaos/plugin-power

Domain evaluator for agent power situation (influence, control, leverage).

Why This Plugin Exists

elizaOS agents need to understand their external "power" situation to make informed decisions. An agent with strong relationships and key contacts can take different actions than one who is socially isolated.

Power is external social capital, distinct from internal state (homeostasis). This plugin answers questions like:

• How much influence does the agent have in its network?
• Are relationships well-maintained or neglected?
• Does the agent have access to key decision-makers?

Architecture

[plugin-rolodex]  →  [plugin-power]  →  [plugin-appraisal]  →  [plugin-motivation]
   (data)            (evaluator)         (registry)           (interpreter)

Why This Separation?

Layer	Responsibility	Knows About
Data (rolodex)	Store relationship data	Relationships
Evaluator (power)	Assess power from relationships	Relationships + assessment
Registry (appraisal)	Store assessments	Assessments only
Interpreter (motivation)	Decide priorities	All assessments

Each layer has a single responsibility. Adding new domain evaluators (money, notoriety) doesn't require changing motivation. Changing power logic doesn't affect data storage.

Components

PowerService

The core evaluation engine.

What it does:

• Collects relationship insights from plugin-rolodex
• Assesses influence (network strength), control (network stability), leverage (key contacts)
• Calculates confidence based on data quality
• Publishes appraisals to plugin-appraisal

Why a service (not evaluator)?

• Services maintain state and handle complex logic
• Can be queried directly by other plugins
• Lifecycle management (start/stop)

PowerEvaluator

Message-triggered re-evaluation.

What it does:

• Detects relationship-relevant messages (keywords like "thank you", "friend", "disagree")
• Triggers PowerService.evaluate()

Why keyword matching (not LLM)?

• Fast (instant vs. seconds for LLM)
• Cheap (no API calls)
• Transparent (debuggable)
• Good enough (false positives are cheap, false negatives are worse)

PowerProvider

LLM context injection.

What it does:

• Formats power assessment as natural language
• Provides structured data for code access
• Available via composeState(msg, ['POWER'])

Why a provider (not just service access)?

• Standard interface across elizaOS
• Automatic inclusion in state composition
• Handles missing service gracefully

Installation

bun add @elizaos/plugin-power

Usage

Register the Plugin

import { powerPlugin } from '@elizaos/plugin-power';
import { rolodexPlugin } from '@elizaos/plugin-rolodex';
import { appraisalPlugin } from '@elizaos/plugin-appraisal';

const runtime = new AgentRuntime({
  plugins: [
    rolodexPlugin,    // Required - provides relationship data
    appraisalPlugin,  // Optional - stores appraisals
    powerPlugin,      // This plugin
  ],
});

Access the Service

import { POWER_SERVICE_TYPE, type IPowerService } from '@elizaos/plugin-power';

const service = runtime.getService(POWER_SERVICE_TYPE) as IPowerService;

// Trigger evaluation
const assessment = await service.evaluate();

// Read last assessment (sync)
const last = service.getLastAssessment();

Include in LLM Context

import { POWER_PROVIDER_NAME } from '@elizaos/plugin-power';

const state = await runtime.composeState(message, [POWER_PROVIDER_NAME]);

// Natural language for prompt
console.log(state.data.providers.POWER.text);
// "Your influence is strong. Your network control is stable..."

// Structured data for code
const { assessment, confidence } = state.data.providers.POWER.data;

Listen for Events

import { PowerEvents } from '@elizaos/plugin-power';

runtime.registerEvent(PowerEvents.EVALUATED, (payload) => {
  console.log('Power evaluated:', payload.assessment.influence);
});

runtime.registerEvent(PowerEvents.EVALUATION_FAILED, (payload) => {
  console.error('Evaluation failed:', payload.reason);
});

Type the Appraisal

import type { PowerPayload } from '@elizaos/plugin-power';
import type { Appraisal } from '@elizaos/plugin-appraisal';

const appraisal: Appraisal<PowerPayload> = appraisalService.get('power');
console.log(appraisal.payload.influence);  // 'dominant' | 'strong' | 'moderate' | 'weak'

Assessment Dimensions

Influence

What it measures: Social capital based on strong relationships.

How it's calculated: Count of relationships with strength > 70.

Level	Threshold	Meaning
dominant	>5 strong	Agent is a social hub
strong	3-5 strong	Solid network
moderate	1-2 strong	Some connections
weak	0 strong	Minimal social capital

Why count (not average)? An agent with 10 strong relationships has more influence than one with 2 very strong relationships. Count captures network breadth.

Control

What it measures: Network stability based on relationship maintenance.

How it's calculated: Ratio of neglected relationships (no contact in 30+ days) to total.

Level	Threshold	Meaning
secure	<20% neglected	Well-maintained
stable	20-40% neglected	Mostly good
contested	40-60% neglected	Needs attention
vulnerable	>60% neglected	Deteriorating

Why neglect ratio (not absolute count)? Normalizes for network size. 10 neglected out of 100 is better than 3 neglected out of 5.

Leverage

What it measures: Access to key contacts (VIP/business categories).

How it's calculated: Count of contacts in VIP or business categories.

Level	Threshold	Meaning
high	>3 key contacts	Strong access to decision-makers
moderate	1-3 key contacts	Some access
low	1 key contact	Limited access
none	0 key contacts	No special access

Why VIP/business categories? These indicate contacts with decision-making authority or resources. Friends provide different value (emotional support) but not "leverage" in the negotiating sense.

Confidence Calculation

Confidence (0-1) represents "how much should you trust this assessment?"

Network Size Factor

Relationships	Confidence Multiplier	Rationale
<2	0.25	Extrapolating from minimal data
2-3	0.50	Small sample
4-5	0.75	Approaching real network
6+	1.00	Full confidence from size

Data Freshness Factor

Condition	Confidence Multiplier	Rationale
No recent interactions	0.60	Data might be stale
Has recent interactions	1.00	Data is current

Combined Example

6 relationships, no recent interactions:
  1.0 (size) × 0.6 (freshness) = 0.60 confidence

2 relationships, recent interactions:
  0.5 (size) × 1.0 (freshness) = 0.50 confidence

1 relationship, no recent interactions:
  0.25 (size) × 0.6 (freshness) = 0.15 confidence

Minimum confidence: 0.10 (even terrible data provides some signal)

Configuration

Customize thresholds via runtime settings:

// In agent character or environment
{
  POWER_INFLUENCE_DOMINANT_THRESHOLD: 10,  // Need 10+ for "dominant"
  POWER_CONTROL_SECURE_THRESHOLD: 0.1,     // <10% neglected = "secure"
  POWER_LEVERAGE_HIGH_THRESHOLD: 5,        // Need 5+ for "high"
}

Why configurable? Different agents have different contexts. A celebrity might need 50 relationships for "dominant"; a personal assistant might consider 3 "dominant".

Dependencies

Required

• @elizaos/core: Runtime, types, base classes
• plugin-rolodex: Relationship data source

Optional

• plugin-appraisal: Appraisal storage (degrades gracefully without)

Why is rolodex required but appraisal optional?

• Without rolodex: No data to assess. Fail loudly.
• Without appraisal: Can still assess, just don't publish. Degrade gracefully.

API Reference

Types

// Assessment payload
interface PowerPayload {
  influence: 'dominant' | 'strong' | 'moderate' | 'weak';
  control: 'secure' | 'stable' | 'contested' | 'vulnerable';
  leverage: 'high' | 'moderate' | 'low' | 'none';
  keyRelationships?: string[];
}

// Service interface
interface IPowerService {
  evaluate(): Promise<PowerPayload | null>;
  getLastAssessment(): PowerPayload | null;
  getLastEvaluatedAt(): number | null;
}

Constants

POWER_SERVICE_TYPE = 'power'
POWER_PROVIDER_NAME = 'POWER'
POWER_APPRAISAL_ID = 'power'
PowerEvents.EVALUATED = 'POWER_EVALUATED'
PowerEvents.EVALUATION_FAILED = 'POWER_EVALUATION_FAILED'

Development

Build

bun run build

Test

bun test

Watch

bun run dev

License

MIT