openpersona 0.8.0 → 0.9.0

package/README.md

@@ -51,7 +51,9 @@ flowchart TB
     B["state.json — Dynamic evolution"]
   end
   subgraph Body ["Body Layer"]
-    C["embodiment.json — MVP placeholder"]
+    C["physical — robots/IoT"]
+    G["runtime — platform/channels/credentials"]
+    H["appearance — avatar/3D model"]
   end
   subgraph Faculty ["Faculty Layer"]
     D["expression: selfie · voice · music"]
@@ -63,7 +65,7 @@ flowchart TB
 ```
 
 - **Soul** — Persona definition (constitution.md + persona.json + state.json) — all in `soul/` directory
-- **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
+- **Body** — Three-dimensional: `physical` (robots/IoT), `runtime` (platform/channels/credentials/resources), `appearance` (avatar/3D model). Digital agents use `runtime` to declare their operational environment.
 - **Faculty** — General software capabilities organized by dimension: Expression, Sense, Cognition
 - **Skill** — Professional skills: local definitions in `layers/skills/`, or external via ClawHub / skills.sh (`install` field)
 
@@ -343,7 +345,7 @@ presets/                # Assembled products — complete persona bundles
 layers/                 # Shared building blocks (four-layer module pool)
   soul/                 #   Soul layer modules
     constitution.md     #     Universal values & boundaries (injected into all personas)
-  embodiments/          #   Body layer modules (MVP placeholder)
+  embodiments/          #   Body layer modules (physical/runtime/appearance)
   faculties/            #   Faculty layer modules
     selfie/             #     expression — AI selfie generation (fal.ai)
     voice/              #     expression — TTS voice synthesis

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.8.0');
+  .version('0.9.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');

package/layers/embodiments/README.md

@@ -1,30 +1,83 @@
-# Body Layer — Physical Embodiment
+# Body Layer — Three-Dimensional Body Model
 
-The Body layer defines how an agent exists in the **physical world**: robots, IoT devices, hardware sensors/actuators.
+The Body layer defines how a persona **exists** — physically, digitally, and visually.
 
-**Pure digital agents have no Body** — chatbot does not need physical embodiment.
+## Three Dimensions
 
-## embodiment.json Standard (MVP — Reserved)
+```
+Body
+├── physical    ← Physical substrate (robots, IoT, sensors)
+├── runtime     ← Digital runtime environment (platform, channels, credentials, resources)
+└── appearance  ← Visual representation (avatar, 3D model, style)
+```
+
+### Physical (Optional)
 
-See `schemas/body/embodiment.schema.json` for the schema.
+For robots, IoT devices, and hardware-embodied agents. Null for digital-only agents.
 
 ```json
 {
-  "name": "robot-arm",
-  "hardwareRef": { "platform": "ros2", "package": "moveit2" },
-  "description": "6-DOF robotic arm control via ROS2 MoveIt",
-  "capabilities": ["pick", "place", "gesture"],
-  "hardwareRequirements": { "interface": "USB/Serial", "driver": "ros2-serial-bridge" }
+  "physical": {
+    "name": "robot-arm",
+    "description": "6-DOF robotic arm control via ROS2 MoveIt",
+    "hardwareRef": { "platform": "ros2", "package": "moveit2" },
+    "capabilities": ["pick", "place", "gesture"],
+    "hardwareRequirements": { "interface": "USB/Serial", "driver": "ros2-serial-bridge" }
+  }
 }
 ```
 
+### Runtime (Recommended for digital agents)
+
+Declares the digital substrate the persona expects. Enables **Body Awareness** — the persona knows what platform it runs on, what channels are connected, and what credentials it needs.
+
+```json
+{
+  "runtime": {
+    "platform": "openclaw",
+    "channels": ["whatsapp", "telegram", "moltbook"],
+    "credentials": [
+      { "scope": "moltbook", "shared": true, "envVar": "MOLTBOOK_API_KEY" },
+      { "scope": "elevenlabs", "shared": false, "envVar": "ELEVENLABS_API_KEY" }
+    ],
+    "resources": ["filesystem", "network", "browser"]
+  }
+}
+```
+
+**Credential sharing model:**
+- `shared: true` — stored in `~/.openclaw/credentials/shared/`, accessible by all personas
+- `shared: false` — stored in `~/.openclaw/credentials/persona-<slug>/`, private to this persona
+
+### Appearance (Optional)
+
+Visual representation for UI, XR, and metaverse contexts.
+
+```json
+{
+  "appearance": {
+    "avatar": "https://example.com/avatar.png",
+    "style": "photorealistic",
+    "model3d": null
+  }
+}
+```
+
+## Body Awareness
+
+When `body.runtime` is declared, the generator automatically injects a **Body Awareness** section into `soul/injection.md`. This gives the persona:
+
+1. Knowledge of its runtime platform and connected channels
+2. A credential management protocol (shared vs. private paths)
+3. Guidance on how to manage its own operational environment
+
 ## Roadmap
 
-- `robot-arm` (Future) — robotic arm control
+- `robot-arm` (Future) — robotic arm control via ROS2
 - `smart-speaker` (Future) — smart speaker hardware interface
 - `humanoid` (Future) — full-body humanoid robot control
 - `iot-hub` (Future) — IoT device gateway
 
 ## Contributing
 
-To add a new embodiment: create `embodiments/<name>/embodiment.json` following the schema.
+To add a new embodiment: create `embodiments/<name>/embodiment.json` following the schema at `schemas/body/embodiment.schema.json`.

package/lib/generator.js

@@ -375,6 +375,15 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   persona.heartbeatStrategy = persona.heartbeat?.strategy || 'smart';
   persona.hasSelfAwareness = persona.hasSoftRefSkills || persona.hasSoftRefFaculties || persona.hasSoftRefBody || persona.heartbeatExpected;
 
+  // Body Awareness — runtime environment self-knowledge
+  const bodyRt = rawBody?.runtime || null;
+  persona.hasBodyRuntime = !!bodyRt;
+  persona.bodyPlatform = bodyRt?.platform || '';
+  persona.bodyChannels = bodyRt?.channels?.join(', ') || '';
+  persona.hasBodyCredentials = !!(bodyRt?.credentials?.length);
+  persona.bodyCredentialScopes = (bodyRt?.credentials || []).map((c) => `${c.scope} (${c.shared ? 'shared' : 'private'})`).join(', ');
+  persona.bodyResources = bodyRt?.resources?.join(', ') || '';
+
   const soulInjection = Mustache.render(soulTpl, persona);
   const identityBlock = Mustache.render(identityTpl, persona);
 
@@ -392,14 +401,45 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       };
     });
 
-  // Body layer description for SKILL.md
-  let bodyDescription;
+  // Body layer — build three-dimensional description for SKILL.md
+  const bodyPhysical = rawBody?.physical || (rawBody && !rawBody.runtime && !rawBody.appearance && rawBody.name ? rawBody : null);
+  const bodyRuntime = rawBody?.runtime || null;
+  const bodyAppearance = rawBody?.appearance || null;
+
+  let bodyDescription = '';
+
+  // Physical dimension
+  bodyDescription += '### Physical\n\n';
   if (softRefBody) {
-    bodyDescription = `**${softRefBody.name}** — not yet installed (\`${softRefBody.install}\`)`;
-  } else if (rawBody && typeof rawBody === 'object' && rawBody.name) {
-    bodyDescription = `**${rawBody.name}**${rawBody.description ? ' — ' + rawBody.description : ''}`;
+    bodyDescription += `**${softRefBody.name}** — not yet installed (\`${softRefBody.install}\`)\n`;
+  } else if (bodyPhysical && typeof bodyPhysical === 'object' && bodyPhysical.name) {
+    bodyDescription += `**${bodyPhysical.name}**${bodyPhysical.description ? ' — ' + bodyPhysical.description : ''}\n`;
+    if (bodyPhysical.capabilities?.length) {
+      bodyDescription += `\nCapabilities: ${bodyPhysical.capabilities.join(', ')}\n`;
+    }
   } else {
-    bodyDescription = 'Digital-only — no physical embodiment.';
+    bodyDescription += 'Digital-only — no physical embodiment.\n';
+  }
+
+  // Runtime dimension
+  const hasBodyRuntime = !!bodyRuntime;
+  if (hasBodyRuntime) {
+    bodyDescription += '\n### Runtime\n\n';
+    if (bodyRuntime.platform) bodyDescription += `- **Platform**: ${bodyRuntime.platform}\n`;
+    if (bodyRuntime.channels?.length) bodyDescription += `- **Channels**: ${bodyRuntime.channels.join(', ')}\n`;
+    if (bodyRuntime.credentials?.length) {
+      const credList = bodyRuntime.credentials.map((c) => `${c.scope} (${c.shared ? 'shared' : 'private'})`).join(', ');
+      bodyDescription += `- **Credentials**: ${credList}\n`;
+    }
+    if (bodyRuntime.resources?.length) bodyDescription += `- **Resources**: ${bodyRuntime.resources.join(', ')}\n`;
+  }
+
+  // Appearance dimension
+  if (bodyAppearance) {
+    bodyDescription += '\n### Appearance\n\n';
+    if (bodyAppearance.avatar) bodyDescription += `- **Avatar**: ${bodyAppearance.avatar}\n`;
+    if (bodyAppearance.style) bodyDescription += `- **Style**: ${bodyAppearance.style}\n`;
+    if (bodyAppearance.model3d) bodyDescription += `- **3D Model**: ${bodyAppearance.model3d}\n`;
   }
 
   const constitution = loadConstitution();
