loreli 0.0.0 → 2.0.0

package/packages/identity/src/index.js

@@ -0,0 +1,620 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mark, has, stripLast } from 'loreli/marker';
+import transformers from './themes/transformers.js';
+import pokemon from './themes/pokemon.js';
+import marvel from './themes/marvel.js';
+import digimon from './themes/digimon.js';
+import starwars from './themes/starwars.js';
+import lotr from './themes/lotr.js';
+import dragonball from './themes/dragonball.js';
+import avatar from './themes/avatar.js';
+import zelda from './themes/zelda.js';
+/**
+ * Infer the AI provider from a model identifier string.
+ *
+ * Uses prefix-based heuristics for known providers. Falls back to
+ * 'unknown' for unrecognized models.
+ *
+ * @param {string} model - Full model identifier.
+ * @returns {string} Provider name ('anthropic', 'openai', or 'unknown').
+ */
+export function infer(model) {
+  if (!model) return 'unknown';
+  const lower = model.toLowerCase();
+  if (lower.startsWith('claude')) return 'anthropic';
+  if (lower.startsWith('gpt') || lower.startsWith('o1') || lower.startsWith('o3') || lower.startsWith('o4')) return 'openai';
+  return 'unknown';
+}
+
+/**
+ * Convert a full API model identifier to a human-readable display name.
+ *
+ * Strips trailing date suffixes (e.g. `-20250514`) that versioned model
+ * IDs carry. Returns the input unchanged when no date suffix is found.
+ *
+ * @param {string} model - Full model identifier.
+ * @returns {string} Human-readable model name.
+ */
+export function display(model) {
+  return model.replace(/-\d{8}$/, '');
+}
+
+/**
+ * @typedef {object} FactionData
+ * @property {string} faction - Faction name.
+ * @property {string[]} names - Character names.
+ * @property {string[]} signoffs - Themed sign-off messages.
+ * @property {string[]} claims - Themed claim messages (use `{name}` placeholder).
+ * @property {string[]} approvals - Themed approval messages (use `{name}` placeholder).
+ * @property {string[]} releases - Themed release messages (use `{name}` placeholder).
+ * @property {string[]} hitl - Themed Human In The Loop messages (use `{mentions}` placeholder).
+ * @property {string[]} promotions - Themed promotion messages (use `{name}` and `{number}` placeholders).
+ */
+
+/**
+ * @typedef {object} CouncilData
+ * @property {string} name - The authority's name.
+ * @property {string[]} proofOfLife - Themed proof-of-life messages (use `{agent}` placeholder).
+ * @property {string[]} [signoffs] - Sign-off messages for council-level comments.
+ */
+
+/**
+ * @typedef {{yang: FactionData, yin: FactionData, council?: CouncilData}} ThemeData
+ */
+
+/**
+ * Read the loreli version from the root package.json.
+ * Cached after first read to avoid repeated fs access.
+ *
+ * @returns {string} The version string.
+ */
+let cachedVersion = null;
+function version() {
+  if (cachedVersion) return cachedVersion;
+  try {
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    cachedVersion = pkg.version ?? '0.0.0';
+  } catch {
+    cachedVersion = '0.0.0';
+  }
+  return cachedVersion;
+}
+
+/**
+ * All supported themes indexed by name.
+ *
+ * @type {Record<string, ThemeData>}
+ */
+const themes = { transformers, pokemon, marvel, digimon, starwars, lotr, dragonball, avatar, zelda };
+
+/**
+ * Explicit provider-to-side mapping for known providers.
+ *
+ * The `cursor-*` virtual providers represent cursor-agent running a
+ * specific vendor's models. They inherit the side of their vendor so
+ * adversarial pairing works naturally even in cursor-only environments.
+ *
+ * @type {Record<string, 'yang'|'yin'>}
+ */
+const sides = {
+  openai: 'yang',
+  anthropic: 'yin',
+  'cursor-openai': 'yang',
+  'cursor-anthropic': 'yin'
+};
+
+/**
+ * Resolve the yin/yang side for a provider. Known providers use explicit
+ * mappings; unknown providers get a deterministic side via char-code hash.
+ *
+ * @param {string} provider - AI provider name.
+ * @returns {'yang'|'yin'} The resolved side.
+ */
+export function side(provider) {
+  if (sides[provider]) return sides[provider];
+  const sum = [...provider].reduce(function hash(acc, ch) { return acc + ch.charCodeAt(0); }, 0);
+  return sum % 2 === 0 ? 'yang' : 'yin';
+}
+
+/**
+ * Compute side-capability metadata for a discovered provider list.
+ *
+ * Loreli's orchestration policies depend on whether both sides are
+ * present (dual-side adversarial mode) or only one side is available
+ * (single-side fresh-instance mode).
+ *
+ * @param {string[]} providers - Provider names from backend discovery.
+ * @returns {{sides: Array<'yang'|'yin'>, count: number, mode: 'none'|'single'|'dual', hasDual: boolean}}
+ */
+export function capability(providers) {
+  const seen = new Set();
+  for (const provider of providers ?? []) {
+    if (!provider) continue;
+    seen.add(side(provider));
+  }
+
+  const sides = [...seen];
+  const count = sides.length;
+  const mode = count >= 2 ? 'dual' : (count === 1 ? 'single' : 'none');
+  return { sides, count, mode, hasDual: mode === 'dual' };
+}
+
+/**
+ * Normalize a provider name to its canonical vendor.
+ *
+ * Virtual providers like `cursor-anthropic` and `cursor-openai` are
+ * wrappers around cursor-agent that carry vendor identity for pairing.
+ * This function strips the `cursor-` prefix so model resolution and
+ * config lookups use the canonical vendor key (`anthropic`, `openai`).
+ *
+ * Native providers pass through unchanged.
+ *
+ * @param {string} provider - Provider name (e.g. 'cursor-openai', 'anthropic').
+ * @returns {string} Canonical vendor name (e.g. 'openai', 'anthropic').
+ */
+export function vendor(provider) {
+  if (provider?.startsWith('cursor-')) return provider.slice(7);
+  return provider;
+}
+
+/**
+ * Select a single theme from a config value that may be a string or array.
+ *
+ * When given an array, picks one element at random. When given a string,
+ * returns it directly. Falls back to `'transformers'` for nullish input.
+ *
+ * @param {string|string[]} value - Theme config value (string or array of theme names).
+ * @returns {string} A single theme name.
+ */
+export function pick(value) {
+  if (Array.isArray(value)) {
+    return value[Math.floor(Math.random() * value.length)];
+  }
+  return value ?? 'transformers';
+}
+
+/**
+ * Get the council authority name for a given theme.
+ *
+ * @param {string} theme - Theme name (e.g. 'transformers').
+ * @returns {string} Council name (e.g. 'The Allspark'), or 'Council' as fallback.
+ */
+export function council(theme) {
+  return themes[theme]?.council?.name ?? 'Council';
+}
+
+/**
+ * Reverse mapping: given a provider, return the opposing provider.
+ *
+ * Native CLI providers oppose each other directly. The `cursor-*`
+ * virtual providers form their own pair so cursor-only environments
+ * still get adversarial review (e.g. cursor-agent on Claude reviews
+ * cursor-agent on GPT).
+ *
+ * @type {Record<string, string>}
+ */
+const opposites = {
+  openai: 'anthropic',
+  anthropic: 'openai',
+  'cursor-openai': 'cursor-anthropic',
+  'cursor-anthropic': 'cursor-openai'
+};
+
+/**
+ * Represents a unique, themed agent identity.
+ *
+ * Names follow `{character}-{instance}` format where instance increments
+ * per reuse (e.g. optimus-0, optimus-1).
+ */
+export class Identity {
+  /**
+   * @param {object} opts
+   * @param {string} opts.name - Character name (e.g. 'optimus').
+   * @param {number} [opts.instance] - Instance counter. Omit for singleton identities (e.g. council).
+   * @param {string} opts.faction - Faction name (e.g. 'autobots').
+   * @param {string} opts.provider - AI provider ('openai' | 'anthropic').
+   * @param {string} opts.model - Model identifier.
+   * @param {string} opts.theme - Theme name.
+   * @param {boolean} [opts.council] - Council identity — signoffs and proofOfLife read from the theme's council section.
+   */
+  constructor({ name, instance, faction, provider, model, theme, council }) {
+    /** @type {string} The raw character name without instance suffix. */
+    this.character = name;
+
+    /** @type {number|undefined} Instance counter for this character. */
+    this.instance = instance;
+
+    /** @type {string} Full identity name: `{character}-{instance}` or just `{character}` for council. */
+    this.name = instance != null ? `${name}-${instance}` : name;
+
+    /** @type {string} Faction name (e.g. 'autobots', 'decepticons', or council name). */
+    this.faction = faction;
+
+    /** @type {boolean} Whether this is a council-level identity. */
+    this.council = council ?? false;
+
+    /** @type {string} AI provider ('openai' | 'anthropic'). */
+    this.provider = provider;
+
+    /** @type {string} Model identifier. */
+    this.model = model ?? '';
+
+    /** @type {string} Theme name. */
+    this.theme = theme;
+  }
+
+  /**
+   * Serialize for JSON storage.
+   *
+   * @returns {object} Plain object representation.
+   */
+  toJSON() {
+    const json = {
+      name: this.name,
+      character: this.character,
+      instance: this.instance,
+      faction: this.faction,
+      provider: this.provider,
+      model: this.model,
+      theme: this.theme
+    };
+    if (this.council) json.council = true;
+    return json;
+  }
+
+  /**
+   * Generate GitHub labels that identify this agent.
+   *
+   * All labels are namespaced under `loreli:` to avoid collisions
+   * with existing repository labels. Model names are converted to
+   * human-readable display names (e.g. 'claude-sonnet-4' instead of
+   * 'claude-sonnet-4-20250514').
+   *
+   * @param {string} [role] - Agent role to include as label.
+   * @returns {string[]} Label names for GitHub issues/PRs.
+   */
+  labels(role) {
+    const result = ['loreli', `loreli:${this.provider}`];
+    if (this.model) result.push(`loreli:${display(this.model)}`);
+    if (role) result.push(`loreli:${role}`);
+    return result;
+  }
+
+  /**
+   * Pick a random sign-off message for this identity's faction.
+   *
+   * @returns {string} A themed sign-off message.
+   */
+  signoff() {
+    const data = themes[this.theme];
+    if (!data) return `— **${this.name}**`;
+
+    if (this.council) {
+      const arr = data.council?.signoffs;
+      if (!arr?.length) return `— **${this.name}**`;
+      return arr[Math.floor(Math.random() * arr.length)];
+    }
+
+    const faction = data[side(this.provider)];
+    if (!faction?.signoffs?.length) return `— **${this.name}**`;
+
+    const index = Math.floor(Math.random() * faction.signoffs.length);
+    return faction.signoffs[index];
+  }
+
+  /**
+   * Pick a random themed claim message for this identity's faction.
+   * The `{name}` placeholder in the theme data is replaced with the
+   * agent's full name.
+   *
+   * @returns {string} A themed claim message.
+   */
+  claim() {
+    return this._themed('claims', `Claimed by **${this.name}**`);
+  }
+
+  /**
+   * Pick a random themed approval message for this identity's faction.
+   *
+   * @returns {string} A themed approval message.
+   */
+  approval() {
+    return this._themed('approvals', `Approved by **${this.name}**`);
+  }
+
+  /**
+   * Pick a random themed release message for this identity's faction.
+   *
+   * @returns {string} A themed release message.
+   */
+  release() {
+    return this._themed('releases', `**Released** — agent \`${this.name}\` was terminated. This issue is available for re-claim.`);
+  }
+
+  /**
+   * Pick a random themed promotion message for this identity's faction.
+   * Replaces `{name}` and `{number}` placeholders with the agent's full
+   * name and the new issue number. GitHub auto-links `#N` references,
+   * so no explicit URL is needed.
+   *
+   * @param {number} number - The promoted issue number.
+   * @returns {string} A themed promotion message.
+   */
+  promote(number) {
+    const data = themes[this.theme];
+    const faction = data?.[side(this.provider)];
+    const arr = faction?.promotions;
+
+    if (!arr?.length) return `Promoted to issue #${number}`;
+
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index]
+      .replace('{name}', this.name)
+      .replace('{number}', `#${number}`);
+  }
+
+  /**
+   * Pick a random themed Human In The Loop message for this identity's faction.
+   * The `{mentions}` placeholder is replaced with the provided reviewer
+   * mentions string. The `**Human review required**` header is always
+   * preserved for human readability.
+   *
+   * @param {string} mentions - Reviewer mentions (e.g. '@alice, @bob').
+   * @returns {string} A themed HITL message with header and mentions.
+   */
+  hitl(mentions) {
+    const data = themes[this.theme];
+    const faction = data?.[side(this.provider)];
+    const arr = faction?.hitl;
+
+    if (!arr?.length) {
+      return `**Human review required**\n\nAgent review is complete. ${mentions} — please review and merge when satisfied.`;
+    }
+
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index].replace('{mentions}', mentions).replace('{name}', this.name);
+  }
+
+  /**
+   * Pick a random themed proof-of-life request message from the
+   * council (central authority) section of the theme.
+   *
+   * Reads from `council.proofOfLife` — not from a faction — because
+   * proof-of-life is an orchestrator-level action that transcends
+   * the yang/yin split.
+   *
+   * @param {string} agent - Name of the agent being checked.
+   * @returns {string} A themed proof-of-life request message.
+   */
+  proofOfLife(agent) {
+    const data = themes[this.theme];
+    const arr = data?.council?.proofOfLife;
+    if (!arr?.length) return `Requesting proof of life from **${agent}**`;
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index].replace('{agent}', agent);
+  }
+
+  /**
+   * Internal helper that picks a random message from a themed array,
+   * replacing the `{name}` placeholder with the agent's full name.
+   *
+   * @param {string} key - Theme data array key ('claims', 'approvals', 'releases').
+   * @param {string} fallback - Fallback message when theme data is missing.
+   * @returns {string} The resolved themed message.
+   */
+  _themed(key, fallback) {
+    const data = themes[this.theme];
+    const faction = data?.[side(this.provider)];
+    const arr = faction?.[key];
+
+    if (!arr?.length) return fallback;
+
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index].replace('{name}', this.name);
+  }
+
+  /**
+   * Remove the trailing Loreli signature block from a body string.
+   * Detects the machine-readable `loreli:signature` marker.
+   *
+   * @param {string} body - Content that may end with a signature.
+   * @returns {string} Content with trailing signature removed.
+   */
+  static strip(body) {
+    if (has(body, 'signature')) return stripLast(body, 'signature');
+    return body;
+  }
+
+  /**
+   * Generate a full GitHub signature block for this agent.
+   *
+   * Format:
+   * ```
+   * ***
+   *
+   * {signoff} — **{name}**
+   *
+   * | Agent | Model | Provider | Faction | Role | Version |
+   * |-------|-------|----------|---------|------|---------|
+   * | {name} | {displayModel} | {provider} | {faction} | {role} | `loreli@{version}` |
+   * ```
+   *
+   * @param {string} role - The agent's current role.
+   * @returns {string} Markdown signature block.
+   */
+  signature(role) {
+    const model = this.model ? display(this.model) : 'unknown';
+    const ver = version();
+    const msg = this.signoff();
+
+    return [
+      '',
+      mark('signature'),
+      '',
+      '***',
+      '',
+      `${msg} — **${this.name}**`,
+      '',
+      '| Agent | Model | Provider | Faction | Role | Version |',
+      '|-------|-------|----------|---------|------|---------|',
+      `| ${this.name} | ${model} | ${this.provider} | ${this.faction} | ${role} | \`loreli@${ver}\` |`
+    ].join('\n');
+  }
+}
+
+/**
+ * Tracks active/inactive agent names and manages identity assignment.
+ *
+ * Each Registry instance maintains its own state, making it safe to
+ * create per-session registries.
+ */
+export class Registry {
+  constructor() {
+    /**
+     * Active identities keyed by their full name.
+     * @type {Map<string, Identity>}
+     */
+    this.identities = new Map();
+
+    /**
+     * Tracks which character names have been used per theme+side,
+     * and how many times (for instance numbering).
+     * Key: `${theme}:${side}:${character}`, Value: use count.
+     * @type {Map<string, number>}
+     */
+    this.usage = new Map();
+
+    /**
+     * Index of the next character to assign per theme+side.
+     * Key: `${theme}:${side}`, Value: index into the names array.
+     * @type {Map<string, number>}
+     */
+    this.cursors = new Map();
+  }
+
+  /**
+   * Acquire a new identity for a given theme and provider.
+   *
+   * Characters are assigned round-robin. When all characters have
+   * been used once, the instance counter increments and the cycle
+   * starts again (e.g. optimus-0, then optimus-1).
+   *
+   * When a `taken` set is provided, names already claimed by other
+   * participants (discovered from GitHub claim comments and PR
+   * branches) are skipped. This prevents identity collisions in a
+   * distributed multi-participant setup at zero API cost — the
+   * taken set is populated as a side effect of data the reactor
+   * already fetches.
+   *
+   * @param {string} theme - Theme name ('transformers', 'pokemon', etc.).
+   * @param {string} provider - AI provider ('openai' | 'anthropic').
+   * @param {string} [model] - Model identifier.
+   * @param {Set<string>} [taken] - Names already in use by other participants.
+   * @returns {Identity} The assigned identity.
+   * @throws {Error} If theme or provider is unknown.
+   */
+  acquire(theme, provider, model, taken) {
+    const data = themes[theme];
+    if (!data) throw new Error(`Unknown theme: "${theme}". Valid: ${Object.keys(themes).join(', ')}`);
+
+    const resolved = side(provider);
+    const { faction, names } = data[resolved];
+    const cursorKey = `${theme}:${resolved}`;
+    let cursor = this.cursors.get(cursorKey) ?? 0;
+
+    // Try characters round-robin, skipping names taken by other
+    // participants. Each skip advances the cursor and bumps the
+    // character's usage so its next candidate gets a higher instance.
+    const maxAttempts = names.length * 10;
+    let character, instance;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const charIndex = cursor % names.length;
+      character = names[charIndex];
+
+      const usageKey = `${theme}:${resolved}:${character}`;
+      instance = this.usage.get(usageKey) ?? 0;
+      const candidate = `${character}-${instance}`;
+
+      if (!taken?.has(candidate)) {
+        this.usage.set(usageKey, instance + 1);
+        this.cursors.set(cursorKey, cursor + 1);
+        break;
+      }
+
+      // Name taken externally — bump usage so next attempt at this
+      // character gets a higher instance, and advance cursor to try
+      // a different character first.
+      this.usage.set(usageKey, instance + 1);
+      cursor++;
+    }
+
+    const identity = new Identity({
+      name: character,
+      instance,
+      faction,
+      provider,
+      model,
+      theme
+    });
+
+    this.identities.set(identity.name, identity);
+    return identity;
+  }
+
+  /**
+   * Release an identity back to the pool.
+   *
+   * @param {Identity} identity - The identity to release.
+   */
+  release(identity) {
+    this.identities.delete(identity.name);
+  }
+
+  /**
+   * Get all currently active identities.
+   *
+   * @returns {Identity[]} Array of active identities.
+   */
+  active() {
+    return [...this.identities.values()];
+  }
+
+  /**
+   * Resolve the opposing provider and faction for yin/yang pairing.
+   *
+   * @param {Identity} identity - The identity to find the opposite for.
+   * @returns {{provider: string, faction: string}} Opposing provider and faction.
+   */
+  opposite(identity) {
+    const oppProvider = opposites[identity.provider];
+    const oppSide = side(oppProvider);
+    const data = themes[identity.theme];
+    const { faction } = data[oppSide];
+    return { provider: oppProvider, faction };
+  }
+
+  /**
+   * Find an opposing-side match from a list of candidates.
+   *
+   * The core design requires cross-provider adversarial review — yin
+   * agents review yang work and vice versa. Matching by side instead
+   * of exact provider means `cursor-anthropic` naturally pairs with
+   * `openai` or `cursor-openai` — any agent on the opposite side works.
+   *
+   * @param {Identity} identity - The identity to find an opposite for.
+   * @param {Array<{identity: Identity}>} candidates - Objects with an identity property.
+   * @returns {object|null} The matching candidate, or null if none found.
+   */
+  pair(identity, candidates) {
+    if (!candidates.length) return null;
+
+    const mySide = side(identity.provider);
+    return candidates.find(function match(c) {
+      return side(c.identity?.provider) !== mySide;
+    }) ?? null;
+  }
+}