loreli 0.0.0 → 2.0.0

package/packages/hub/src/index.js

@@ -0,0 +1,79 @@
+import { BaseHub } from './base.js';
+import { GitHubHub } from './github.js';
+export { definitions } from './labels.js';
+
+export { BaseHub, GitHubHub };
+
+/**
+ * Factory function that creates the appropriate hub implementation
+ * based on available tokens or explicit provider option.
+ *
+ * Token resolution order:
+ * 1. Explicit opts.token
+ * 2. loreli/config instance (opts.config) — reads through config's resolution chain
+ * 3. Environment variable (GITHUB_TOKEN) — direct fallback
+ *
+ * @param {object} [opts] - Configuration options.
+ * @param {string} [opts.provider] - Explicit provider ('github', future 'gitlab').
+ * @param {string} [opts.token] - Authentication token.
+ * @param {object} [opts.config] - loreli/config instance with a get() method.
+ * @returns {import('./base.js').BaseHub} A hub instance.
+ * @throws {Error} When no token is available for the selected provider.
+ *
+ * @example
+ * ```js
+ * // Auto-detect from environment
+ * const h = hub();
+ *
+ * // With loreli/config — token resolves via config's env layer
+ * const h = hub({ config });
+ *
+ * // Explicit token
+ * const h = hub({ provider: 'github', token: 'ghp_...' });
+ * ```
+ */
+export function hub(opts = {}) {
+  const provider = opts.provider ?? detect(opts.config);
+  const token = opts.token ?? tokenFrom(opts.config, provider);
+
+  if (!token) {
+    throw new Error(
+      `No token available for provider "${provider}". ` +
+      'Set GITHUB_TOKEN (or pass { token } explicitly).'
+    );
+  }
+
+  switch (provider) {
+    case 'github':
+      return new GitHubHub({ token });
+    default:
+      throw new Error(`Unknown hub provider: "${provider}"`);
+  }
+}
+
+/**
+ * Detect the provider from config or environment variables.
+ *
+ * @param {object} [config] - Optional loreli/config instance.
+ * @returns {string} The detected provider name.
+ */
+function detect(config) {
+  if (config?.get?.('github.token')) return 'github';
+  if (process.env.GITHUB_TOKEN) return 'github';
+  // Future: check GITLAB_TOKEN, GITEA_TOKEN, etc.
+  return 'github'; // default
+}
+
+/**
+ * Resolve the token for a provider, checking config first then env.
+ *
+ * @param {object} [config] - Optional loreli/config instance.
+ * @param {string} provider - The provider name.
+ * @returns {string|undefined} The token, or undefined if not set.
+ */
+function tokenFrom(config, provider) {
+  switch (provider) {
+    case 'github': return config?.get?.('github.token') ?? process.env.GITHUB_TOKEN;
+    default: return undefined;
+  }
+}

package/packages/hub/src/labels.js

@@ -0,0 +1,48 @@
+import hex from 'text-hex';
+
+/**
+ * Known loreli: label descriptions keyed by suffix.
+ * Used to generate human-readable descriptions for namespaced labels.
+ *
+ * @type {Record<string, string>}
+ */
+const KNOWN = {
+  planner: 'Agent role: planner',
+  action: 'Agent role: action',
+  reviewer: 'Agent role: reviewer',
+  approved: 'Approved by reviewer agent',
+  'changes-requested': 'Changes requested by reviewer agent',
+  'needs-attention': 'Escalated — requires human attention',
+  parent: 'Parent tracking issue for a planning objective',
+  openai: 'AI provider: openai',
+  anthropic: 'AI provider: anthropic'
+};
+
+/**
+ * Build label definition objects (with deterministic colors) for hub.ensure().
+ *
+ * Colors are generated from the label name using text-hex — no hardcoded palette.
+ * Each unique label name always produces the same hex color.
+ *
+ * All agent labels use the `loreli:` namespace prefix to avoid collisions
+ * with existing repository labels. The base `loreli` label is the only
+ * one without the colon prefix.
+ *
+ * @param {string[]} names - Label names (e.g. ['loreli', 'loreli:planner']).
+ * @returns {Array<{name: string, color: string, description: string}>}
+ */
+export function definitions(names) {
+  return names.map(function define(name) {
+    const color = hex(name).replace('#', '');
+    let description = '';
+
+    if (name === 'loreli') {
+      description = 'Managed by Loreli agent orchestration';
+    } else if (name.startsWith('loreli:')) {
+      const suffix = name.slice('loreli:'.length);
+      description = KNOWN[suffix] ?? `Loreli: ${suffix}`;
+    }
+
+    return { name, color, description };
+  });
+}