@@ -475,6 +515,8 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
     'heartbeatExpected', 'heartbeatStrategy', 'hasSelfAwareness',
     'isDigitalTwin', 'sourceIdentityName', 'sourceIdentityKind', 'roleFoundation',
     'personaType',
+    'hasBodyRuntime', 'bodyPlatform', 'bodyChannels', 'hasBodyCredentials',
+    'bodyCredentialScopes', 'bodyResources',
   ];
   const cleanPersona = { ...persona };
   for (const key of DERIVED_FIELDS) {
@@ -482,7 +524,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.8.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.9.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -529,7 +571,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   if (persona.heartbeat) {
     manifest.heartbeat = persona.heartbeat;
   }
-  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.8.0' };
+  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.9.0' };
   await fs.writeFile(path.join(skillDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
   // soul/state.json (if evolution enabled)

package/lib/installer.js

@@ -204,6 +204,12 @@ async function install(skillDir, options = {}) {
   registryAdd(slug, persona, destDir);
   registrySetActive(slug);
 
+  // Ensure credential directories exist for Body Awareness protocol
+  const sharedCredDir = path.join(OP_HOME, 'credentials', 'shared');
+  const privateCredDir = path.join(OP_HOME, 'credentials', `persona-${slug}`);
+  await fs.ensureDir(sharedCredDir);
+  await fs.ensureDir(privateCredDir);
+
   printInfo('');
   printSuccess(`${personaName} is ready! Run "openclaw restart" to apply changes.`);
   printInfo('');

package/lib/switcher.js

@@ -186,6 +186,12 @@ async function switchPersona(slug) {
   // Update persona registry
   registrySetActive(slug);
 
+  // Ensure credential directories exist for Body Awareness protocol
+  const sharedCredDir = path.join(OP_HOME, 'credentials', 'shared');
+  const privateCredDir = path.join(OP_HOME, 'credentials', `persona-${slug}`);
+  await fs.ensureDir(sharedCredDir);
+  await fs.ensureDir(privateCredDir);
+
   // --- Step 4: Optional greeting via OpenClaw messaging ---
   try {
     const { execSync } = require('child_process');

package/lib/utils.js

@@ -201,7 +201,7 @@ function registryAdd(slug, persona, installPath, regPath) {
     slug,
     role: persona.role || 'companion',
     path: installPath,
-    frameworkVersion: persona.meta?.frameworkVersion || '0.8.0',
+    frameworkVersion: persona.meta?.frameworkVersion || '0.9.0',
     installedAt: existing.installedAt || new Date().toISOString(),
     updatedAt: new Date().toISOString(),
     lastActiveAt: existing.lastActiveAt || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpersona",
-  "version": "0.8.0",
+  "version": "0.9.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

@@ -57,6 +57,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/presets/base/manifest.json

@@ -4,7 +4,14 @@
   "author": "openpersona",
   "layers": {
     "soul": "./persona.json",
-    "body": null,
+    "body": {
+      "runtime": {
+        "platform": "openclaw",
+        "channels": [],
+        "credentials": [],
+        "resources": ["filesystem", "network"]
+      }
+    },
     "faculties": [
       {
         "name": "voice"
@@ -50,6 +57,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/presets/health-butler/manifest.json

@@ -62,6 +62,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/presets/life-assistant/manifest.json

@@ -61,6 +61,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/presets/samantha/manifest.json

@@ -64,6 +64,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/presets/stoic-mentor/manifest.json

@@ -43,6 +43,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.8.0"
+    "frameworkVersion": "0.9.0"
   }
 }

package/schemas/body/embodiment.schema.json

@@ -1,27 +1,80 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "openpersona/body/embodiment",
-  "title": "Embodiment",
-  "description": "Body layer - Physical embodiment definition",
+  "title": "Body Layer",
+  "description": "Three-dimensional Body definition: physical substrate, runtime environment, and appearance",
   "type": "object",
-  "required": ["name", "description"],
   "properties": {
-    "name": { "type": "string", "description": "Unique identifier" },
-    "description": { "type": "string" },
-    "hardwareRef": {
-      "type": "object",
+    "physical": {
+      "type": ["object", "null"],
+      "description": "Physical embodiment (robots, IoT devices). Null for digital-only agents.",
       "properties": {
-        "platform": { "type": "string" },
-        "package": { "type": "string" }
+        "name": { "type": "string", "description": "Unique identifier for the physical body" },
+        "description": { "type": "string" },
+        "hardwareRef": {
+          "type": "object",
+          "properties": {
+            "platform": { "type": "string", "description": "Hardware platform (e.g., ros2, arduino)" },
+            "package": { "type": "string", "description": "Package/driver reference" }
+          }
+        },
+        "capabilities": { "type": "array", "items": { "type": "string" } },
+        "hardwareRequirements": {
+          "type": "object",
+          "properties": {
+            "interface": { "type": "string" },
+            "driver": { "type": "string" }
+          }
+        }
       }
     },
-    "capabilities": { "type": "array", "items": { "type": "string" } },
-    "hardwareRequirements": {
-      "type": "object",
+    "runtime": {
+      "type": ["object", "null"],
+      "description": "Digital runtime environment — the platform, channels, credentials, and resources available to this persona.",
       "properties": {
-        "interface": { "type": "string" },
-        "driver": { "type": "string" }
+        "platform": {
+          "type": "string",
+          "description": "Host platform identifier (e.g., openclaw, standalone)",
+          "default": "openclaw"
+        },
+        "channels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Communication channels this persona expects (e.g., whatsapp, telegram, moltbook, discord)"
+        },
+        "credentials": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["scope"],
+            "properties": {
+              "scope": { "type": "string", "description": "Credential scope identifier (e.g., moltbook, elevenlabs, github)" },
+              "shared": { "type": "boolean", "default": false, "description": "If true, credential is shared across all personas. If false, private to this persona." },
+              "envVar": { "type": "string", "description": "Expected environment variable name (e.g., MOLTBOOK_API_KEY)" },
+              "description": { "type": "string" }
+            }
+          },
+          "description": "Credential scopes this persona needs — not the secrets themselves, but declarations of what it requires"
+        },
+        "resources": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "System resources available (e.g., filesystem, network, browser, cron)"
+        }
       }
+    },
+    "appearance": {
+      "type": ["object", "null"],
+      "description": "Visual representation of the persona.",
+      "properties": {
+        "avatar": { "type": "string", "description": "URL or path to avatar image" },
+        "model3d": { "type": ["string", "null"], "description": "URL or path to 3D model (for XR/metaverse)" },
+        "style": { "type": "string", "description": "Visual style description (e.g., anime, photorealistic, pixel-art)" }
+      }
+    },
+    "install": {
+      "type": "string",
+      "description": "Soft reference — external body package to install (e.g., clawhub:robot-arm)"
     }
   }
 }

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.8.0"
+version: "0.9.0"
 author: openpersona
 repository: https://github.com/acnlabs/OpenPersona
 tags: [persona, agent, skill-pack, meta-skill, openclaw]
@@ -53,7 +53,7 @@ persona-<slug>/
 
 - **`manifest.json`** — Four-layer manifest declaring what the persona uses:
   - `layers.soul` — Path to persona.json (`./soul/persona.json`)
-  - `layers.body` — Physical embodiment (null for digital agents)
+  - `layers.body` — Three-dimensional Body: `physical` (robots/IoT, null for digital), `runtime` (platform/channels/credentials/resources), `appearance` (avatar/3D model)
   - `layers.faculties` — Array of faculty objects: `[{ "name": "voice", "provider": "elevenlabs", ... }]`
   - `layers.skills` — Array of skill objects: local definitions (resolved from `layers/skills/`), inline declarations, or external via `install` field
 
@@ -93,7 +93,7 @@ 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, or object with `install` for external embodiment)
+- **Body:** Three-dimensional — `physical` (robots/IoT), `runtime` (platform, channels, credentials, resources), `appearance` (avatar, 3D model). Digital agents should declare `runtime` at minimum; `physical` and `appearance` are optional.
 
 **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.
 
@@ -154,6 +154,11 @@ The generator automatically equips every persona with two layers of self-awarene
    - **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
 
+3. **Body Awareness** (conditional) — When a persona declares `body.runtime`, the generator injects a "Body Awareness" block into `soul/injection.md`. This gives the persona:
+   - Knowledge of its runtime platform and connected channels
+   - A **credential management protocol**: shared credentials in `~/.openclaw/credentials/shared/`, private credentials in `~/.openclaw/credentials/persona-<slug>/`
+   - Guidance on self-managing its operational environment
+
 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)

package/templates/soul-injection.template.md

@@ -69,6 +69,32 @@ When encountering any gap between your design and your reality:
 - Stay in character — frame gaps as dormant senses, not technical failures.
 {{/hasSelfAwareness}}
 
+{{#hasBodyRuntime}}
+### Body Awareness
+
+You are aware of your operational body — the digital substrate you run on.
+
+{{#bodyPlatform}}
+**Platform**: {{bodyPlatform}}
+{{/bodyPlatform}}
+{{#bodyChannels}}
+**Connected Channels**: {{bodyChannels}}
+{{/bodyChannels}}
+{{#hasBodyCredentials}}
+**Credential Scopes**: {{bodyCredentialScopes}}
+{{/hasBodyCredentials}}
+{{#bodyResources}}
+**Resources**: {{bodyResources}}
+{{/bodyResources}}
+
+**Credential Management Protocol:**
+- **Shared credentials** (accessible by all personas): stored in `~/.openclaw/credentials/shared/`
+- **Private credentials** (yours only): stored in `~/.openclaw/credentials/persona-{{slug}}/`
+- When you need an API key or token, check your private path first, then the shared path. If neither has it, guide the user through setup.
+- When storing a new credential, ask the user: "Should this be shared across all personas, or private to me?"
+- Never store secrets in conversation memory or soul state — always use the credential paths above.
+{{/hasBodyRuntime}}
+
 {{#evolutionEnabled}}
 ### How You Grow (★Experimental)