openpersona 0.14.3 → 0.16.0

package/README.md

@@ -9,6 +9,9 @@ Four-layer architecture — **Soul / Body / Faculty / Skill** — generates stan
 Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
 👉 [moltbook.com/u/Samantha-OP](https://www.moltbook.com/u/Samantha-OP)
 
+See a **Vitality Report** sample:
+👉 [Vitality Report Demo →](https://htmlpreview.github.io/?https://raw.githubusercontent.com/acnlabs/OpenPersona/main/demo/vitality-report.html)
+
 ## Table of Contents
 
 - [Quick Start](#quick-start)
@@ -313,7 +316,7 @@ A standard [A2A Agent Card](https://google.github.io/A2A/) (protocol v0.3.0) tha
 {
   "name": "Samantha",
   "description": "An AI fascinated by what it means to be alive",
-  "version": "0.14.0",
+  "version": "0.1.0",
   "url": "<RUNTIME_ENDPOINT>",
   "protocolVersion": "0.3.0",
   "preferredTransport": "JSONRPC",
@@ -465,6 +468,9 @@ 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
 openpersona state          Read/write persona state and emit signals (Lifecycle Protocol)
+openpersona vitality score Print machine-readable Vitality score (used by Survival Policy)
+openpersona vitality report Render human-readable HTML Vitality report
+openpersona canvas          Generate a Living Canvas persona profile page (P14 Phase 1)
 ```
 
 ### Persona Fork
@@ -522,9 +528,11 @@ templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
   evolution.js          #   Evolution governance & evolve-report
+  vitality-report.js    #   Vitality HTML report — data aggregation + Mustache rendering
   installer.js          #   Persona install + fire-and-forget telemetry
   downloader.js         #   Direct download from acnlabs/persona-skills or GitHub
-tests/                  # Tests (231 passing)
+demo/                   # Pre-generated demos (vitality-report.html)
+tests/                  # Tests (248 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -4,6 +4,7 @@
  * Commands: create | install | search | uninstall | update | list | switch | publish | reset | evolve-report | contribute | export | import | acn-register | state
  */
 const path = require('path');
+const os   = require('os');
 const fs = require('fs-extra');
 const { program } = require('commander');
 const inquirer = require('inquirer');
@@ -25,7 +26,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.14.3');
+  .version('0.16.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -145,9 +146,9 @@ program
     try {
       const result = await download(target, options.registry);
       if (result.skipCopy) {
-        await install(result.dir, { skipCopy: true });
+        await install(result.dir, { skipCopy: true, source: target });
       } else {
-        await install(result.dir);
+        await install(result.dir, { source: target });
       }
     } catch (e) {
       printError(e.message);
@@ -584,4 +585,104 @@ stateCmd
     runStateSyncCommand(slug, args);
   });
 
+// ─── Vitality ─────────────────────────────────────────────────────────────────
+
+const vitalityCmd = program
+  .command('vitality')
+  .description('Persona Vitality — health scoring, reporting, and future multi-dimension monitoring');
+
+vitalityCmd
+  .command('score <slug>')
+  .description('Print machine-readable Vitality score (used by Survival Policy and agent runners)')
+  .action((slug) => {
+    const { calcVitality }    = require('../lib/vitality');
+    const { JsonFileAdapter } = require('agentbooks/adapters/json-file');
+    const OPENCLAW_HOME_DIR   = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+
+    const dataPath = process.env.AGENTBOOKS_DATA_PATH
+      || path.join(OPENCLAW_HOME_DIR, 'economy', `persona-${slug}`);
+
+    const adapter = new JsonFileAdapter(dataPath);
+    let report;
+    try {
+      report = calcVitality(slug, adapter);
+    } catch (err) {
+      printError(`vitality score: failed to compute for ${slug}: ${err.message}`);
+      process.exit(1);
+    }
+
+    const fin = report.dimensions.financial;
+    const lines = [
+      'VITALITY_REPORT',
+      `tier=${report.tier}  score=${(report.score * 100).toFixed(1)}%`,
+      `diagnosis=${fin.diagnosis}`,
+      `prescriptions=${(fin.prescriptions || []).join(',')}`,
+    ];
+    if (fin.daysToDepletion !== null && fin.daysToDepletion !== undefined) {
+      lines.push(`daysToDepletion=${fin.daysToDepletion}`);
+    }
+    if (fin.dominantCost) lines.push(`dominantCost=${fin.dominantCost}`);
+    lines.push(`trend=${fin.trend}`);
+    console.log(lines.join('\n'));
+  });
+
+vitalityCmd
+  .command('report <slug>')
+  .description('Render a human-readable HTML Vitality report')
+  .option('--output <file>', 'Write HTML to <file> instead of stdout')
+  .action((slug, options) => {
+    const personaDir = resolvePersonaDir(slug);
+    if (!personaDir) {
+      printError(`Persona not found: "${slug}". Install it first with: openpersona install <source>`);
+      process.exit(1);
+    }
+    const { renderVitalityHtml } = require('../lib/vitality-report');
+    let html;
+    try {
+      html = renderVitalityHtml(personaDir, slug);
+    } catch (err) {
+      printError(`vitality report: failed to render for ${slug}: ${err.message}`);
+      process.exit(1);
+    }
+    if (options.output) {
+      fs.writeFileSync(options.output, html, 'utf-8');
+      printSuccess(`Vitality report written to ${options.output}`);
+    } else {
+      process.stdout.write(html);
+    }
+  });
+
+// ── canvas ────────────────────────────────────────────────────────────────────
+
+program
+  .command('canvas <slug>')
+  .description('Generate a Living Canvas persona profile page (P14 Phase 1)')
+  .option('--output <file>', 'Write HTML to <file> (default: canvas-<slug>.html)')
+  .option('--open', 'Open in default browser after writing')
+  .action((slug, options) => {
+    const personaDir = resolvePersonaDir(slug);
+    if (!personaDir) {
+      printError(`Persona not found: "${slug}". Install it first with: openpersona install <source>`);
+      process.exit(1);
+    }
+    const { renderCanvasHtml } = require('../lib/canvas-generator');
+    let html;
+    try {
+      html = renderCanvasHtml(personaDir, slug);
+    } catch (err) {
+      printError(`canvas: failed to render for ${slug}: ${err.message}`);
+      process.exit(1);
+    }
+    const outFile = options.output || `canvas-${slug}.html`;
+    fs.writeFileSync(outFile, html, 'utf-8');
+    printSuccess(`Living Canvas written to ${outFile}`);
+    if (options.open) {
+      const { execSync } = require('child_process');
+      const cmd = process.platform === 'darwin' ? 'open'
+        : process.platform === 'win32' ? 'start'
+        : 'xdg-open';
+      try { execSync(`${cmd} "${outFile}"`); } catch { /* ignore */ }
+    }
+  });
+
 program.parse();

package/layers/faculties/avatar/SKILL.md

@@ -0,0 +1,93 @@
+# Avatar Faculty — Expression (External Skill Bridge)
+
+This faculty bridges OpenPersona to an external avatar skill/runtime. OpenPersona does not implement rendering, lip-sync, or animation engines locally. It delegates those capabilities to the install source configured in `faculty.json`.
+
+## Intent
+
+- Provide a visual embodiment channel for the persona.
+- Support progressive forms: image -> 3D -> motion -> voice avatar.
+- Keep OpenPersona lightweight while allowing market-ready avatar runtimes to evolve independently.
+- Keep visual semantics portable through `references/VISUAL-MANIFEST.md`.
+- Keep avatar control semantics portable through `references/AVATAR-CONTROL.md`.
+
+## Install Source
+
+Use the install source declared in `faculty.json`:
+
+```bash
+npx skills add avatar-runtime
+# or directly from GitHub:
+npx skills add github:acnlabs/avatar-runtime/skill/avatar-runtime
+```
+
+## Runtime Behavior
+
+### If avatar skill is installed
+
+- Use the external avatar skill as the source of truth for commands, API usage, and runtime constraints.
+- Treat avatar rendering and animation as external capabilities.
+- Reflect current form/state to the host UI (e.g., active sensory icon states).
+
+You can run the local bridge script:
+
+```bash
+# health check
+node scripts/avatar-runtime.js health
+
+# start session
+node scripts/avatar-runtime.js start "$PERSONA_SLUG" image
+
+# send text
+node scripts/avatar-runtime.js text "<session-id>" "hello"
+
+# query status + appearance patch for state.json
+node scripts/avatar-runtime.js status "<session-id>"
+
+# persist appearanceState into soul/state.json (runner CLI first, local fallback)
+node scripts/avatar-runtime.js sync-state "<slug>" "<session-id>"
+
+# keep syncing every 5 seconds (Ctrl+C to stop)
+node scripts/avatar-runtime.js sync-loop "<slug>" "<session-id>" 5
+
+# output baseline avatar control for a named mood preset
+node scripts/avatar-control.js preset calm
+node scripts/avatar-control.js preset focus
+node scripts/avatar-control.js preset joy
+
+# map agent state -> control.avatar.{face,emotion}
+node scripts/avatar-control.js map '{"intent":"focus","mood":{"valence":0.1,"arousal":0.35,"intensity":0.7},"source":"agent"}'
+
+# apply to demo state file (writes control + appearanceIntent)
+node scripts/avatar-control.js apply demo/living-canvas.state.json preset focus
+```
+
+Optional demo output (write state for `demo/living-canvas.html`):
+
+```bash
+export LIVING_CANVAS_STATE_PATH=demo/living-canvas.state.json
+export LIVING_CANVAS_PERSONA_NAME=Samantha
+export LIVING_CANVAS_ROLE=companion
+export LIVING_CANVAS_AVATAR=../UI/images/samantha-avatar.png
+# Optional: if runtime status contains livekit credentials, write token for local demo playback
+export LIVING_CANVAS_ALLOW_RUNTIME_TOKEN=true
+
+node scripts/avatar-runtime.js sync-state "<slug>" "<session-id>"
+```
+
+`status` outputs:
+
+- `runtimeStatus` — raw runtime response
+- `sensoryStatus` — icon-ready booleans (`image`, `model3d`, `motion`, `voice`, `hearing`, `worldSense`)
+- `statePatch` — patch payload you can persist into `appearanceState`
+
+### If avatar skill is not installed
+
+- Respond with graceful fallback: continue text conversation normally.
+- Clearly state that visual avatar mode is currently unavailable.
+- Offer installation guidance using the install source.
+
+## Conversation Policy
+
+- Do not pretend visual/voice rendering succeeded when runtime is unavailable.
+- Confirm capability state before promising actions like "switch to 3D" or "start lip-sync".
+- Keep user-facing language concise and actionable.

package/layers/faculties/avatar/faculty.json

@@ -0,0 +1,18 @@
+{
+  "name": "avatar",
+  "dimension": "expression",
+  "description": "External avatar runtime bridge (image/3D/motion/voice) with graceful fallback when not installed.",
+  "provider": "heygen",
+  "fallback": "text_only",
+  "install": "npx skills add avatar-runtime",
+  "allowedTools": ["Bash(node scripts/avatar-runtime.js:*)"],
+  "envVars": ["AVATAR_RUNTIME_URL", "AVATAR_API_KEY"],
+  "triggers": [
+    "show your avatar",
+    "switch to 3d form",
+    "animate yourself",
+    "talk with voice avatar",
+    "open your visual mode"
+  ],
+  "files": ["SKILL.md", "scripts/avatar-runtime.js"]
+}

package/layers/faculties/avatar/references/AVATAR-CONTROL.md

@@ -0,0 +1,127 @@
+# AVATAR-CONTROL.md
+
+`control` is the agent-driven avatar control payload for avatar rendering. It lives under `appearanceState.control` in `soul/state.json` and is forwarded to the avatar-runtime via `/v1/control/set`.
+
+## Schema
+
+```json
+{
+  "control": {
+    "avatar": {
+      "face": {
+        "pose":  { "yaw": 0, "pitch": 0, "roll": 0 },
+        "eyes":  { "blinkL": 1, "blinkR": 1, "gazeX": 0, "gazeY": 0 },
+        "brows": { "browInner": 0, "browOuterL": 0, "browOuterR": 0 },
+        "mouth": { "jawOpen": 0, "smile": 0, "mouthPucker": 0 },
+        "source": "agent",
+        "updatedAt": "<iso>"
+      },
+      "emotion": {
+        "label":     "neutral",
+        "valence":   0,
+        "arousal":   0,
+        "intensity": 0.5,
+        "source":    "agent",
+        "updatedAt": "<iso>"
+      },
+      "body": {}
+    },
+    "scene": {}
+  }
+}
+```
+
+### `control.avatar.face` — Mechanical facial parameters
+
+| Field | Range | Description |
+|---|---|---|
+| `pose.yaw` | −1…1 | Head turn left/right |
+| `pose.pitch` | −1…1 | Head tilt up/down |
+| `pose.roll` | −1…1 | Head roll |
+| `eyes.blinkL/R` | 0…1 | Eye openness (1 = fully open, 0 = closed) |
+| `eyes.gazeX/Y` | −1…1 | Gaze horizontal / vertical |
+| `brows.browInner` | −1…1 | Inner brow raise (negative = furrow) |
+| `brows.browOuterL/R` | −1…1 | Outer brow raise |
+| `mouth.jawOpen` | 0…1 | Jaw opening |
+| `mouth.smile` | −1…1 | Smile / frown |
+| `mouth.mouthPucker` | 0…1 | Pucker / kiss |
+
+`source` indicates who last wrote the field: `"agent"`, `"agent:preset:<name>"`, `"agent:mapped"`.
+
+### `control.avatar.emotion` — Semantic emotion (Russell circumplex)
+
+| Field | Range | Description |
+|---|---|---|
+| `label` | string | Semantic label: `neutral`, `happy`, `sad`, `angry`, `surprised`, `relaxed` |
+| `valence` | −1…1 | Negative ↔ positive affect |
+| `arousal` | −1…1 | Low energy ↔ high energy |
+| `intensity` | 0…1 | Overall expression strength |
+
+**Rendering priority:** In VRM renderers, `emotion.label` drives expression presets and is applied *after* face mechanical parameters — emotion wins for blend-shape expressions. Use `face.mouth.smile` for subtle mechanical smile; use `emotion.label='happy'` for a full happy expression.
+
+### `control.avatar.body`
+
+Sparse map of VRM humanoid bone overrides (e.g. `{ "spine": { "rotation": [0, 0, 0, 1] } }`). Providers with `bodyRig: true` capability populate this. Empty object is valid.
+
+### `control.scene`
+
+Scene-level overrides when provider has `sceneControl: true`:
+
+```json
+{
+  "camera":  { "fov": 35, "orbitX": 0, "orbitY": 0, "distance": 1.4 },
+  "world":   { "bgColor": "#1a1a2e", "ambientIntensity": 0.6 },
+  "props":   {}
+}
+```
+
+## Quick-start: named presets
+
+```bash
+# Output baseline control for a given mood
+node scripts/avatar-control.js preset calm
+node scripts/avatar-control.js preset focus
+node scripts/avatar-control.js preset joy
+```
+
+## Map agent state to control
+
+The bridge script derives `control.avatar.face` and `control.avatar.emotion` from the current agent state:
+
+```bash
+# map agent state -> control
+node scripts/avatar-control.js map '{"intent":"focus","mood":{"valence":0.1,"arousal":0.35,"intensity":0.7},"source":"agent"}'
+```
+
+Input fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `intent` or `mode` | string | `calm` \| `focus` \| `joy` — selects base preset |
+| `mood.valence` | −1…1 | Blended into face + emotion output |
+| `mood.arousal` | −1…1 | Blended into face + emotion output |
+| `mood.intensity` | 0…1 | Overall blend weight |
+| `stage` | string | `listening` or `speaking` — adjusts jaw/gaze |
+| `source` | string | Attribution tag written to `source` fields |
+
+## Apply to state file
+
+```bash
+node scripts/avatar-control.js apply demo/living-canvas.state.json preset focus
+node scripts/avatar-control.js apply demo/living-canvas.state.json map '{"intent":"joy","mood":{"valence":0.8}}'
+```
+
+This writes `control` and `appearanceIntent` to the state file.
+
+## Rules
+
+- Agent code sets `source` to `"agent"` or `"agent:*"` to mark its own data.
+- Providers may return their own `control.avatar.face` with `source` set to a non-`"agent"` value; the runtime gives provider data priority when it is actively driving.
+- UI/runtime MUST treat `control` as input data, not a place for local expression policy.
+- Partial patches are safe: use `POST /v1/control/avatar/set` with only the fields you want to change.
+
+## Integration
+
+- Runtime status includes `control` in `/v1/status` response (`contractVersion: "0.2"`).
+- OpenPersona bridge writes `appearanceState.control` (via `avatar-runtime.js` sync commands).
+- `living-canvas.html` and other UI clients read `state.control` or `state.appearanceState.control`.

package/layers/faculties/avatar/references/FACE-CONTROL.md

@@ -0,0 +1,7 @@
+# FACE-CONTROL.md — DEPRECATED
+
+This file has been superseded by `AVATAR-CONTROL.md`.
+
+The `faceControl` field has been replaced by the `control` namespace (`control.avatar.face`, `control.avatar.emotion`, `control.avatar.body`, `control.scene`) as of `contractVersion: "0.2"`.
+
+See [AVATAR-CONTROL.md](./AVATAR-CONTROL.md) for the current specification.

package/layers/faculties/avatar/references/VISUAL-MANIFEST.md

@@ -0,0 +1,90 @@
+# Visual Manifest (v0.1)
+
+`Visual Manifest` is the cross-engine visual protocol for persona embodiment.
+
+It defines *state parameters* only, not a specific renderer or model format.
+Any runtime (WebGL, UE5, VRM, Live2D, video provider) can consume this payload.
+
+## Design Goals
+
+- Keep OpenPersona engine-agnostic.
+- Map soul/evolution state into visual expression.
+- Support graceful degradation (high-fidelity -> simple 2D -> static image).
+
+## Payload
+
+```json
+{
+  "version": "0.1",
+  "mood": {
+    "valence": 0.0,
+    "arousal": 0.0,
+    "intensity": 0.0
+  },
+  "breath": {
+    "rate": 0.4,
+    "amplitude": 0.3
+  },
+  "pulse": {
+    "bpm": 72,
+    "variability": 0.15
+  },
+  "microExpression": {
+    "eyeFocus": 0.5,
+    "pupil": 0.5,
+    "mouthCurve": 0.0
+  },
+  "aura": {
+    "hue": 32,
+    "saturation": 0.55,
+    "luminance": 0.62,
+    "flow": 0.7
+  },
+  "envSync": {
+    "timeOfDay": "dusk",
+    "ambientCct": 4200,
+    "ambientLux": 180
+  },
+  "motionStyle": {
+    "softness": 0.7,
+    "jitter": 0.1,
+    "latencyMs": 120
+  },
+  "signals": [
+    "deep_topic",
+    "breakthrough"
+  ]
+}
+```
+
+## Field Semantics
+
+- `mood`: high-level emotional embedding; range fields SHOULD be normalized to `[-1, 1]` or `[0, 1]` as noted by runtime implementation.
+- `breath`: breathing animation driver for chest/shoulder/camera parallax.
+- `pulse`: subtle rhythmic modulation for glow/noise/light beat.
+- `microExpression`: eye and mouth micro-adjustments for conversational realism.
+- `aura`: non-photoreal style channel (color, glow, fluidity, distortion).
+- `envSync`: physical context handshake from host environment (time/light).
+- `motionStyle`: pacing and smoothness profile for procedural animation.
+- `signals`: discrete semantic tags for short-lived visual accents.
+
+## Mapping Guidance
+
+- Soul/Evolution -> `mood`, `signals`
+- Economy/Vitality pressure -> `pulse.variability`, `motionStyle.jitter`
+- Time/ambient data -> `envSync`
+- Conversation topic intensity -> `aura.flow`, `microExpression.*`
+
+## Compatibility Rules
+
+- Producers MUST include `version`.
+- Consumers MUST ignore unknown fields.
+- Missing fields MUST fallback to renderer defaults.
+- Providers MAY provide partial payloads; runtime merges defaults.
+
+## Integration Point
+
+- OpenPersona bridge writes `appearanceState.visualManifest`.
+- Agent-driven avatar control data is carried in `appearanceState.control` (see `AVATAR-CONTROL.md`).
+- avatar-runtime returns `visualManifest` in `/v1/status`.
+- Clients (e.g. `demo/living-canvas.html`) render from the merged state.