package/packages/identity/README.md

@@ -0,0 +1,288 @@
+# loreli/identity
+
+Themed agent naming with provider-based yin/yang pairing. Also provides model-identity utility functions (`display`, `infer`) that convert raw model strings to human-readable forms and infer provider from model names.
+
+When OpenAI agents create work, Anthropic agents review it (and vice versa), creating adversarial quality checks through themed identity assignment. Multi-provider backends like Cursor Agent are assigned to the faction matching their configured model's provider.
+
+## API Reference
+
+### `display(model)` → string
+
+Convert a full API model identifier to a human-readable display name by stripping trailing date suffixes (e.g. `-20250514`). Returns the input unchanged when no date suffix is found.
+
+```js
+import { display } from 'loreli/identity';
+
+display('claude-sonnet-4-20250514'); // 'claude-sonnet-4'
+display('gpt-4o');                   // 'gpt-4o'
+```
+
+### `infer(model)` → string
+
+Infer the AI provider from a model identifier string using prefix-based heuristics. Returns `'anthropic'` for claude models, `'openai'` for gpt/o-series models, and `'unknown'` for unrecognized models.
+
+```js
+import { infer } from 'loreli/identity';
+
+infer('claude-sonnet-4-20250514'); // 'anthropic'
+infer('gpt-4o');                   // 'openai'
+infer('o3-mini');                  // 'openai'
+infer('gemini-pro');               // 'unknown'
+infer(null);                       // 'unknown'
+```
+
+### `side(provider)` → `'yang' | 'yin'`
+
+Resolve the yin/yang side for a provider. Known providers use explicit mappings; unknown providers are assigned deterministically using a stable hash so pairing remains consistent across runs.
+
+```js
+import { side } from 'loreli/identity';
+
+side('openai');            // 'yang'
+side('anthropic');         // 'yin'
+side('cursor-openai');     // 'yang'
+side('cursor-anthropic');  // 'yin'
+```
+
+### `vendor(provider)` → string
+
+Normalize provider names to canonical vendor names for model/config lookups. Cursor virtual providers strip the `cursor-` prefix.
+
+```js
+import { vendor } from 'loreli/identity';
+
+vendor('cursor-openai');    // 'openai'
+vendor('cursor-anthropic'); // 'anthropic'
+vendor('openai');           // 'openai'
+```
+
+### `pick(themes)` → string
+
+Select a single theme from a config value that may be a string or an array of theme names. When given an array, picks one element at random. When given a string, returns it directly. Falls back to `'transformers'` for nullish input.
+
+This is the randomization entry point for multi-theme configs. Callers invoke `pick()` once at the work-item boundary (first agent added), then thread the resolved theme to all subsequent agents in the same work item so antagonist pairs always share the same theme universe.
+
+```js
+import { pick } from 'loreli/identity';
+
+pick('pokemon');                        // 'pokemon'
+pick(['pokemon', 'marvel', 'zelda']);   // random: 'pokemon', 'marvel', or 'zelda'
+pick(null);                             // 'transformers'
+pick(undefined);                        // 'transformers'
+```
+
+### `council(theme)` → string
+
+Get the council authority name for a given theme. Returns `'Council'` as fallback for unknown themes.
+
+```js
+import { council } from 'loreli/identity';
+
+council('transformers'); // 'The Allspark'
+council('pokemon');      // 'Professor Oak'
+council('marvel');       // 'S.H.I.E.L.D.'
+council('unknown');      // 'Council'
+```
+
+### `Identity`
+
+Represents a unique, themed agent identity.
+
+```js
+import { Identity } from 'loreli/identity';
+
+const id = new Identity({
+  name: 'optimus', instance: 0, faction: 'autobots',
+  provider: 'openai', model: 'gpt-4o', theme: 'transformers'
+});
+
+id.name;       // 'optimus-0'
+id.character;  // 'optimus'
+id.faction;    // 'autobots'
+id.provider;   // 'openai'
+id.toJSON();   // serializable plain object
+id.labels();   // ['loreli', 'provider:openai', 'model:gpt-4o']
+id.labels('action'); // ['loreli', 'provider:openai', 'model:gpt-4o', 'role:action']
+id.signoff();  // 'Autobots, roll out!'
+id.signature('action'); // full markdown signature block (see below)
+```
+
+#### Council Identity
+
+For orchestrator-level interactions, create a council identity by omitting `instance` and setting `council: true`. Council identities use the theme's central authority for signoffs and produce names without instance suffixes.
+
+```js
+import { Identity, council } from 'loreli/identity';
+
+const id = new Identity({
+  name: 'Loreli',
+  provider: 'loreli',
+  model: 'mcp',
+  theme: 'transformers',
+  faction: council('transformers'), // 'The Allspark'
+  council: true
+});
+
+id.name;      // 'Loreli' (no instance suffix)
+id.faction;   // 'The Allspark'
+id.signoff(); // 'Till all are one.' (council signoff, not faction)
+```
+
+#### `identity.labels(role?)` → string[]
+
+Generate GitHub label names that identify this agent. Model names are converted to human-readable display names (e.g. `claude-sonnet-4` instead of `claude-sonnet-4-20250514`). Pass an optional `role` to include a `role:` label.
+
+This is the single source of truth for what labels an agent should apply to GitHub issues and PRs.
+
+#### `identity.signoff()` → string
+
+Returns a randomly selected, faction-specific sign-off message from the agent's theme. Each faction has 30 unique messages. The selection is random per call, giving each GitHub interaction a unique personality.
+
+#### `identity.signature(role)` → string
+
+Generates a full markdown signature block for GitHub comments. Every agent communication (claims, approvals, relay output) is stamped with this block, making each interaction traceable to a specific agent, model, and loreli version.
+
+The signature block includes a themed sign-off message above a metadata table:
+
+```markdown
+***
+
+Autobots, roll out! — **optimus-0**
+
+| Agent | Model | Provider | Faction | Role | Version |
+|-------|-------|----------|---------|------|---------|
+| optimus-0 | gpt-4o | openai | autobots | action | `loreli@0.0.0` |
+```
+
+This is automatically appended by claim, signoff, and relay comments in the orchestration workflow.
+
+### `Registry`
+
+Manages identity assignment, tracking, and yin/yang pairing.
+
+```js
+import { Registry } from 'loreli/identity';
+
+const registry = new Registry();
+
+// Acquire an identity
+const agent = registry.acquire('transformers', 'openai', 'gpt-4o');
+// -> Identity { name: 'optimus-0', faction: 'autobots' }
+
+// Find the polar opposite for review
+const opp = registry.opposite(agent);
+// -> { provider: 'anthropic', faction: 'decepticons' }
+
+// List all active identities
+registry.active(); // [Identity, ...]
+
+// Release when agent is done
+registry.release(agent);
+```
+
+#### `registry.acquire(theme, provider, model?)` → Identity
+
+Assigns the next available character name from the theme's faction. Characters are round-robin; when all 10 are used, instance counters increment (e.g. `optimus-0`, then `optimus-1`).
+
+#### `registry.release(identity)`
+
+Returns an identity to the pool.
+
+#### `registry.active()` → Identity[]
+
+Returns all currently active identities.
+
+#### `registry.opposite(identity)` → { provider, faction }
+
+Returns the opposing provider and faction for yin/yang review pairing.
+
+#### `registry.pair(identity, candidates)` → object | null
+
+Find the opposing-provider match from a list of candidates. Each candidate must have an `identity` property with a `provider` field. Returns the first candidate whose provider opposes the given identity, or `null`.
+
+This is the authoritative place for cross-provider matching logic. The orchestrator delegates to this method instead of implementing its own search.
+
+```js
+const action = registry.acquire('transformers', 'openai');
+const reviewers = [
+  { identity: registry.acquire('transformers', 'anthropic'), role: 'reviewer' },
+  { identity: registry.acquire('transformers', 'openai'), role: 'reviewer' }
+];
+
+const match = registry.pair(action, reviewers);
+// → the anthropic reviewer (opposing provider)
+```
+
+#### `identity.proofOfLife(agent)` → string
+
+Returns a randomly selected proof-of-life request message from the theme's **council** — the central authority that transcends the yang/yin faction split. The `{agent}` placeholder in the theme message is replaced with the provided agent name.
+
+Proof-of-life is an orchestrator-level concern (the system checking on its agents), so messages come from the council rather than a faction. Each theme has a named council authority and at least 10 unique messages.
+
+```js
+const id = new Identity({
+  name: 'optimus', instance: 0, faction: 'autobots',
+  provider: 'openai', model: 'gpt-4o', theme: 'transformers'
+});
+
+id.proofOfLife('megatron-0');
+// 'The Allspark calls upon **megatron-0** — report your status.'
+```
+
+Falls back to a plain `Requesting proof of life from **{agent}**` when theme data is missing.
+
+## Council
+
+Each theme includes a `council` section representing the central authority that oversees both factions. The council is used for orchestrator-level interactions like proof-of-life checks, where messages should not be faction-specific. Each council provides:
+
+- `name` — The authority's display name
+- `proofOfLife` — 10 themed messages for liveness checks (use `{agent}` placeholder)
+- `signoffs` — 5 sign-off messages for council-level GitHub comments
+
+| Theme | Council Authority |
+|-------|-------------------|
+| Transformers | The Allspark |
+| Pokemon | Professor Oak |
+| Marvel | S.H.I.E.L.D. |
+| Digimon | Yggdrasil |
+| Star Wars | The Force |
+| LOTR | The Valar |
+| Dragon Ball | Grand Zeno |
+| Avatar | Raava |
+| Zelda | Hylia |
+
+## Themes
+
+| Theme | OpenAI (Yang) | Anthropic (Yin) |
+|-------|---------------|-----------------|
+| `transformers` | Autobots (Optimus, Bumblebee, Jazz, ...) | Decepticons (Megatron, Starscream, ...) |
+| `pokemon` | Fire (Charizard, Arcanine, ...) | Water (Blastoise, Gyarados, ...) |
+| `marvel` | Avengers (IronMan, Captain, Thor, ...) | X-Men (Wolverine, Cyclops, ...) |
+| `digimon` | Vaccine (Agumon, Gabumon, ...) | Virus (Devimon, Myotismon, ...) |
+| `starwars` | Jedi (Luke, Obiwan, Yoda, ...) | Sith (Vader, Palpatine, Maul, ...) |
+| `lotr` | Fellowship (Gandalf, Aragorn, Legolas, ...) | Mordor (Sauron, Saruman, Witchking, ...) |
+| `dragonball` | Z Fighters (Goku, Vegeta, Gohan, ...) | Villains (Frieza, Cell, Buu, ...) |
+| `avatar` | Benders (Aang, Katara, Toph, ...) | Fire Nation (Ozai, Azula, Amon, ...) |
+| `zelda` | Hyrule (Link, Zelda, Impa, ...) | Shadow (Ganondorf, Majora, Zant, ...) |
+
+Each faction contains 10 characters and 30 sign-off messages.
+
+## Sign-Off Messages
+
+Every faction has its own set of themed sign-off messages that are randomly selected for each GitHub comment. Examples:
+
+| Theme | Yang (OpenAI) | Yin (Anthropic) |
+|-------|---------------|-----------------|
+| Transformers | "Autobots, roll out!" | "Peace through tyranny." |
+| Pokemon | "The flame burns bright!" | "Surf's up!" |
+| Marvel | "Avengers, assemble!" | "To me, my X-Men!" |
+| Digimon | "Digivolve into champion!" | "Darkness is the ultimate debugger." |
+| Star Wars | "May the Force be with you." | "I find your lack of tests disturbing." |
+| LOTR | "You shall not pass — without tests!" | "One codebase to rule them all." |
+| Dragon Ball | "It's over 9000 commits!" | "This isn't even my final form." |
+| Avatar | "The code is like water — it flows where it needs to." | "Everything changed when the fire nation committed." |
+| Zelda | "It's dangerous to go alone — take this PR." | "You've met with a terrible fate, haven't you?" |
+
+## Naming Convention
+
+Names follow `{character}-{instance}` where instance increments per reuse: `optimus-0`, `optimus-1`. This ensures uniqueness across sessions.