openfeelz 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFeelz contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# OpenFeelz
+
+> *"Let's build robots with Genuine People Personalities, they said. So they tried it out with me. I'm a personality prototype. You can tell can't you?"*
+> -- Douglas Adams, *The Hitchhiker's Guide to the Galaxy*
+
+[![CI](https://github.com/trianglegrrl/openfeelz/actions/workflows/ci.yml/badge.svg)](https://github.com/trianglegrrl/openfeelz/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-plugin-purple.svg)](https://openclaw.com)
+
+An [OpenClaw](https://openclaw.com) plugin that gives AI agents a multidimensional emotional model with personality-influenced decay, rumination, and multi-agent awareness.
+
+Most agents vibes-check each message independently and forget everything between turns. OpenFeelz gives them emotional short-term memory -- the agent knows you've been frustrated for the last three messages, and it carries that context forward. It's not sentience, it's just better interaction design. (But it's pretty cool.)
+
+## Features
+
+- **PAD Dimensional Model** -- Pleasure, Arousal, Dominance + Connection, Curiosity, Energy, Trust
+- **Ekman Basic Emotions** -- Happiness, Sadness, Anger, Fear, Disgust, Surprise
+- **OCEAN Personality** -- Big Five traits influence baselines, decay rates, and response intensity
+- **Exponential Decay** -- Emotions fade toward personality-influenced baselines over time
+- **Rumination Engine** -- Intense emotions continue to influence state across interactions
+- **Goal-Aware Modulation** -- Personality-inferred goals amplify relevant emotions
+- **Multi-Agent Awareness** -- Agents see other agents' emotional states in the system prompt
+- **Custom Taxonomy** -- Define your own emotion labels with dimension mappings
+- **LLM Classification** -- Automatically classify user/agent emotions via OpenAI-compatible models
+- **Web Dashboard** -- Glassmorphism UI at `/emotion-dashboard`
+- **MCP Server** -- Expose emotional state to Cursor, Claude Desktop, etc.
+- **CLI Tools** -- `openclaw emotion status`, `reset`, `personality`, `history`, `decay`
+
+## Installation
+
+```bash
+openclaw plugins install openfeelz
+openclaw plugins enable openfeelz
+```
+
+## How It Works
+
+Every agent turn, OpenFeelz hooks into the lifecycle:
+
+```
+User sends a message
+        |
+        v
+  [before_agent_start hook]
+        |
+        v
+  1. Load emotion state from disk
+  2. Apply exponential decay based on elapsed time
+  3. Advance any active rumination entries
+  4. Format state into an <emotion_state> XML block
+  5. Return as "prependContext" to OpenClaw
+        |
+        v
+  Agent sees emotional context in its system prompt
+        |
+        v
+  [Agent responds]
+        |
+        v
+  [agent_end hook]
+        |
+        v
+  1. Classify emotions in user + agent messages via LLM
+  2. Map to dimensional changes
+  3. Start rumination if intensity exceeds threshold
+  4. Save updated state to disk
+```
+
+### What the Agent Sees
+
+The plugin prepends an `<emotion_state>` block to the system prompt:
+
+```xml
+<emotion_state>
+  <dimensions>
+    pleasure: lowered (-0.12), arousal: elevated (0.18), curiosity: elevated (0.72)
+  </dimensions>
+  <user>
+    2026-02-06 09:15: Felt strongly frustrated because deployment keeps failing.
+    2026-02-06 08:40: Felt moderately anxious because tight deadline approaching.
+    Trend (last 24h): mostly frustrated.
+  </user>
+  <agent>
+    2026-02-06 09:10: Felt moderately focused because working through error logs.
+  </agent>
+  <others>
+    research-agent — 2026-02-06 08:00: Felt mildly curious because investigating new library.
+  </others>
+</emotion_state>
+```
+
+- **`<dimensions>`** -- PAD dimensions that deviate >0.15 from personality baseline
+- **`<user>`** -- Last 3 classified user emotions with timestamps, intensity, and triggers
+- **`<agent>`** -- Last 2 agent emotions (continuity across turns)
+- **`<others>`** -- Other agents' recent emotional states (up to `maxOtherAgents`)
+
+The block only appears when there's something to show. Set `contextEnabled: false` to disable injection while keeping classification, decay, and the dashboard active.
+
+## Decay Model
+
+Emotions return to personality-influenced baselines via exponential decay:
+
+```
+newValue = baseline + (currentValue - baseline) * e^(-rate * elapsedHours)
+halfLife = ln(2) / rate
+```
+
+### Default Rates
+
+| Dimension / Emotion | Rate (per hour) | Half-Life | Notes |
+|---------------------|-----------------|-----------|-------|
+| Pleasure | 0.058 | ~12h | |
+| Arousal | 0.087 | ~8h | Activation calms quickly |
+| Dominance | 0.046 | ~15h | Sense of control shifts slowly |
+| Connection | 0.035 | ~20h | Social bonds persist |
+| Curiosity | 0.058 | ~12h | |
+| Energy | 0.046 | ~15h | |
+| Trust | 0.035 | ~20h | Hard-won, slow to fade |
+| Happiness | 0.058 | ~12h | |
+| Sadness | 0.046 | ~15h | Lingers longer than joy |
+| Anger | 0.058 | ~12h | |
+| Fear | 0.058 | ~12h | |
+| Disgust | 0.046 | ~15h | |
+| Surprise | 0.139 | ~5h | Fades the fastest |
+
+### Personality Modulation
+
+OCEAN traits adjust decay rates:
+
+- **High neuroticism** -- Negative emotions linger (~0.84-0.88x decay rate)
+- **High extraversion** -- Sadness fades faster (~1.16x), arousal/pleasure recover quicker
+- **High agreeableness** -- Anger fades faster (~1.12x), connection decays slower
+- **High openness** -- Curiosity and surprise persist longer
+
+### When Decay Runs
+
+Decay is computed on-demand, not on a timer:
+
+1. **`before_agent_start`** -- Primary mechanism. Applied based on elapsed time since last update.
+2. **Tool `query` action** -- Decay applied before reading, so values are accurate.
+3. **Optional background service** -- Set `decayServiceEnabled: true` for dashboard accuracy between interactions.
+
+### Configuring Decay
+
+Three levels of control:
+
+- **Global half-life** -- `halfLifeHours: 6` makes everything fade 2x faster
+- **Per-dimension overrides** -- `"decayRates": { "pleasure": 0.1, "trust": 0.02 }`
+- **Personality-driven** -- Change OCEAN traits and rates recalculate automatically
+
+## Configuration
+
+In `~/.openclaw/openclaw.json` under `plugins.entries.openfeelz.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openfeelz": {
+        "config": {
+          "apiKey": "${OPENAI_API_KEY}",
+          "model": "gpt-5-mini",
+          "halfLifeHours": 12,
+          "ruminationEnabled": true,
+          "personality": {
+            "openness": 0.7,
+            "conscientiousness": 0.6,
+            "extraversion": 0.5,
+            "agreeableness": 0.8,
+            "neuroticism": 0.3
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Also configurable via the OpenClaw web UI.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENAI_API_KEY` | _(required)_ | API key for LLM emotion classification |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Custom API base URL |
+| `EMOTION_MODEL` | `gpt-5-mini` | Classification model (when OpenAI key present) |
+| `EMOTION_CLASSIFIER_URL` | _(none)_ | External HTTP classifier (bypasses LLM) |
+| `EMOTION_HALF_LIFE_HOURS` | `12` | Global decay half-life |
+| `EMOTION_CONFIDENCE_MIN` | `0.35` | Min confidence threshold |
+| `EMOTION_HISTORY_SIZE` | `100` | Max stored stimuli per agent |
+| `EMOTION_TIMEZONE` | _(system)_ | IANA timezone for display |
+
+### Full Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | `$OPENAI_API_KEY` | API key for LLM classification |
+| `baseUrl` | string | OpenAI default | API base URL |
+| `model` | string | `claude-sonnet-4-5` / `gpt-5-mini` | Classification model (auto-selected by available API key) |
+| `classifierUrl` | string | _(none)_ | External classifier URL |
+| `confidenceMin` | number | `0.35` | Min confidence threshold |
+| `halfLifeHours` | number | `12` | Global decay half-life |
+| `trendWindowHours` | number | `24` | Trend computation window |
+| `maxHistory` | number | `100` | Max stored stimuli |
+| `ruminationEnabled` | boolean | `true` | Enable rumination engine |
+| `ruminationThreshold` | number | `0.7` | Intensity threshold for rumination |
+| `ruminationMaxStages` | number | `4` | Max rumination stages |
+| `realtimeClassification` | boolean | `false` | Classify on every message |
+| `contextEnabled` | boolean | `true` | Prepend emotion context to prompt |
+| `decayServiceEnabled` | boolean | `false` | Background decay service |
+| `decayServiceIntervalMinutes` | number | `30` | Decay service interval |
+| `dashboardEnabled` | boolean | `true` | Serve web dashboard |
+| `timezone` | string | _(system)_ | IANA timezone |
+| `maxOtherAgents` | number | `3` | Max other agents in prompt |
+| `emotionLabels` | string[] | _(21 built-in)_ | Custom label taxonomy |
+| `personality` | object | all `0.5` | OCEAN trait values |
+| `decayRates` | object | _(see table)_ | Per-dimension rate overrides |
+| `dimensionBaselines` | object | _(computed)_ | Per-dimension baseline overrides |
+
+## Agent Tool: `emotion_state`
+
+The agent can inspect and modify its own emotional state:
+
+| Action | Description | Parameters |
+|--------|-------------|------------|
+| `query` | Get current emotional state | `format?: "full" / "summary" / "dimensions" / "emotions"` |
+| `modify` | Apply an emotional stimulus | `emotion, intensity?, trigger?` |
+| `set_dimension` | Set or adjust a dimension | `dimension, value?` or `dimension, delta?` |
+| `reset` | Reset to personality baseline | `dimensions?` (comma-separated, or all) |
+| `set_personality` | Set an OCEAN trait | `trait, value` |
+| `get_personality` | Get current OCEAN profile | _(none)_ |
+
+## CLI
+
+```bash
+openclaw emotion status              # Formatted state with bars
+openclaw emotion status --json       # Raw JSON
+openclaw emotion personality         # OCEAN profile
+openclaw emotion personality set --trait openness --value 0.8
+openclaw emotion reset               # Reset all to baseline
+openclaw emotion reset --dimensions pleasure,arousal
+openclaw emotion history --limit 20  # Recent stimuli
+openclaw emotion decay --dimension pleasure --rate 0.05
+```
+
+## Dashboard
+
+`http://localhost:<gateway-port>/emotion-dashboard`
+
+Real-time visualization of PAD dimensions, basic emotions, OCEAN profile, recent stimuli, and active rumination. Append `?format=json` for the raw API.
+
+## MCP Server
+
+Works with any MCP-compatible client (Cursor, Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "openfeelz": {
+      "command": "npx",
+      "args": ["openfeelz/mcp"]
+    }
+  }
+}
+```
+
+**Resources:** `emotion://state`, `emotion://personality`
+
+**Tools:** `query_emotion`, `modify_emotion`, `set_personality`
+
+## Migration from v1
+
+```bash
+openclaw hooks disable emotion-state
+openclaw emotion migrate
+```
+
+Converts v1 state files (flat labels + string intensities) to v2 format (dimensional model + numeric intensities). Uses a separate state file (`openfeelz.json`), so no risk of data loss.
+
+## Architecture
+
+```
+index.ts                 Plugin entry: registers tool, hooks, service, CLI, dashboard
+src/
+  types.ts               All interfaces (DimensionalState, BasicEmotions, OCEANProfile, etc.)
+  model/
+    emotion-model.ts     Core model: clamping, primary detection, intensity, deltas
+    personality.ts       OCEAN: baselines, decay rates, rumination probability
+    decay.ts             Exponential decay toward personality-influenced baselines
+    mapping.ts           Emotion label -> dimension/emotion delta mapping (60+ labels)
+    rumination.ts        Multi-stage internal processing for intense emotions
+    goal-modulation.ts   Personality-inferred goals amplify relevant emotions
+    custom-taxonomy.ts   User-defined emotion labels with custom mappings
+  state/
+    state-manager.ts     Orchestrator: classify + map + decay + ruminate + persist
+    state-file.ts        Atomic JSON I/O with file locking
+    multi-agent.ts       Scan sibling agent states for awareness
+  classify/
+    classifier.ts        Unified LLM + HTTP classifier with fallback
+  tool/
+    emotion-tool.ts      OpenClaw tool: query/modify/reset/personality
+  hook/
+    hooks.ts             before_agent_start + agent_end hooks
+  cli/
+    cli.ts               Commander.js CLI commands
+  http/
+    dashboard.ts         Glassmorphism HTML dashboard
+  mcp/
+    mcp-server.ts        MCP server resources + tools
+  format/
+    prompt-formatter.ts  System prompt <emotion_state> block builder
+  migration/
+    migrate-v1.ts        v1 -> v2 converter
+```
+
+## Development
+
+```bash
+npm install
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+npm run typecheck     # TypeScript strict mode
+npm run lint          # oxlint
+npm run build         # Compile to dist/
+```
+
+## Contributing
+
+Issues, PRs, and questions are all welcome. If you want to poke around the model or improve it, please do -- I'd love to collaborate. :)
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+Made with ❤️ by [@trianglegrrl](https://github.com/trianglegrrl) for the OpenClaw community 🦞

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenFeelz - OpenClaw Plugin Entry Point
+ *
+ * Registers:
+ *  - emotion_state tool (query/modify/reset/personality)
+ *  - before_agent_start hook (inject emotional context)
+ *  - agent_end hook (classify emotions from conversation)
+ *  - background service (optional periodic decay)
+ *  - CLI commands (openclaw emotion ...)
+ *  - HTTP dashboard route (/emotion-dashboard)
+ *
+ * State is stored per-agent in each agent's workspace:
+ *   {workspace}/openfeelz.json
+ */
+declare const emotionEnginePlugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+export default emotionEnginePlugin;

package/dist/index.js

@@ -0,0 +1,240 @@
+/**
+ * OpenFeelz - OpenClaw Plugin Entry Point
+ *
+ * Registers:
+ *  - emotion_state tool (query/modify/reset/personality)
+ *  - before_agent_start hook (inject emotional context)
+ *  - agent_end hook (classify emotions from conversation)
+ *  - background service (optional periodic decay)
+ *  - CLI commands (openclaw emotion ...)
+ *  - HTTP dashboard route (/emotion-dashboard)
+ *
+ * State is stored per-agent in each agent's workspace:
+ *   {workspace}/openfeelz.json
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_CONFIG } from "./src/types.js";
+import { StateManager } from "./src/state/state-manager.js";
+import { resolveAgentDir, resolveAgentStatePath, listAgentIds } from "./src/paths.js";
+import { createEmotionTool } from "./src/tool/emotion-tool.js";
+import { createBootstrapHook, createAgentEndHook } from "./src/hook/hooks.js";
+import { registerEmotionCli } from "./src/cli/cli.js";
+import { createDashboardHandler } from "./src/http/dashboard.js";
+import { analyzePersonalityViaLLM, describeEmotionalStateViaLLM } from "./src/analysis/analyzer.js";
+/**
+ * Resolve plugin configuration from raw pluginConfig + environment variables.
+ */
+function resolveConfig(raw) {
+    const env = process.env;
+    const personality = (raw?.personality ?? {});
+    const apiKey = raw?.apiKey ?? env.ANTHROPIC_API_KEY ?? env.OPENAI_API_KEY ?? undefined;
+    const explicitModel = raw?.model ?? env.EMOTION_MODEL;
+    const hasAnthropicKey = !!(raw?.apiKey || env.ANTHROPIC_API_KEY);
+    const hasOpenAIKey = !!(raw?.apiKey || env.OPENAI_API_KEY);
+    let model = explicitModel ?? DEFAULT_CONFIG.model;
+    let baseUrl = raw?.baseUrl ?? env.OPENAI_BASE_URL ?? DEFAULT_CONFIG.baseUrl;
+    if (!explicitModel && hasOpenAIKey && !hasAnthropicKey) {
+        model = "gpt-5-mini";
+        baseUrl = baseUrl || "https://api.openai.com/v1";
+    }
+    return {
+        apiKey,
+        baseUrl,
+        model,
+        provider: raw?.provider ?? undefined,
+        classifierUrl: raw?.classifierUrl ?? env.EMOTION_CLASSIFIER_URL ?? undefined,
+        confidenceMin: raw?.confidenceMin ?? (Number(env.EMOTION_CONFIDENCE_MIN) || DEFAULT_CONFIG.confidenceMin),
+        halfLifeHours: raw?.halfLifeHours ?? (Number(env.EMOTION_HALF_LIFE_HOURS) || DEFAULT_CONFIG.halfLifeHours),
+        trendWindowHours: raw?.trendWindowHours ?? DEFAULT_CONFIG.trendWindowHours,
+        maxHistory: raw?.maxHistory ?? (Number(env.EMOTION_HISTORY_SIZE) || DEFAULT_CONFIG.maxHistory),
+        ruminationEnabled: raw?.ruminationEnabled ?? DEFAULT_CONFIG.ruminationEnabled,
+        ruminationThreshold: raw?.ruminationThreshold ?? DEFAULT_CONFIG.ruminationThreshold,
+        ruminationMaxStages: raw?.ruminationMaxStages ?? DEFAULT_CONFIG.ruminationMaxStages,
+        realtimeClassification: raw?.realtimeClassification ?? DEFAULT_CONFIG.realtimeClassification,
+        contextEnabled: raw?.contextEnabled ?? DEFAULT_CONFIG.contextEnabled,
+        decayServiceEnabled: raw?.decayServiceEnabled ?? DEFAULT_CONFIG.decayServiceEnabled,
+        decayServiceIntervalMinutes: raw?.decayServiceIntervalMinutes ?? DEFAULT_CONFIG.decayServiceIntervalMinutes,
+        dashboardEnabled: raw?.dashboardEnabled ?? DEFAULT_CONFIG.dashboardEnabled,
+        timezone: raw?.timezone ?? env.EMOTION_TIMEZONE ?? undefined,
+        maxOtherAgents: raw?.maxOtherAgents ?? DEFAULT_CONFIG.maxOtherAgents,
+        emotionLabels: raw?.emotionLabels ?? DEFAULT_CONFIG.emotionLabels,
+        personality: {
+            openness: personality.openness ?? DEFAULT_CONFIG.personality.openness,
+            conscientiousness: personality.conscientiousness ?? DEFAULT_CONFIG.personality.conscientiousness,
+            extraversion: personality.extraversion ?? DEFAULT_CONFIG.personality.extraversion,
+            agreeableness: personality.agreeableness ?? DEFAULT_CONFIG.personality.agreeableness,
+            neuroticism: personality.neuroticism ?? DEFAULT_CONFIG.personality.neuroticism,
+        },
+        decayRateOverrides: raw?.decayRates ?? {},
+        dimensionBaselineOverrides: raw?.dimensionBaselines ?? {},
+    };
+}
+/**
+ * Attempt to resolve an Anthropic API key from OpenClaw's auth-profiles.json.
+ * Falls back gracefully if the file doesn't exist or has no Anthropic profile.
+ */
+function resolveApiKeyFromAuthProfiles(api, agentId = "main") {
+    try {
+        const agentDir = resolveAgentDir(api.config, agentId);
+        const authFile = path.join(agentDir, "auth-profiles.json");
+        if (!fs.existsSync(authFile))
+            return undefined;
+        const raw = JSON.parse(fs.readFileSync(authFile, "utf8"));
+        const profiles = raw?.profiles ?? {};
+        for (const profile of Object.values(profiles)) {
+            if (profile?.provider === "anthropic" && profile?.token) {
+                return profile.token;
+            }
+        }
+    }
+    catch {
+        // Not critical
+    }
+    return undefined;
+}
+const emotionEnginePlugin = {
+    id: "openfeelz",
+    name: "OpenFeelz",
+    description: "PAD + Ekman + OCEAN emotional model with personality-influenced decay, " +
+        "rumination, and multi-agent awareness",
+    register(api) {
+        const config = resolveConfig(api.pluginConfig);
+        // Resolve API key from OpenClaw auth profiles if not explicitly configured
+        if (!config.apiKey) {
+            const resolvedKey = resolveApiKeyFromAuthProfiles(api);
+            if (resolvedKey) {
+                config.apiKey = resolvedKey;
+            }
+        }
+        const cfg = api.config;
+        // Per-agent StateManager cache (state path = workspace/openfeelz.json)
+        const managerCache = new Map();
+        const getManager = (agentId) => {
+            const id = agentId?.trim() || "main";
+            let m = managerCache.get(id);
+            if (!m) {
+                const statePath = resolveAgentStatePath(cfg, id);
+                m = new StateManager(statePath, config);
+                managerCache.set(id, m);
+            }
+            return m;
+        };
+        const defaultStatePath = resolveAgentStatePath(cfg, "main");
+        api.logger?.info?.(`openfeelz: registered (state: ${defaultStatePath}, model: ${config.model}, provider: ${config.provider ?? "auto"})`);
+        // -- Tool -- (uses main agent when agent context not available)
+        api.registerTool(createEmotionTool(getManager("main")), { name: "emotion_state" });
+        // -- Hooks --
+        const bootstrapHandler = createBootstrapHook(getManager, config, cfg);
+        api.on("before_agent_start", async (event) => {
+            const agentId = event.agentId ?? "main";
+            const result = await bootstrapHandler({
+                prompt: event.prompt ?? "",
+                userKey: event.senderId ?? event.sessionKey ?? "unknown",
+                agentId,
+            });
+            return result;
+        });
+        const agentEndHandler = createAgentEndHook(getManager, config);
+        api.on("agent_end", async (event) => {
+            const agentId = event.agentId ?? "main";
+            await agentEndHandler({
+                success: event.success ?? true,
+                messages: event.messages ?? [],
+                userKey: event.senderId ?? event.sessionKey ?? "unknown",
+                agentId,
+            });
+        });
+        // -- Service (background analysis: startup + every 30m) --
+        if (config.apiKey) {
+            let analysisIntervalHandle = null;
+            const runAnalysis = async () => {
+                try {
+                    for (const agentId of listAgentIds(cfg)) {
+                        const manager = getManager(agentId);
+                        const state = await manager.getState();
+                        const opts = {
+                            apiKey: config.apiKey,
+                            model: config.model,
+                            provider: config.provider,
+                            baseUrl: config.baseUrl,
+                        };
+                        const [personality, emotionalState] = await Promise.all([
+                            analyzePersonalityViaLLM(state, opts),
+                            describeEmotionalStateViaLLM(state, opts),
+                        ]);
+                        const now = new Date().toISOString();
+                        const updated = {
+                            ...state,
+                            cachedAnalysis: {
+                                personality: { ...personality, generatedAt: now },
+                                emotionalState: { ...emotionalState, generatedAt: now },
+                            },
+                        };
+                        await manager.saveState(updated);
+                    }
+                }
+                catch (err) {
+                    api.logger?.error?.(`[openfeelz] Analysis service error: ${err}`);
+                }
+            };
+            api.registerService({
+                id: "openfeelz-analysis",
+                start: () => {
+                    runAnalysis();
+                    analysisIntervalHandle = setInterval(runAnalysis, 30 * 60_000);
+                    api.logger?.info?.("openfeelz: analysis service started (interval: 30m)");
+                },
+                stop: () => {
+                    if (analysisIntervalHandle) {
+                        clearInterval(analysisIntervalHandle);
+                        analysisIntervalHandle = null;
+                    }
+                    api.logger?.info?.("openfeelz: analysis service stopped");
+                },
+            });
+        }
+        // -- Service (optional background decay) --
+        if (config.decayServiceEnabled) {
+            let intervalHandle = null;
+            api.registerService({
+                id: "openfeelz-decay",
+                start: () => {
+                    const ms = config.decayServiceIntervalMinutes * 60_000;
+                    intervalHandle = setInterval(async () => {
+                        try {
+                            for (const agentId of listAgentIds(cfg)) {
+                                const manager = getManager(agentId);
+                                let state = await manager.getState();
+                                state = manager.applyDecay(state);
+                                state = manager.advanceRumination(state);
+                                await manager.saveState(state);
+                            }
+                        }
+                        catch (err) {
+                            api.logger?.error?.(`[openfeelz] Decay service error: ${err}`);
+                        }
+                    }, ms);
+                    api.logger?.info?.(`openfeelz: decay service started (interval: ${config.decayServiceIntervalMinutes}m)`);
+                },
+                stop: () => {
+                    if (intervalHandle) {
+                        clearInterval(intervalHandle);
+                        intervalHandle = null;
+                    }
+                    api.logger?.info?.("openfeelz: decay service stopped");
+                },
+            });
+        }
+        // -- CLI --
+        api.registerCli(({ program }) => registerEmotionCli({ program, getManager, config }), { commands: ["emotion"] });
+        // -- HTTP Dashboard --
+        if (config.dashboardEnabled) {
+            api.registerHttpRoute({
+                path: "/emotion-dashboard",
+                handler: createDashboardHandler(getManager),
+            });
+        }
+    },
+};
+export default emotionEnginePlugin;

package/dist/src/analysis/analyzer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LLM-backed personality and emotional state analysis.
+ *
+ * Uses direct HTTP calls with config.apiKey (same pattern as classifier).
+ * Supports Anthropic and OpenAI. Injectable fetchFn for testing.
+ */
+import type { EmotionEngineState } from "../types.js";
+export interface PersonalityAnalysisResult {
+    summary: string;
+    pad: {
+        pleasure: number;
+        arousal: number;
+        dominance: number;
+    };
+    extensions: {
+        connection: number;
+        curiosity: number;
+        energy: number;
+        trust: number;
+    };
+    ocean: {
+        openness: number;
+        conscientiousness: number;
+        extraversion: number;
+        agreeableness: number;
+        neuroticism: number;
+    };
+}
+export interface EmotionalStateResult {
+    summary: string;
+    primary: string;
+    intensity: number;
+    notes: string[];
+}
+/** Options for the analyzer functions. */
+export interface AnalyzerOptions {
+    /** API key (Anthropic or OpenAI, depending on model). */
+    apiKey?: string;
+    /** Base URL override (for OpenAI-compatible endpoints). */
+    baseUrl?: string;
+    /** Model name for LLM analysis. */
+    model?: string;
+    /** Force a specific provider: "anthropic" | "openai". Auto-detected from model if omitted. */
+    provider?: "anthropic" | "openai";
+    /** Timeout in ms. */
+    timeoutMs?: number;
+    /** Injectable fetch function (for testing). */
+    fetchFn?: typeof fetch;
+}
+export declare function analyzePersonalityViaLLM(state: EmotionEngineState, opts: AnalyzerOptions): Promise<PersonalityAnalysisResult>;
+export declare function describeEmotionalStateViaLLM(state: EmotionEngineState, opts: AnalyzerOptions): Promise<EmotionalStateResult>;