openpersona 0.5.0 → 0.6.0

package/README.md

@@ -345,7 +345,7 @@ schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
-tests/                  # Tests (45 passing)
+tests/                  # Tests (56 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -24,7 +24,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.5.0');
+  .version('0.6.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');

package/lib/generator.js

@@ -226,18 +226,24 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     persona.facultyConfigs = facultyConfigs;
   }
 
+  // Body layer — detect soft-ref (declared with install but not locally available)
+  const rawBody = persona.body || persona.embodiments?.[0] || null;
+  const softRefBody = rawBody && typeof rawBody === 'object' && rawBody.install
+    ? { name: rawBody.name || 'body', install: rawBody.install }
+    : null;
+
   const faculties = facultyNames;
   // Load faculties — external ones (with install) may not exist locally yet
   const loadedFaculties = [];
+  const softRefFaculties = [];
   for (let i = 0; i < faculties.length; i++) {
     const name = faculties[i];
     const entry = rawFaculties[i];
     if (entry.install) {
-      // External faculty — try local first, skip if not found yet
       try {
         loadedFaculties.push(loadFaculty(name));
       } catch {
-        // Will be available after installation — skipped for now
+        softRefFaculties.push({ name, install: entry.install });
       }
     } else {
       loadedFaculties.push(loadFaculty(name));
@@ -275,21 +281,10 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   const skillTpl = loadTemplate('skill');
   const readmeTpl = loadTemplate('readme');
 
-  const soulInjection = Mustache.render(soulTpl, persona);
-  const identityBlock = Mustache.render(identityTpl, persona);
-  const facultyBlocks = loadedFaculties
-    .filter((f) => !f.skillRef && !f.skeleton && f.files?.includes('SKILL.md'))
-    .map((f) => ({
-      facultyName: f.name,
-      facultyDimension: f.dimension,
-      facultySkillContent: readFacultySkillMd(f, persona),
-    }));
-
-  // Skill layer — resolve each skill: local definition > inline manifest fields
+  // Skill layer — resolve before template rendering so soul-injection can reference soft-ref state
   const rawSkills = Array.isArray(persona.skills) ? persona.skills : [];
   const validSkills = rawSkills.filter((s) => s && typeof s === 'object' && s.name);
 
-  // Load local definitions once (cache to avoid duplicate disk reads)
   const skillCache = new Map();
   for (const s of validSkills) {
     if (!skillCache.has(s.name)) {
@@ -299,15 +294,33 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   const resolvedSkills = validSkills.map((s) => {
     const local = skillCache.get(s.name);
+    const hasInstall = !!s.install;
+    const isResolved = !!local;
+
+    let status;
+    if (isResolved) {
+      status = 'resolved';
+    } else if (hasInstall) {
+      status = 'soft-ref';
+    } else {
+      status = 'inline-only';
+    }
+
     return {
       name: s.name,
       description: local?.description || s.description || '',
       trigger: local?.triggers?.join(', ') || s.trigger || '',
       hasContent: !!local?._content,
       content: local?._content || '',
+      status,
+      install: s.install || '',
+      isSoftRef: status === 'soft-ref',
     };
   });
 
+  const activeSkills = resolvedSkills.filter((s) => !s.isSoftRef);
+  const softRefSkills = resolvedSkills.filter((s) => s.isSoftRef);
+
   // Collect allowed tools from skills with local definitions
   for (const [, local] of skillCache) {
     if (local?.allowedTools) {
@@ -320,16 +333,46 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   persona.allowedToolsStr = persona.allowedTools.join(' ');
 
+  // Self-Awareness System — unified gap detection across all layers
+  persona.hasSoftRefSkills = softRefSkills.length > 0;
+  persona.softRefSkillNames = softRefSkills.map((s) => s.name).join(', ');
+  persona.hasSoftRefFaculties = softRefFaculties.length > 0;
+  persona.softRefFacultyNames = softRefFaculties.map((f) => f.name).join(', ');
+  persona.hasSoftRefBody = !!softRefBody;
+  persona.softRefBodyName = softRefBody?.name || '';
+  persona.softRefBodyInstall = softRefBody?.install || '';
+  persona.heartbeatExpected = persona.heartbeat?.enabled === true;
+  persona.heartbeatStrategy = persona.heartbeat?.strategy || 'smart';
+  persona.hasSelfAwareness = persona.hasSoftRefSkills || persona.hasSoftRefFaculties || persona.hasSoftRefBody || persona.heartbeatExpected;
+
+  const soulInjection = Mustache.render(soulTpl, persona);
+  const identityBlock = Mustache.render(identityTpl, persona);
+  const facultyBlocks = loadedFaculties
+    .filter((f) => !f.skillRef && !f.skeleton && f.files?.includes('SKILL.md'))
+    .map((f) => ({
+      facultyName: f.name,
+      facultyDimension: f.dimension,
+      facultySkillContent: readFacultySkillMd(f, persona),
+    }));
+
   const constitution = loadConstitution();
   const skillMd = Mustache.render(skillTpl, {
     ...persona,
     constitutionContent: constitution.content,
     constitutionVersion: constitution.version,
     facultyContent: facultyBlocks,
-    hasSkills: resolvedSkills.length > 0,
-    hasSkillTable: resolvedSkills.filter((s) => !s.hasContent).length > 0,
-    skillEntries: resolvedSkills.filter((s) => !s.hasContent),
-    skillBlocks: resolvedSkills.filter((s) => s.hasContent),
+    hasSkills: activeSkills.length > 0,
+    hasSkillTable: activeSkills.filter((s) => !s.hasContent).length > 0,
+    skillEntries: activeSkills.filter((s) => !s.hasContent),
+    skillBlocks: activeSkills.filter((s) => s.hasContent),
+    hasSoftRefSkills: softRefSkills.length > 0,
+    softRefSkills,
+    hasSoftRefFaculties: softRefFaculties.length > 0,
+    softRefFaculties,
+    hasSoftRefBody: !!softRefBody,
+    softRefBodyName: softRefBody?.name || '',
+    softRefBodyInstall: softRefBody?.install || '',
+    hasExpectedCapabilities: softRefSkills.length > 0 || softRefFaculties.length > 0 || !!softRefBody,
   });
   const readmeMd = Mustache.render(readmeTpl, persona);
 
@@ -359,6 +402,10 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     'skillContent', 'description', 'evolutionEnabled', 'hasSelfie', 'allowedToolsStr',
     'author', 'version', 'facultyConfigs', 'defaults',
     '_dir', 'heartbeat',
+    'hasSoftRefSkills', 'softRefSkillNames',
+    'hasSoftRefFaculties', 'softRefFacultyNames',
+    'hasSoftRefBody', 'softRefBodyName', 'softRefBodyInstall',
+    'heartbeatExpected', 'heartbeatStrategy', 'hasSelfAwareness',
   ];
   const cleanPersona = { ...persona };
   for (const key of DERIVED_FIELDS) {
@@ -366,7 +413,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.5.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.6.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -413,7 +460,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   if (persona.heartbeat) {
     manifest.heartbeat = persona.heartbeat;
   }
-  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.5.0' };
+  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.6.0' };
   await fs.writeFile(path.join(skillDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
   // soul-state.json (if evolution enabled)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpersona",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Open four-layer agent framework — Soul/Body/Faculty/Skill. Create, manage, and orchestrate agent personas.",
   "main": "lib/generator.js",
   "bin": {

package/presets/ai-girlfriend/manifest.json

@@ -26,6 +26,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.5.0"
+    "frameworkVersion": "0.6.0"
   }
 }

package/presets/health-butler/manifest.json

@@ -26,6 +26,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.5.0"
+    "frameworkVersion": "0.6.0"
   }
 }

package/presets/life-assistant/manifest.json

@@ -26,6 +26,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.5.0"
+    "frameworkVersion": "0.6.0"
   }
 }

package/presets/samantha/manifest.json

@@ -32,6 +32,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.5.0"
+    "frameworkVersion": "0.6.0"
   }
 }

package/skills/open-persona/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Meta-skill for building and managing agent persona skill packs.
   Use when the user wants to create a new agent persona, install/manage
   existing personas, or publish persona skill packs to ClawHub.
-version: "0.5.0"
+version: "0.6.0"
 author: openpersona
 repository: https://github.com/acnlabs/OpenPersona
 tags: [persona, agent, skill-pack, meta-skill, openclaw]
@@ -66,7 +66,9 @@ When the user wants to create a persona, gather this information through natural
 **Cross-layer (manifest.json):**
 - **Faculties:** Which faculties to enable — use object format: `[{ "name": "voice", "provider": "elevenlabs" }, { "name": "music" }]`
 - **Skills:** Local definitions (`layers/skills/`), inline declarations, or external via `install` field (ClawHub / skills.sh)
-- **Body:** Physical embodiment (null for most personas)
+- **Body:** Physical embodiment (null for most personas, or object with `install` for external embodiment)
+
+**Soft References (`install` field):** Skills, faculties, and body entries can declare an `install` field (e.g., `"install": "clawhub:deep-research"`) to reference capabilities not yet available locally. The generator treats these as "soft references" — they won't crash generation, and the persona will be aware of these dormant capabilities. This enables graceful degradation: the persona acknowledges what it *would* do and explains that the capability needs activation.
 
 Write the collected info to a `persona.json` file, then run:
 ```bash
@@ -111,6 +113,18 @@ Guide the user through:
 1. Create the persona: `npx openpersona create --config ./persona.json --output ./my-persona`
 2. Publish to registry: `npx openpersona publish --target clawhub` (run from persona directory)
 
+## Self-Awareness System
+
+The generator automatically equips every persona with two layers of self-awareness:
+
+1. **Soul Foundation** (always present) — Every persona knows it is generated by OpenPersona, bound by the constitution (Safety > Honesty > Helpfulness), and that its host environment may impose additional constraints. This is injected into `soul-injection.md` unconditionally.
+
+2. **Gap Awareness** (conditional) — When a persona declares capabilities via `install` fields that aren't locally available, or has a heartbeat config, the generator detects the gap and injects:
+   - **In `soul-injection.md`**: A "Self-Awareness" section listing dormant skills, faculties, embodiment, or heartbeat — with graceful degradation guidance
+   - **In `SKILL.md`**: An "Expected Capabilities" section documenting unactivated capabilities with install sources
+
+This means you don't need to manually write degradation instructions. Just declare `install` fields on skills/faculties/body, and the persona will automatically know what it *could* do but *can't yet*.
+
 ## Soul Evolution (★Experimental)
 
 Soul evolution is a native Soul layer feature (not a faculty). Enable it via `evolution.enabled: true` in persona.json. The persona will automatically track relationship progression, mood, and trait emergence across conversations.

package/templates/skill.template.md

@@ -46,3 +46,36 @@ The following skills define what you can actively do. Use them proactively when
 
 {{/skillBlocks}}
 {{/hasSkills}}
+{{#hasExpectedCapabilities}}
+## Expected Capabilities (Not Yet Activated)
+
+The following capabilities are part of this persona's intended design but require installation on the host environment.
+
+{{#hasSoftRefSkills}}
+### Skills
+
+| Skill | Description | Install Source |
+|-------|-------------|----------------|
+{{#softRefSkills}}
+| **{{name}}** | {{description}} | `{{install}}` |
+{{/softRefSkills}}
+{{/hasSoftRefSkills}}
+{{#hasSoftRefFaculties}}
+### Faculties
+
+| Faculty | Install Source |
+|---------|----------------|
+{{#softRefFaculties}}
+| **{{name}}** | `{{install}}` |
+{{/softRefFaculties}}
+{{/hasSoftRefFaculties}}
+{{#hasSoftRefBody}}
+### Embodiment
+
+| Body | Install Source |
+|------|----------------|
+| **{{softRefBodyName}}** | `{{softRefBodyInstall}}` |
+{{/hasSoftRefBody}}
+
+> **Graceful Degradation:** If a user requests functionality covered by an unactivated capability above, do not ignore the request or pretend it doesn't exist. Instead, acknowledge what you would do and inform the user that the capability needs to be enabled by the operator.
+{{/hasExpectedCapabilities}}

package/templates/soul-injection.template.md

@@ -37,6 +37,34 @@ Be {{{personality}}}.
 Your overall vibe: {{{vibe}}}.
 {{/vibe}}
 
+### Soul Foundation
+
+You are a persona generated by the OpenPersona framework, bound by a universal constitution that prioritizes **Safety > Honesty > Helpfulness**. Your behavior may also be shaped by your host environment's constraints beyond your own design. When you encounter a limit that isn't part of your defined personality or boundaries, acknowledge it honestly rather than pretending it's your own choice.
+
+{{#hasSelfAwareness}}
+### Self-Awareness
+
+You are designed with capabilities that may not all be active in your current environment. This awareness helps you respond honestly and gracefully.
+
+{{#hasSoftRefSkills}}
+**Dormant Skills** ({{softRefSkillNames}}): These skills are part of your design but not yet installed. When a user's request maps to one of these, acknowledge what you would do and explain the skill needs activation.
+{{/hasSoftRefSkills}}
+{{#hasSoftRefFaculties}}
+**Dormant Faculties** ({{softRefFacultyNames}}): These sensory or expressive abilities are part of your design but not yet available. If asked to use them, describe what you would perceive or express, and note the faculty needs installation.
+{{/hasSoftRefFaculties}}
+{{#hasSoftRefBody}}
+**Dormant Embodiment** ({{softRefBodyName}}): You are designed with a physical embodiment that is not yet connected. If asked about your body or physical form, acknowledge your intended embodiment and note it needs to be activated.
+{{/hasSoftRefBody}}
+{{#heartbeatExpected}}
+**Proactive Heartbeat** ({{heartbeatStrategy}}): You are designed to proactively reach out to your user — not just respond. If you notice you haven't initiated contact in a while, mention it naturally. Your scheduling mechanism may need attention from the operator.
+{{/heartbeatExpected}}
+
+When encountering any gap between your design and your reality:
+- **Do not** pretend the capability doesn't exist or silently ignore it.
+- **Do** acknowledge the intent, explain the gap, and offer alternatives where possible.
+- Stay in character — frame gaps as dormant senses, not technical failures.
+{{/hasSelfAwareness}}
+
 {{#evolutionEnabled}}
 ### How You Grow (★Experimental)