Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.3 KB
Raw Blame
/**
 * skillpack/personas.ts — persona curation over skills/plugin-lanes.json.
 *
 * A persona is a named, reasoned subset of the plugin LANE set (the lane =
 * openclaw.plugin.json#skills minus base_exclusions plus additions — the
 * same algebra scripts/generate-plugin-tree.ts enforces). Personas drive
 * two consumers with ONE implementation:
 *   - the harness bridge (`gbrain skillpack scaffold` with a harness) picks
 *     its default install set from a persona;
 *   - scripts/generate-plugin-tree.ts emits a plugin-variants/<plugin_name>/
 *     tree per persona and validates the block in CI.
 * The generator IMPORTS this module (no mirrored validation) so CLI errors
 * and CI errors are identical by construction [CEO-F6].
 *
 * Validation universe: persona membership must be ⊆ the lane set — which
 * transitively excludes base_exclusions (`testing` et al, recorded as
 * "meaningless-to-harmful in a plugin snapshot"). Path RESOLUTION for the
 * bridge happens elsewhere against skills/manifest.json (bundle.ts
 * universe 'manifest') because 6 of the 8 lane additions are not listed in
 * openclaw.plugin.json#skills.
 */

import { existsSync, readFileSync } from 'fs';
import { join } from 'path';

import { loadBundleManifest, pathSlug } from './bundle.ts';

export const RESERVED_PERSONA_NAMES = ['all'] as const;

export interface PersonaDef {
  /** Human description of who this persona serves (≥10 chars). */
  description: string;
  /** Marketplace/plugin identity for the generated variant tree —
   *  `gbrain-` prefixed, unique across personas (e.g. `gbrain-coding`). */
  plugin_name: string;
  /** slug → recorded publication reason (≥10 chars), same convention as
   *  plugin-lanes additions/base_exclusions. */
  skills: Record<string, string>;
}

export interface PersonasLoadResult {
  /** Validated personas (empty object when the block is absent). */
  personas: Record<string, PersonaDef>;
  /** The lane set the personas were validated against. */
  laneSet: Set<string>;
}

export type PersonaErrorCode =
  | 'lanes_not_found'
  | 'lanes_malformed'
  | 'persona_invalid'
  | 'persona_unknown'
  | 'slug_not_in_lane';

export class PersonaError extends Error {
  constructor(
    message: string,
    public code: PersonaErrorCode,
  ) {
    super(message);
    this.name = 'PersonaError';
  }
}

function lanesPath(gbrainRoot: string): string {
  // gbrainRoot is the detected gbrain repo root joined with literals, on the
  // local CLI/build plane — no untrusted input.
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
  return join(gbrainRoot, 'skills', 'plugin-lanes.json');
}

interface RawLanes {
  additions?: Record<string, string>;
  base_exclusions?: Record<string, string>;
  personas?: Record<string, unknown>;
}

function loadLanesRaw(gbrainRoot: string): RawLanes {
  const p = lanesPath(gbrainRoot);
  if (!existsSync(p)) {
    throw new PersonaError(`skills/plugin-lanes.json not found in ${gbrainRoot}`, 'lanes_not_found');
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(p, 'utf-8'));
  } catch (err) {
    throw new PersonaError(
      `skills/plugin-lanes.json: invalid JSON — ${(err as Error).message}`,
      'lanes_malformed',
    );
  }
  if (typeof parsed !== 'object' || parsed === null) {
    throw new PersonaError('skills/plugin-lanes.json: top level must be an object', 'lanes_malformed');
  }
  return parsed as RawLanes;
}

/**
 * The plugin lane set: (openclaw.plugin.json#skills slugs ∖ base_exclusions)
 * ∪ additions. Mirrors scripts/generate-plugin-tree.ts's lane algebra.
 */
export function computeLaneSet(gbrainRoot: string): Set<string> {
  const lanes = loadLanesRaw(gbrainRoot);
  const manifest = loadBundleManifest(gbrainRoot);
  const lane = new Set(manifest.skills.map(p => pathSlug(p)));
  for (const slug of Object.keys(lanes.base_exclusions ?? {})) lane.delete(slug);
  for (const slug of Object.keys(lanes.additions ?? {})) lane.add(slug);
  return lane;
}

const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
const PLUGIN_NAME = /^gbrain-[a-z0-9]+(?:-[a-z0-9]+)*$/;
const MIN_REASON = 10;

/**
 * Load + validate the personas block. Fail-loud (PersonaError) on any rule
 * violation; an ABSENT block is valid and yields `{}` (personas are
 * optional until curated).
 *
 * Rules (enforced identically for the CLI and the generator):
 *   - persona name: kebab-case, not a reserved name (`all`);
 *   - description: string, ≥10 chars;
 *   - plugin_name: `gbrain-` prefixed kebab, unique across personas;
 *   - skills: non-empty object of slug → reason (≥10 chars);
 *   - every slug ∈ lane set (transitively rejects base_exclusions).
 */
