oomi-ai 0.2.18 → 0.2.20

package/README.md

@@ -4,8 +4,9 @@ OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
 
 ## Current Focus
 
-`0.2.18` adds the first live persona automation lane:
+`0.2.19` adds the first live persona automation lane:
 - WebSpatial-based persona scaffolding for generated Oomi apps
+- a high-level `oomi personas create-managed` command for agent-driven persona creation
 - device-authenticated persona runtime registration and job callbacks
 - automatic bridge-side polling for queued `persona_job` control messages
 - end-to-end local persona startup from a structured orchestration payload
@@ -153,6 +154,7 @@ oomi personas scaffold market-analyst --name "Market Analyst" --description "Pri
 
 Use:
 - `oomi personas create <id>` for repo-local manifest work
+- `oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace"` for the end-to-end Oomi-managed persona flow
 - `oomi personas scaffold <slug>` for a WebSpatial-based Oomi app shell with runtime metadata and health documents
 - `oomi persona-jobs execute --message-file <job.json>` when OpenClaw receives a structured persona orchestration job from Oomi
 
@@ -166,7 +168,13 @@ oomi persona-jobs succeed pj_123 --workspace-path ~/.openclaw/personas/market-an
 oomi persona-jobs fail pj_123 --code JOB_FAILED --message "Scaffold generation failed."
 ```
 
-When the managed bridge is running, `oomi-ai` now also polls the backend control lane for queued `persona_job` messages and executes them automatically. That poll path is filtered to `metadata.type = persona_job`, so it does not consume normal queued chat traffic.
+Recommended agent flow:
+
+```bash
+oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace for recipes, meal planning, and kitchen notes."
+```
+
+That command creates the managed persona record in Oomi using the linked device identity. The backend then enqueues the `persona_job`, and the running bridge consumes that job automatically. The poll path is filtered to `metadata.type = persona_job`, so it does not consume normal queued chat traffic.
 
 ## Bridge Health States
 

package/agent_instructions.md

@@ -194,6 +194,13 @@ Aliases allowed if needed:
 
 ## Persona App Generation
 
+When a user asks you in chat to create a new persona for Oomi:
+
+1. Prefer `oomi personas create-managed --name "<name>" --description "<description>"`.
+2. That is the primary end-to-end command for agent-driven persona creation.
+3. It creates the managed persona record in Oomi and relies on the running bridge to consume the queued `persona_job` automatically.
+4. Do not manually scaffold first unless you are recovering a failed persona job or working outside the queued Oomi flow.
+
 When generating a managed persona app for Oomi:
 
 1. Do not build the app shell from scratch.

package/bin/oomi-ai.js

@@ -12,6 +12,7 @@ import { scaffoldPersonaApp } from '../lib/scaffold.js';
 import { createPersonaApiClient } from '../lib/personaApiClient.js';
 import { startPersonaJobPoller } from '../lib/personaJobPoller.js';
 import { executePersonaJob } from '../lib/personaJobExecutor.js';
+import { inferSpokenMetadataFromContent, normalizeSpokenMetadata } from '../lib/spokenMetadata.js';
 import {
   buildLocalPersonaRuntime,
   defaultPersonaWorkspaceRoot,
@@ -190,6 +191,8 @@ Commands:
 
   personas create <id>
     Create a new persona manifest and optionally sync it to the backend.
+  personas create-managed [slug]
+    Create a managed persona in Oomi and enqueue its build job for the linked device.
   personas scaffold <slug>
     Create an Oomi-managed persona app scaffold for agent customization.
   personas runtime-register <slug>
@@ -225,9 +228,10 @@ Common flags:
   --json                 Print pairing result as JSON (for automation)
   --backend-url URL      Override Oomi backend URL
   --root PATH            Override repo root path for persona discovery
-  --name NAME            Persona display name (for create)
-  --description TEXT     Persona description (for scaffold)
-  --summary TEXT         Persona summary (for create)
+  --name NAME            Persona display name (for create)
+  --description TEXT     Persona description (for scaffold)
+  --slug SLUG            Explicit slug override (for create-managed)
+  --summary TEXT         Persona summary (for create)
   --status STATUS        Persona status (for create)
   --type TYPE            Persona type (for create)
   --tags a,b,c           Persona tags (for create)
@@ -595,6 +599,32 @@ function printPersonaScaffoldResult(result, asJson = false) {
   }
 }
 
+function printManagedPersonaCreateResult(result, asJson = false) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const persona = result?.persona && typeof result.persona === 'object' ? result.persona : {};
+  const personaJob = result?.personaJob && typeof result.personaJob === 'object' ? result.personaJob : {};
+  console.log(`Managed persona created: ${String(persona.name || persona.slug || 'unknown')}`);
+  if (persona.slug) {
+    console.log(`Slug: ${persona.slug}`);
+  }
+  if (persona.lifecycle) {
+    console.log(`Lifecycle: ${persona.lifecycle}`);
+  }
+  if (personaJob.jobId) {
+    console.log(`Persona job: ${personaJob.jobId}`);
+  }
+  if (personaJob.status) {
+    console.log(`Job status: ${personaJob.status}`);
+  }
+  if (personaJob.deviceId) {
+    console.log(`Assigned device: ${personaJob.deviceId}`);
+  }
+}
+
 function parseOptionalPositiveInteger(value) {
   if (value === undefined || value === null || value === '') return null;
   const parsed = Number(value);
@@ -932,6 +962,26 @@ async function handlePersonaJobExecuteCommand(flags = {}) {
 
   printStructuredResult(result, isTruthyFlag(flags.json));
 }
+
+async function handlePersonaCreateManagedCommand(flags = {}, positionalSlug = '') {
+  const name = String(flags.name || '').trim();
+  if (!name) {
+    throw new Error('Persona name is required. Usage: oomi personas create-managed [slug] --name "<name>" --description "<description>"');
+  }
+
+  const description = String(flags.description || '').trim() || name;
+  const explicitSlug = String(flags.slug || positionalSlug || '').trim();
+  const client = createCliPersonaApiClient(flags);
+  const result = await client.createManagedPersona({
+    slug: explicitSlug,
+    name,
+    description,
+    templateType: String(flags['template-type'] || 'persona-app').trim() || 'persona-app',
+    promptTemplateVersion: String(flags['template-version'] || 'v1').trim() || 'v1',
+  });
+
+  printManagedPersonaCreateResult(result, isTruthyFlag(flags.json));
+}
 
 function resolveOpenclawConfigPath() {
   const candidates = [
@@ -1599,13 +1649,80 @@ function prepareGatewayFrameForLocalGateway(frameText, gatewayAuth, options = {}
   }
 }
 
-function parseJsonPayload(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
+function parseJsonPayload(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function extractTextFromGatewayMessage(message) {
+  if (!message || typeof message !== 'object') return '';
+
+  if (typeof message.content === 'string' && message.content.trim()) {
+    return message.content.trim();
+  }
+
+  if (!Array.isArray(message.content)) return '';
+
+  return message.content
+    .filter((block) => block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+function ensureVoiceAssistantSpokenMetadata(frameText) {
+  const frame = parseJsonPayload(frameText);
+  if (!frame || typeof frame !== 'object') {
+    return { frameText, changed: false, reason: '' };
+  }
+  if (frame.type !== 'event' || frame.event !== 'chat') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const payload = frame.payload && typeof frame.payload === 'object' ? frame.payload : null;
+  if (!payload || payload.state !== 'final') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const message = payload.message && typeof payload.message === 'object' ? payload.message : null;
+  if (!message || message.role !== 'assistant') {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  const originalMetadata =
+    message.metadata && typeof message.metadata === 'object' && !Array.isArray(message.metadata)
+      ? message.metadata
+      : {};
+  const metadata = { ...originalMetadata };
+  const explicitSpokenPresent = Object.prototype.hasOwnProperty.call(originalMetadata, 'spoken');
+  const spoken =
+    normalizeSpokenMetadata(originalMetadata.spoken) ||
+    (!explicitSpokenPresent ? inferSpokenMetadataFromContent(extractTextFromGatewayMessage(message)) : null);
+  if (!spoken) {
+    return { frameText, changed: false, reason: '' };
+  }
+
+  metadata.spoken = spoken;
+  const nextFrame = JSON.stringify({
+    ...frame,
+    payload: {
+      ...payload,
+      message: {
+        ...message,
+        metadata,
+      },
+    },
+  });
+
+  return {
+    frameText: nextFrame,
+    changed: nextFrame !== frameText,
+    reason: explicitSpokenPresent ? 'normalized' : 'synthesized',
+  };
+}
 
 function extractCorrelationId(params) {
   if (!params || typeof params !== 'object') return '';
@@ -2833,11 +2950,18 @@ async function startOpenclawBridge(flags) {
         flushSessionQueue(sessionBridge);
       });
 
-      gatewaySocket.on('message', runBridgeCallbackSafely((gatewayRaw) => {
-        const frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
-        const gatewayPayload = parseJsonPayload(frame);
-        if (gatewayPayload?.event === 'connect.challenge') {
-          console.log(`[bridge] gateway.connect.challenge ${sessionId}`);
+      gatewaySocket.on('message', runBridgeCallbackSafely((gatewayRaw) => {
+        let frame = typeof gatewayRaw === 'string' ? gatewayRaw : gatewayRaw.toString();
+        if (classifyBridgeSessionScope(sessionId) === 'voice') {
+          const spokenNormalized = ensureVoiceAssistantSpokenMetadata(frame);
+          if (spokenNormalized.changed) {
+            frame = spokenNormalized.frameText;
+            console.log(`[bridge] voice.spoken_metadata.${spokenNormalized.reason} ${sessionId}`);
+          }
+        }
+        const gatewayPayload = parseJsonPayload(frame);
+        if (gatewayPayload?.event === 'connect.challenge') {
+          console.log(`[bridge] gateway.connect.challenge ${sessionId}`);
           const nonce =
             gatewayPayload.payload && typeof gatewayPayload.payload.nonce === 'string'
               ? gatewayPayload.payload.nonce.trim()
@@ -3964,15 +4088,20 @@ async function main() {
     return;
   }
 
-  if (command === 'personas' && subcommand === 'create') {
+  if (command === 'personas' && subcommand === 'create') {
     const id = args.positionals[0];
     if (!id) {
       throw new Error('Persona id is required. Usage: oomi personas create <id>');
     }
     await createPersona({ id, root: args.flags.root, flags: args.flags });
     return;
-  }
-
+  }
+
+  if (command === 'personas' && subcommand === 'create-managed') {
+    await handlePersonaCreateManagedCommand(args.flags, args.positionals[0]);
+    return;
+  }
+
   if (command === 'personas' && subcommand === 'scaffold') {
     const slug = args.positionals[0];
     if (!slug) {
@@ -4065,11 +4194,12 @@ if (__isDirectExecution) {
   });
 }
 
-export {
-  prepareGatewayFrameForLocalGateway,
-  classifyBridgeFailure,
-  classifyBridgeSessionScope,
-  createBridgeProcessFaultHandler,
+export {
+  prepareGatewayFrameForLocalGateway,
+  ensureVoiceAssistantSpokenMetadata,
+  classifyBridgeFailure,
+  classifyBridgeSessionScope,
+  createBridgeProcessFaultHandler,
   computeReconnectDelayMs,
   resolveBridgeStatusForBrokerOpen,
   resolveBridgeStatusForRuntimeFault,

package/lib/personaApiClient.js

@@ -66,6 +66,38 @@ export function createPersonaApiClient({
   }
 
   return {
+    createManagedPersona({
+      slug,
+      name,
+      description,
+      templateType = 'persona-app',
+      promptTemplateVersion = 'v1',
+    }) {
+      const safeName = trimString(name);
+      if (!safeName) {
+        throw new Error('Persona name is required.');
+      }
+
+      const body = withDevice({
+        name: safeName,
+        description: trimString(description) || safeName,
+        templateType: trimString(templateType) || 'persona-app',
+        promptTemplateVersion: trimString(promptTemplateVersion) || 'v1',
+      });
+      const safeSlug = trimString(slug);
+      if (safeSlug) {
+        body.slug = safeSlug;
+      }
+
+      return postJson({
+        fetchImpl,
+        backendUrl: resolvedBackendUrl,
+        deviceToken: resolvedDeviceToken,
+        path: '/v1/personas/managed_create',
+        body,
+      });
+    },
+
     registerRuntime({
       slug,
       endpoint,

package/lib/spokenMetadata.js

@@ -0,0 +1,273 @@
+function trimString(value, fallback = '') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function clampInteger(value, fallback, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  const normalized = Math.floor(value);
+  if (normalized < min) return fallback;
+  if (normalized > max) return max;
+  return normalized;
+}
+
+const BOUNDED_LANGUAGE_TYPES = new Set([
+  'Auto',
+  'Chinese',
+  'English',
+  'German',
+  'Italian',
+  'Portuguese',
+  'Spanish',
+  'Japanese',
+  'Korean',
+  'French',
+  'Russian',
+]);
+
+const BOUNDED_PACE_VALUES = new Set(['very_slow', 'slow', 'medium', 'medium_fast', 'fast']);
+const BOUNDED_PITCH_VALUES = new Set(['low', 'slightly_low', 'neutral', 'slightly_high', 'high']);
+const BOUNDED_ENERGY_VALUES = new Set(['soft', 'calm', 'warm', 'bright', 'intense']);
+const BOUNDED_VOLUME_VALUES = new Set(['soft', 'normal', 'projected']);
+
+function inferSpokenLanguage(text) {
+  const normalized = trimString(text);
+  if (!normalized) return 'English';
+  return 'English';
+}
+
+function normalizeSpokenSegment(segment) {
+  if (!segment || typeof segment !== 'object' || Array.isArray(segment)) return null;
+
+  const text = trimString(segment.text);
+  if (!text) return null;
+
+  const normalized = { text };
+  const pace = trimString(segment.pace);
+  const pitch = trimString(segment.pitch);
+  const energy = trimString(segment.energy);
+  const volume = trimString(segment.volume);
+  const pauseAfterMs = clampInteger(segment.pause_after_ms, 0, { min: 0, max: 1200 });
+
+  if (BOUNDED_PACE_VALUES.has(pace)) normalized.pace = pace;
+  if (BOUNDED_PITCH_VALUES.has(pitch)) normalized.pitch = pitch;
+  if (BOUNDED_ENERGY_VALUES.has(energy)) normalized.energy = energy;
+  if (BOUNDED_VOLUME_VALUES.has(volume)) normalized.volume = volume;
+  normalized.pause_after_ms = pauseAfterMs;
+
+  return normalized;
+}
+
+function stripEmoji(text) {
+  return text.replace(/[\uFE0E\uFE0F]/g, '').replace(/\p{Extended_Pictographic}|\p{Emoji_Presentation}/gu, '');
+}
+
+function normalizeSpeechText(text) {
+  return stripEmoji(text)
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/__(.*?)__/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/[–—]/g, ', ')
+    .replace(/…/g, '...')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([,.;!?])/g, '$1')
+    .replace(/([,.;!?])(?=[^\s])/g, '$1 ')
+    .replace(/,\s*,+/g, ', ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function splitSpeechSegments(text) {
+  const normalized = normalizeSpeechText(text);
+  if (!normalized) return [];
+
+  const baseSegments = normalized
+    .split(/(?<=[.!?])\s+/)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+
+  const segments = [];
+  for (const segment of baseSegments) {
+    if (segment.length <= 96) {
+      segments.push(segment);
+      continue;
+    }
+
+    const clauseParts = segment
+      .split(/,\s+/)
+      .map((part) => part.trim())
+      .filter(Boolean);
+
+    if (clauseParts.length > 1) {
+      for (let index = 0; index < clauseParts.length; index += 1) {
+        const part = clauseParts[index];
+        const needsComma = index < clauseParts.length - 1 && !/[.!?]$/.test(part);
+        segments.push(needsComma ? `${part},` : part);
+      }
+      continue;
+    }
+
+    segments.push(segment);
+  }
+
+  if (segments.length <= 5) return segments;
+
+  return [...segments.slice(0, 4), segments.slice(4).join(' ').trim()];
+}
+
+function inferSegmentStyle(segmentText, index, totalSegments) {
+  const normalized = segmentText.toLowerCase();
+  const exclamatory = /!/.test(segmentText) || /\b(hell yeah|awesome|amazing|stoked|love|perfect|great)\b/.test(normalized);
+  const curious = /\?/.test(segmentText);
+  const reflective =
+    /\b(i think|i'm|i am|i've|i have|lately|right now|before this|each time|understand|it feels like)\b/.test(normalized) ||
+    segmentText.length > 60;
+
+  if (curious) {
+    return {
+      pace: 'medium',
+      pitch: 'slightly_high',
+      energy: 'warm',
+      volume: 'normal',
+      pause_after_ms: 0,
+    };
+  }
+
+  if (exclamatory) {
+    return {
+      pace: 'medium_fast',
+      pitch: 'slightly_high',
+      energy: 'bright',
+      volume: 'normal',
+      pause_after_ms: index < totalSegments - 1 ? 220 : 0,
+    };
+  }
+
+  if (reflective) {
+    return {
+      pace: 'medium',
+      pitch: 'neutral',
+      energy: 'warm',
+      volume: 'normal',
+      pause_after_ms: index < totalSegments - 1 ? 260 : 0,
+    };
+  }
+
+  return {
+    pace: 'medium',
+    pitch: 'neutral',
+    energy: 'warm',
+    volume: 'normal',
+    pause_after_ms: index < totalSegments - 1 ? 180 : 0,
+  };
+}
+
+function synthesizeSpokenSegments(text) {
+  const language = inferSpokenLanguage(text);
+  const rawSegments = splitSpeechSegments(text);
+  if (rawSegments.length === 0) return null;
+
+  const segments = rawSegments.map((segmentText, index) => ({
+    text: segmentText,
+    ...inferSegmentStyle(segmentText, index, rawSegments.length),
+  }));
+
+  return {
+    language,
+    segments,
+  };
+}
+
+function normalizeSpokenMetadata(spoken) {
+  if (!spoken || typeof spoken !== 'object' || Array.isArray(spoken)) return null;
+
+  const text = trimString(spoken.text);
+  if (!text) return null;
+
+  const normalized = { text };
+  const language = trimString(spoken.language);
+  if (BOUNDED_LANGUAGE_TYPES.has(language)) {
+    normalized.language = language;
+  }
+
+  const explicitSegments =
+    Array.isArray(spoken.segments)
+      ? spoken.segments.map((segment) => normalizeSpokenSegment(segment)).filter(Boolean)
+      : [];
+  if (explicitSegments.length > 0) {
+    normalized.segments = explicitSegments;
+  }
+
+  const instructions = trimString(spoken.instructions);
+  if (instructions) normalized.instructions = instructions;
+  if (spoken.style && typeof spoken.style === 'object' && !Array.isArray(spoken.style)) {
+    normalized.style = spoken.style;
+  }
+
+  const fallbackSegments = synthesizeSpokenSegments(text);
+  if (!normalized.language && fallbackSegments?.language) {
+    normalized.language = fallbackSegments.language;
+  }
+  if (!normalized.segments && fallbackSegments?.segments?.length) {
+    normalized.segments = fallbackSegments.segments;
+  }
+
+  return normalized;
+}
+
+function inferSpokenMetadataFromContent(content) {
+  const text = normalizeSpeechText(trimString(content));
+  if (!text) return null;
+  const synthesized = synthesizeSpokenSegments(text);
+
+  const normalized = text.toLowerCase();
+  const upbeat =
+    /!/.test(text) ||
+    /\b(hell yeah|awesome|amazing|great|stoked|love|glad|perfect|nice|cool)\b/.test(normalized);
+  const gentle =
+    /\b(sorry|gentle|softly|careful|reassuring|calm|okay|it'?s okay|i know)\b/.test(normalized);
+  const curious = /\?/.test(text);
+
+  if (upbeat) {
+    return {
+      text,
+      language: synthesized?.language || 'English',
+      segments: synthesized?.segments,
+      instructions: 'Speak with warm, upbeat conversational energy and natural pacing.',
+      style: { emotion: 'upbeat', energy: 'medium' },
+    };
+  }
+
+  if (gentle) {
+    return {
+      text,
+      language: synthesized?.language || 'English',
+      segments: synthesized?.segments,
+      instructions: 'Speak gently and reassuringly, with a calm pace and soft emphasis.',
+      style: { emotion: 'gentle', energy: 'low' },
+    };
+  }
+
+  if (curious) {
+    return {
+      text,
+      language: synthesized?.language || 'English',
+      segments: synthesized?.segments,
+      instructions: 'Speak naturally with curious, engaged intonation and a conversational pace.',
+      style: { emotion: 'curious', energy: 'medium' },
+    };
+  }
+
+  return {
+    text,
+    language: synthesized?.language || 'English',
+    segments: synthesized?.segments,
+    instructions: 'Speak naturally with light warmth and conversational pacing.',
+    style: { emotion: 'neutral', energy: 'medium' },
+  };
+}
+
+export {
+  inferSpokenMetadataFromContent,
+  normalizeSpokenMetadata,
+  normalizeSpeechText,
+};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "oomi-ai",
   "name": "Oomi Channel Plugin",
   "description": "Managed Oomi channel integration for OpenClaw.",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "author": "Oomi",
   "license": "MIT",
   "openclawVersion": ">=0.5.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Oomi OpenClaw channel plugin and bridge tooling",
   "bin": {
     "oomi": "bin/oomi-ai.js"