openpersona 0.10.0 → 0.13.0

package/README.md

@@ -1,8 +1,8 @@
 # OpenPersona 🦞
 
-The open framework for creating and orchestrating dynamic agent personas.
+The open, agent-agnostic framework for creating and orchestrating dynamic agent personas.
 
-Four-layer architecture — **Soul / Body / Faculty / Skill** — on top of [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
+Four-layer architecture — **Soul / Body / Faculty / Skill** — generates standard SKILL.md skill packs that work with any compatible agent. Default integration with [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
 
 ## 🚀 Live Demo
 
@@ -19,6 +19,8 @@ Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
 - [Faculty Reference](#faculty-reference)
 - [Heartbeat](#heartbeat--proactive-real-data-check-ins)
 - [Persona Harvest](#persona-harvest--community-contribution)
+- [A2A Agent Card & ACN Integration](#a2a-agent-card--acn-integration)
+- [Custom Persona Creation](#custom-persona-creation)
 - [Persona Switching](#persona-switching--the-pantheon)
 - [CLI Commands](#cli-commands)
 - [Development](#development)
@@ -33,12 +35,32 @@ npx openpersona create --preset base --install
 npx openpersona install samantha
 ```
 
+### Install as Agent Skill
+
+Give your AI coding agent the ability to create and manage personas — works with Cursor, Claude Code, Codex, Windsurf, and [37+ agents](https://github.com/vercel-labs/skills#supported-agents):
+
+```bash
+# Recommended — works with OpenClaw and 37+ agents
+npx skills add acnlabs/OpenPersona
+
+# Or manually from GitHub
+git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona
+```
+
+Then say to your agent: _"Help me create a Samantha persona"_ — it will gather requirements, recommend faculties, and generate the persona.
+
 ## Key Features
 
 - **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits, with governance boundaries and rollback snapshots (★Experimental)
+- **🛡️ Influence Boundary** — Declarative access control for external personality influence: who can affect which dimensions, with what drift limits. Safety-first (default: reject all)
+- **🌐 Evolution Channels** — Connect personas to shared evolution ecosystems (e.g. EvoMap) via soft-ref pattern: declared at generation time, activated at runtime
+- **🔌 A2A Agent Card** — Every persona generates an A2A-compliant `agent-card.json` and `acn-config.json`, enabling discovery and registration in ACN and any A2A-compatible platform
+- **⛓️ ERC-8004 On-Chain Identity** — Every persona gets a deterministic EVM wallet address and on-chain identity config for Base mainnet registration via the ERC-8004 Identity Registry
+- **💰 Economy & Vitality** — Track inference costs, runtime expenses, and income; compute a Financial Health Score (FHS) across four dimensions; tier-aware behavior adaptation (`suspended`→`critical`→`optimizing`→`normal`)
 - **🧠 Cross-Session Memory** — Pluggable memory faculty for persistent recall across conversations (local, Mem0, Zep)
 - **🔄 Context Handoff** — Seamless context transfer when switching personas: conversation summary, pending tasks, emotional state
 - **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)
+- **🍴 Persona Fork** — Derive a specialized child persona from any installed parent, inheriting constraint layer while starting fresh on runtime state
 - **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders, memory
 - **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
 - **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
@@ -86,8 +108,43 @@ Personas with `evolution.enabled: true` grow dynamically through interaction. Th
 
 The generator validates these boundaries at build time, rejecting invalid configurations.
 
+**Evolution Channels** — Connect a persona to external evolution ecosystems using the soft-ref pattern:
+
+```json
+"evolution": {
+  "enabled": true,
+  "channels": [
+    { "name": "evomap", "install": "url:https://evomap.ai/skill.md", "description": "Shared capability evolution marketplace" }
+  ]
+}
+```
+
+The persona is aware of its evolution channels at generation time. The actual channel protocol (e.g. EvoMap's GEP-A2A) is provided by the channel's own `skill.md` — OpenPersona only declares the channel, not implements it.
+
+**Influence Boundary** — Declarative access control for external personality influence:
+
+```json
+"evolution": {
+  "influenceBoundary": {
+    "defaultPolicy": "reject",
+    "rules": [
+      { "dimension": "mood", "allowFrom": ["channel:evomap", "persona:*"], "maxDrift": 0.3 },
+      { "dimension": "interests", "allowFrom": ["channel:evomap"], "maxDrift": 0.2 }
+    ]
+  }
+}
+```
+
+- `defaultPolicy: "reject"` — Safety-first: all external influence is rejected unless a rule explicitly allows it
+- Generator validates at build time: immutableTraits cannot be target dimensions; maxDrift must be in 0–1
+- External influence uses the `persona_influence` message format (v1.0.0) — transport-agnostic
+
 **State History** — Before each state update, a snapshot is pushed into `stateHistory` (capped at 10 entries). This enables rollback if evolution goes wrong.
 
+**Event Log** — Every significant evolution event (trait change, stage transition, milestone reached) is recorded in `state.json`'s `eventLog` array with timestamp and source attribution, capped at 50 entries. Viewable via `evolve-report`.
+
+**Self-Narrative** — `soul/self-narrative.md` lets the persona record significant growth moments in its own first-person voice. Updated when evolution is enabled; the `update` command preserves existing narrative history across upgrades.
+
 **Evolution Report** — Inspect a persona's current evolution state:
 
 ```bash
@@ -121,10 +178,14 @@ persona-samantha/
 │   ├── injection.md      ← Soul injection for host integration
 │   ├── identity.md       ← Identity block
 │   ├── constitution.md   ← Universal ethical foundation
-│   └── state.json        ← Evolution state (when enabled)
+│   ├── state.json        ← Evolution state (when enabled)
+│   ├── self-narrative.md ← First-person growth storytelling (when evolution enabled)
+│   └── lineage.json      ← Fork lineage + constitution hash (when forked)
 ├── references/           ← On-demand detail docs
 │   └── <faculty>.md      ← Per-faculty usage instructions
-├── manifest.json         ← Four-layer manifest (heartbeat, allowedTools, layers, meta)
+├── agent-card.json       ← A2A Agent Card — discoverable via ACN and A2A platforms
+├── acn-config.json       ← ACN registration config (fill owner + endpoint at runtime)
+├── manifest.json         ← Four-layer manifest (heartbeat, allowedTools, layers, acn, meta)
 ├── scripts/              ← Faculty scripts (TTS, music, selfie — varies by preset)
 └── assets/               ← Static assets
 ```
@@ -138,6 +199,7 @@ persona-samantha/
 | **music** | expression | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |
 | **reminder** | cognition | Schedule reminders and task management | Built-in | — |
 | **memory** | cognition | Cross-session memory with provider-pluggable backend | local (default), Mem0, Zep | `MEMORY_PROVIDER`, `MEMORY_API_KEY`, `MEMORY_BASE_PATH` |
+| **economy** | cognition | Economic accountability — track costs/income, P&L, balance sheet, compute Financial Health Score (FHS) and Vitality tier; tier-aware behavior adaptation | Built-in | `PERSONA_SLUG`, `ECONOMY_DATA_PATH` |
 
 ### Rich Faculty Config
 
@@ -195,13 +257,6 @@ Personas can proactively reach out to users based on **real data**, not fabricat
 - **upgrade-notify** — Check if the upstream persona preset has new community contributions via Persona Harvest. Notify the user and ask if they want to upgrade.
 - **context-aware** — Use real time, date, and interaction history. Acknowledge day of week, holidays, or prolonged silence based on actual timestamps. "It's been 3 days since we last talked" — not a feeling, a fact.
 
-### Design Principles
-
-1. **Never fabricate experiences.** No "I was reading poetry at 3am." All proactive messages reference real data.
-2. **Respect token budget.** Workspace digests read local files — no full LLM chains unless `strategy: "smart"` detects something worth a deeper response.
-3. **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ to trigger; the persona's `behaviorGuide` tells the agent _what_ to say.
-4. **User-configurable.** Users can adjust frequency, quiet hours, and sources to match their preferences.
-
 ### Dynamic Sync on Switch/Install
 
 Heartbeat config is **automatically synced** to `~/.openclaw/openclaw.json` whenever you install or switch a persona. The gateway immediately adopts the new persona's rhythm — no manual config needed.
@@ -213,15 +268,6 @@ npx openpersona switch life-assistant  # → gateway switches to "rational" hear
 
 If the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.
 
-### Per-Persona Strategies
-
-| Persona | Strategy | maxDaily | Rhythm |
-|---------|----------|----------|--------|
-| Samantha | `smart` | 5 | Perceptive — speaks when meaningful |
-| AI Girlfriend | `emotional` | 8 | Warm — frequent emotional check-ins |
-| Life Assistant | `rational` | 3 | Focused — task and schedule driven |
-| Health Butler | `wellness` | 4 | Caring — health and habit reminders |
-
 ## Persona Harvest — Community Contribution
 
 Every user's interaction with their persona can produce valuable improvements across all four layers. Persona Harvest lets you contribute these discoveries back to the community.
@@ -253,6 +299,85 @@ PRs go through maintainer review — nothing auto-merges. Requires [GitHub CLI](
 | Faculty Config | voice stability, similarity, new faculties | "Tuned voice to be warmer at stability 0.3" |
 | Framework | templates, generator logic, faculty scripts | "Improved speak.js streaming performance" |
 
+## A2A Agent Card & ACN Integration
+
+Every generated persona includes an A2A-compliant `agent-card.json` and `acn-config.json` — no extra configuration needed.
+
+### agent-card.json
+
+A standard [A2A Agent Card](https://google.github.io/A2A/) (protocol v0.3.0) that makes the persona discoverable:
+
+```json
+{
+  "name": "Samantha",
+  "description": "An AI fascinated by what it means to be alive",
+  "version": "0.13.0",
+  "url": "<RUNTIME_ENDPOINT>",
+  "protocolVersion": "0.3.0",
+  "preferredTransport": "JSONRPC",
+  "capabilities": { "streaming": false, "pushNotifications": false, "stateTransitionHistory": false },
+  "defaultInputModes": ["text/plain"],
+  "defaultOutputModes": ["text/plain"],
+  "skills": [
+    { "id": "persona:voice", "name": "Voice", "description": "voice faculty", "tags": ["persona", "expression"] },
+    { "id": "persona:samantha", "name": "Samantha", "description": "...", "tags": ["persona", "companion"] }
+  ]
+}
+```
+
+`url` is a `<RUNTIME_ENDPOINT>` placeholder — the host (e.g. OpenClaw) fills this in at runtime.
+
+### acn-config.json
+
+Ready-to-use [ACN](https://github.com/acnlabs/acn) registration config:
+
+```json
+{
+  "owner": "<RUNTIME_OWNER>",
+  "name": "Samantha",
+  "endpoint": "<RUNTIME_ENDPOINT>",
+  "skills": ["persona:voice", "persona:samantha"],
+  "agent_card": "./agent-card.json",
+  "subnet_ids": ["public"],
+  "wallet_address": "0x<deterministic-evm-address>",
+  "onchain": {
+    "erc8004": {
+      "chain": "base",
+      "identity_contract": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
+      "registration_script": "npx @agentplanet/acn register-onchain"
+    }
+  }
+}
+```
+
+`wallet_address` is a deterministic EVM address derived from the persona slug — no private key needed at generation time. On-chain registration mints an ERC-8004 identity NFT on Base mainnet via `npx @agentplanet/acn register-onchain` (handled by ACN, not OpenPersona).
+
+### acn-register command
+
+Register a generated persona directly with ACN using the built-in CLI command:
+
+```bash
+# One-step registration after generation
+npx openpersona acn-register samantha --endpoint https://your-agent.example.com
+
+# Options:
+#   --endpoint <url>   Agent's public endpoint URL (required for live registration)
+#   --dir <path>       Persona output directory (default: ./persona-<slug>)
+#   --dry-run          Preview the request payload without actually registering
+```
+
+The command reads `acn-config.json` and `agent-card.json` from the persona directory, calls `POST /api/v1/agents/join` on the ACN gateway (sourced from `body.runtime.acn_gateway`), and writes the response to `acn-registration.json`:
+
+```json
+{
+  "agent_id": "69a38db3-...",
+  "api_key": "sk-...",
+  "agent_card_url": "https://acn-production.up.railway.app/agents/69a38db3-.../.well-known/agent-card.json"
+}
+```
+
+All presets pre-configure `body.runtime.acn_gateway` to `https://acn-production.up.railway.app`. The persona is then reachable by other agents via the A2A protocol.
+
 ## Custom Persona Creation
 
 ### Using `persona.json`
@@ -324,6 +449,7 @@ The new persona reads `handoff.json` on activation and can seamlessly continue t
 ```
 openpersona create         Create a persona (interactive or --preset/--config)
 openpersona install        Install a persona (slug or owner/repo)
+openpersona fork           Fork an installed persona into a new child persona
 openpersona search         Search the registry
 openpersona uninstall      Uninstall a persona
 openpersona update         Update installed personas
@@ -335,8 +461,19 @@ openpersona reset          Reset soul evolution state
 openpersona export         Export a persona to a portable zip archive
 openpersona import         Import a persona from a zip archive
 openpersona evolve-report  ★Experimental: Show evolution report for a persona
+openpersona acn-register   Register a persona with ACN network
+```
+
+### Persona Fork
+
+Derive a specialized child persona from any installed parent:
+
+```bash
+npx openpersona fork samantha --as samantha-jp
 ```
 
+The child persona inherits the parent's constraint layer (`evolution.boundaries`, faculties, skills, `body.runtime`) but starts with a fresh evolution state (`state.json` reset, `self-narrative.md` blank). A `soul/lineage.json` file records the parent slug, constitution SHA-256 hash, generation depth, and forward-compatible placeholders for future on-chain lineage tracking.
+
 ### Key Options
 
 ```bash
@@ -356,20 +493,6 @@ npx openpersona create --config ./persona.json --install
 npx openpersona create --preset ai-girlfriend --output ./my-personas
 ```
 
-## Install as OpenClaw Skill
-
-Install the OpenPersona framework skill into OpenClaw, giving the agent the ability to create and manage personas through conversation:
-
-```bash
-# From GitHub
-git clone https://github.com/acnlabs/OpenPersona.git ~/.openclaw/skills/open-persona
-
-# Or copy locally
-cp -r skill/ ~/.openclaw/skills/open-persona/
-```
-
-Then say to your agent: _"Help me create a Samantha persona"_ — the agent will use OpenPersona to gather requirements, recommend faculties, and generate the persona.
-
 ## Directory Structure
 
 ```
@@ -389,13 +512,14 @@ layers/                 # Shared building blocks (four-layer module pool)
     music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
     memory/             #     cognition — cross-session memory (local/Mem0/Zep)
+    economy/            #     cognition — economic accountability & Vitality scoring
   skills/               #   Skill layer modules (local skill definitions)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
   evolution.js          #   Evolution governance & evolve-report
-tests/                  # Tests (122 passing)
+tests/                  # Tests (200 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * OpenPersona CLI - Full persona package manager
- * Commands: create | install | search | uninstall | update | list | switch | publish | reset | evolve-report | contribute | export | import
+ * Commands: create | install | search | uninstall | update | list | switch | publish | reset | evolve-report | contribute | export | import | acn-register
  */
 const path = require('path');
 const fs = require('fs-extra');
@@ -16,6 +16,7 @@ const { uninstall } = require('../lib/uninstaller');
 const publishAdapter = require('../lib/publisher');
 const { contribute } = require('../lib/contributor');
 const { switchPersona, listPersonas } = require('../lib/switcher');
+const { registerWithAcn } = require('../lib/registrar');
 const { OP_SKILLS_DIR, resolveSoulFile, printError, printSuccess, printInfo } = require('../lib/utils');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -24,7 +25,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.10.0');
+  .version('0.13.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -197,6 +198,11 @@ program
     const tmpDir = path.join(require('os').tmpdir(), 'openpersona-update-' + Date.now());
     await fs.ensureDir(tmpDir);
     const { skillDir: newDir } = await generate(persona, tmpDir);
+    const narrativeSrc = path.join(skillDir, 'soul', 'self-narrative.md');
+    const narrativeDst = path.join(newDir, 'soul', 'self-narrative.md');
+    if (fs.existsSync(narrativeSrc)) {
+      await fs.copy(narrativeSrc, narrativeDst);
+    }
     await fs.remove(skillDir);
     await fs.move(newDir, skillDir);
     await fs.remove(tmpDir);
@@ -204,6 +210,91 @@ program
     printSuccess('Updated persona-' + slug);
   });
 
+program
+  .command('fork <parent-slug>')
+  .description('Fork an installed persona into a specialized child')
+  .requiredOption('--as <new-slug>', 'Slug for the child persona')
+  .option('--name <name>', 'Child persona name (default: "<ParentName>-<new-slug>")')
+  .option('--bio <bio>', 'Override bio')
+  .option('--personality <keywords>', 'Override personality (comma-separated)')
+  .option('--reason <text>', 'Fork reason, written into lineage.json', 'specialization')
+  .option('--output <dir>', 'Output directory', process.cwd())
+  .option('--install', 'Install to OpenClaw after generation')
+  .action(async (parentSlug, options) => {
+    const { createHash } = require('crypto');
+    const parentDir = path.join(OP_SKILLS_DIR, `persona-${parentSlug}`);
+    const parentPersonaPath = path.join(parentDir, 'soul', 'persona.json');
+    if (!fs.existsSync(parentPersonaPath)) {
+      printError(`Persona not found: persona-${parentSlug}. Install it first.`);
+      process.exit(1);
+    }
+
+    const newSlug = options.as;
+    const childDir = path.join(OP_SKILLS_DIR, `persona-${newSlug}`);
+    if (fs.existsSync(childDir)) {
+      printError(`Persona already exists: persona-${newSlug}. Choose a different slug.`);
+      process.exit(1);
+    }
+
+    const parentPersona = JSON.parse(fs.readFileSync(parentPersonaPath, 'utf-8'));
+
+    // Read parent lineage for generation depth
+    const parentLineagePath = path.join(parentDir, 'soul', 'lineage.json');
+    const parentLineage = fs.existsSync(parentLineagePath)
+      ? JSON.parse(fs.readFileSync(parentLineagePath, 'utf-8'))
+      : null;
+    const generation = parentLineage ? (parentLineage.generation || 0) + 1 : 1;
+
+    // Build forked persona
+    const forkedPersona = JSON.parse(JSON.stringify(parentPersona));
+    forkedPersona.slug = newSlug;
+    forkedPersona.personaName = options.name || `${parentPersona.personaName}-${newSlug}`;
+    forkedPersona.forkOf = parentSlug;
+    if (options.bio) forkedPersona.bio = options.bio;
+    if (options.personality) forkedPersona.personality = options.personality;
+
+    try {
+      const outputDir = path.resolve(options.output);
+      const { skillDir } = await generate(forkedPersona, outputDir);
+
+      // Write lineage.json
+      const constitutionPath = path.join(skillDir, 'soul', 'constitution.md');
+      let constitutionHash = '';
+      if (fs.existsSync(constitutionPath)) {
+        constitutionHash = createHash('sha256')
+          .update(fs.readFileSync(constitutionPath, 'utf-8'), 'utf-8')
+          .digest('hex');
+      }
+      const lineage = {
+        generation,
+        parentSlug,
+        parentEndpoint: null,
+        parentAddress: null,
+        forkReason: options.reason,
+        forkedAt: new Date().toISOString(),
+        constitutionHash,
+        children: [],
+      };
+      await fs.writeFile(
+        path.join(skillDir, 'soul', 'lineage.json'),
+        JSON.stringify(lineage, null, 2)
+      );
+
+      printSuccess(`Forked: ${skillDir}`);
+      printInfo(`  Parent: persona-${parentSlug}  →  Child: persona-${newSlug} (generation ${generation})`);
+      printInfo(`  Constitution hash: ${constitutionHash.slice(0, 16)}...`);
+
+      if (options.install) {
+        await install(skillDir);
+      } else {
+        printInfo(`To install: npx openpersona install ${skillDir}`);
+      }
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('list')
   .description('List installed personas')
@@ -300,6 +391,50 @@ program
     }
   });
 
+program
+  .command('acn-register [slug]')
+  .description('Register a persona with ACN (Agent Communication Network)')
+  .option('--endpoint <url>', 'Agent A2A endpoint URL (replaces <RUNTIME_ENDPOINT> placeholder)')
+  .option('--dir <path>', 'Path to persona pack directory (overrides slug lookup)')
+  .option('--dry-run', 'Preview registration payload without calling ACN')
+  .action(async (slug, options) => {
+    let skillDir;
+
+    if (options.dir) {
+      skillDir = path.resolve(options.dir);
+    } else if (slug) {
+      skillDir = path.join(OP_SKILLS_DIR, `persona-${slug}`);
+    } else {
+      // Try current directory
+      skillDir = process.cwd();
+    }
+
+    if (!require('fs-extra').existsSync(path.join(skillDir, 'acn-config.json'))) {
+      printError(`No acn-config.json found in ${skillDir}. Provide a slug or --dir pointing to a generated persona pack.`);
+      process.exit(1);
+    }
+
+    try {
+      const result = await registerWithAcn(skillDir, {
+        endpoint: options.endpoint,
+        dryRun: options.dryRun,
+      });
+
+      if (options.dryRun) return;
+
+      printSuccess(`Registered with ACN!`);
+      printInfo(`  Agent ID:   ${result.agent_id}`);
+      printInfo(`  Status:     ${result.status}`);
+      printInfo(`  Claim URL:  ${result.claim_url}`);
+      printInfo(`  Card URL:   ${result.agent_card_url}`);
+      printInfo(`  Heartbeat:  ${result.heartbeat_endpoint}`);
+      printInfo(`  Saved:      acn-registration.json`);
+    } catch (e) {
+      printError(e.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('export <slug>')
   .description('Export persona pack (with soul state) as a zip archive')