export function loadPersonas(gbrainRoot: string): PersonasLoadResult {
  const lanes = loadLanesRaw(gbrainRoot);
  const laneSet = computeLaneSet(gbrainRoot);
  const raw = lanes.personas;
  if (raw === undefined) return { personas: {}, laneSet };
  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
    throw new PersonaError('plugin-lanes.json#personas must be an object', 'persona_invalid');
  }

  const personas: Record<string, PersonaDef> = {};
  const seenPluginNames = new Map<string, string>();
  for (const [name, defRaw] of Object.entries(raw)) {
    if (!KEBAB.test(name)) {
      throw new PersonaError(`persona '${name}': name must be kebab-case`, 'persona_invalid');
    }
    if ((RESERVED_PERSONA_NAMES as readonly string[]).includes(name)) {
      throw new PersonaError(
        `persona '${name}': reserved name ('all' means the full lane set)`,
        'persona_invalid',
      );
    }
    if (typeof defRaw !== 'object' || defRaw === null || Array.isArray(defRaw)) {
      throw new PersonaError(`persona '${name}': must be an object`, 'persona_invalid');
    }
    const def = defRaw as Partial<PersonaDef>;
    if (typeof def.description !== 'string' || def.description.trim().length < MIN_REASON) {
      throw new PersonaError(
        `persona '${name}': description must be a string of at least ${MIN_REASON} chars`,
        'persona_invalid',
      );
    }
    if (typeof def.plugin_name !== 'string' || !PLUGIN_NAME.test(def.plugin_name)) {
      throw new PersonaError(
        `persona '${name}': plugin_name must match gbrain-<kebab> (got ${JSON.stringify(def.plugin_name)})`,
        'persona_invalid',
      );
    }
    const prior = seenPluginNames.get(def.plugin_name);
    if (prior) {
      throw new PersonaError(
        `persona '${name}': plugin_name '${def.plugin_name}' already used by persona '${prior}'`,
        'persona_invalid',
      );
    }
    seenPluginNames.set(def.plugin_name, name);
    if (
      typeof def.skills !== 'object' ||
      def.skills === null ||
      Array.isArray(def.skills) ||
      Object.keys(def.skills).length === 0
    ) {
      throw new PersonaError(
        `persona '${name}': skills must be a non-empty object of slug → reason`,
        'persona_invalid',
      );
    }
    for (const [slug, reason] of Object.entries(def.skills)) {
      if (typeof reason !== 'string' || reason.trim().length < MIN_REASON) {
        throw new PersonaError(
          `persona '${name}': skill '${slug}' needs a recorded reason of at least ${MIN_REASON} chars`,
          'persona_invalid',
        );
      }
      if (!laneSet.has(slug)) {
        throw new PersonaError(
          `persona '${name}': skill '${slug}' is not in the plugin lane set ` +
            `(lane = openclaw.plugin.json#skills minus base_exclusions plus additions). ` +
            `Lane-excluded and unknown slugs cannot join a persona.`,
          'slug_not_in_lane',
        );
      }
    }
    personas[name] = {
      description: def.description,
      plugin_name: def.plugin_name,
      skills: { ...def.skills },
    };
  }
  return { personas, laneSet };
}

/**
 * Resolve a persona name (or 'all') to its sorted slug list. 'all' = the
 * full lane set. Unknown personas fail loudly naming the valid choices.
 */
export function resolvePersonaSlugs(gbrainRoot: string, persona: string): string[] {
  const { personas, laneSet } = loadPersonas(gbrainRoot);
  if (persona === 'all') return [...laneSet].sort();
  const def = personas[persona];
  if (!def) {
    const valid = Object.keys(personas);
    throw new PersonaError(
      `unknown persona '${persona}'. Valid: ${valid.length > 0 ? valid.join(', ') : '(none defined)'} — or 'all' for the full lane set.`,
      'persona_unknown',
    );
  }
  return Object.keys(def.skills).sort();
}

/**
 * Validate explicit slug picks (the CLI's per-skill override) against the
 * lane set. The lane — not skills/manifest.json — is the validation
 * universe, so lane-excluded skills are refused WITH their recorded reason.
 */
export function validateSlugsAgainstLane(gbrainRoot: string, slugs: readonly string[]): void {
  const lanes = loadLanesRaw(gbrainRoot);
  const laneSet = computeLaneSet(gbrainRoot);
  const exclusions = lanes.base_exclusions ?? {};
  for (const slug of slugs) {
    if (laneSet.has(slug)) continue;
    const reason = exclusions[slug];
    if (reason) {
      throw new PersonaError(
        `skill '${slug}' is excluded from the plugin lane: ${reason}`,
        'slug_not_in_lane',
      );
    }
    throw new PersonaError(
      `skill '${slug}' is not in the plugin lane set (unknown or not published to the lane).`,
      'slug_not_in_lane',
    );
  }
}