loreli 0.0.0 → 1.0.0

package/bin/loreli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Loreli CLI entry point.
+ *
+ * Uses @mcp-layer/cli to expose a single custom command (`mcp`) that starts
+ * the MCP server. All MCP tools, prompts, and resources are automatically
+ * exposed as CLI commands by the framework (e.g. `loreli tools list`,
+ * `loreli tools start --repo owner/repo`).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadEnv } from 'loreli/config';
+import { cli } from '@mcp-layer/cli';
+
+/**
+ * Error message shown when tmux is missing from PATH.
+ *
+ * @type {string}
+ */
+const TMUX_MISSING = [
+  'tmux is required to run Loreli.',
+  '',
+  'Install it and re-run the command:',
+  '  macOS (Homebrew): brew install tmux',
+  '  Linux (APT): sudo apt install tmux',
+  '',
+  'If tmux is already installed, run `command -v tmux` to verify PATH.',
+  'See README: https://github.com/3rd-Eden/loreli#prerequisites',
+].join('\n');
+
+/**
+ * Preflight evaluation that ensures tmux is on PATH before the CLI runs.
+ *
+ * @throws {Error} When tmux is missing from PATH.
+ * @returns {void}
+ */
+(function preflight() {
+  try {
+    execFileSync('which', ['tmux'], { stdio: 'ignore' });
+  } catch {
+    throw new Error(TMUX_MISSING);
+  }
+}());
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+// Load .env before anything else so GITHUB_TOKEN and other vars are
+// available to every subsystem. Silent no-op when no .env file exists.
+loadEnv();
+
+/**
+ * Build and execute the CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  return await cli({
+    name: pkg.name,
+    version: pkg.version,
+    description: pkg.description,
+    server: 'loreli',
+    showServers: false
+  })
+  .command({
+    name: 'mcp',
+    description: 'Start the MCP server',
+    details: 'Starts the Loreli MCP server with stdio transport for client connections.',
+    examples: [
+      'loreli mcp',
+    ]
+  }, async function start(argv, { spinner }) {
+    const done = spinner('Starting Loreli MCP server');
+    const { Loreli } = await import('loreli/mcp');
+    const loreli = new Loreli();
+    await loreli.start();
+    done();
+  })
+  .render();
+}
+
+main().catch(function fatal(err) {
+  console.error('loreli:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,23 +1,83 @@
 {
   "name": "loreli",
-  "version": "0.0.0",
-  "description": "Loreli is an agentic system that uses the GitHub patterns we're familiar with for orchestration. Issues becomes actions for agents. Pull Requests are review tasks. Discussions are where plans are discussed and then raised as issues on approval. The system uses an antagonist style where OpenAI will always be checked by Antrophic, ensuring you get input from both models.",
-  "keywords": [
-    "loreli",
-    "github",
-    "agentic",
-    "system",
-    "orchestration"
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Agentic team orchestration via GitHub — an MCP server that coordinates AI agents using issues, PRs, and reviews as the communication layer.",
+  "exports": {
+    "./tmux": "./packages/tmux/src/index.js",
+    "./log": "./packages/log/src/index.js",
+    "./hub": "./packages/hub/src/index.js",
+    "./identity": "./packages/identity/src/index.js",
+    "./agent": "./packages/agent/src/index.js",
+    "./config": "./packages/config/src/index.js",
+    "./workspace": "./packages/workspace/src/index.js",
+    "./workflow": "./packages/workflow/src/index.js",
+    "./orchestrator": "./packages/orchestrator/src/index.js",
+    "./planner": "./packages/planner/src/index.js",
+    "./action": "./packages/action/src/index.js",
+    "./risk": "./packages/risk/src/index.js",
+    "./review": "./packages/review/src/index.js",
+    "./session": "./packages/session/src/index.js",
+    "./marker": "./packages/marker/src/index.js",
+    "./knowledge": "./packages/knowledge/src/index.js",
+    "./context": "./packages/context/src/index.js",
+    "./test-utils": "./packages/test-utils/src/index.js",
+    "./mcp": "./packages/mcp/src/index.js"
+  },
+  "bin": {
+    "loreli": "./bin/loreli.js"
+  },
+  "scripts": {
+    "pretest": "node --env-file-if-exists=.env scripts/clean-test-repo.js",
+    "test": "node --env-file-if-exists=.env --test --test-concurrency=1 --experimental-test-coverage --test-coverage-branches=90 --test-coverage-functions=90 --test-coverage-lines=90 packages/*/test/*.test.js",
+    "test:ci": "LORELI_TEST_MODE=unit node --env-file-if-exists=.env --test --test-concurrency=1 packages/*/test/*.test.js",
+    "e2e": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js e2e/multi/*.test.js",
+    "e2e:single": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/single/*.test.js",
+    "e2e:multi": "node --env-file-if-exists=.env scripts/clean-test-repo.js && node --env-file-if-exists=.env --test --test-concurrency=1 e2e/multi/*.test.js",
+    "lint:secrets": "npx secretlint \"**/*\"",
+    "prepublishOnly": "pnpm lint:secrets",
+    "prepare": "node node_modules/pre-commit/install.js && node node_modules/pre-push/install.js"
+  },
+  "pre-commit": [
+    "lint:secrets"
+  ],
+  "pre-push": [
+    "lint:secrets"
   ],
+  "dependencies": {
+    "@mcp-layer/cli": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@octokit/rest": "^21.1.1",
+    "@secretlint/secretlint-rule-preset-recommend": "^11.3.1",
+    "ms": "^2.1.3",
+    "mustache": "^4.2.0",
+    "secretlint": "^11.3.1",
+    "text-hex": "^1.0.0",
+    "winston": "^3.17.0",
+    "yaml": "^2.8.1"
+  },
   "repository": {
     "type": "git",
-    "url": "github.com/3rd-Eden/loreli"
+    "url": "https://github.com/3rd-Eden/loreli.git"
+  },
+  "homepage": "https://www.npmjs.com/package/loreli",
+  "engines": {
+    "node": ">=24"
   },
+  "files": [
+    "bin/",
+    "packages/*/src/**",
+    "packages/*/README.md",
+    "packages/README.md",
+    "packages/*/prompts/",
+    "packages/mcp/scaffolding/",
+    "packages/mcp/instructions.md",
+    "LICENSE",
+    "README.md"
+  ],
   "license": "MIT",
-  "author": "Arnout Kazemier",
-  "type": "module",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "devDependencies": {
+    "pre-commit": "^1.2.2",
+    "pre-push": "^0.1.4"
   }
 }

package/packages/README.md

@@ -0,0 +1,101 @@
+# Package Development Guide
+
+This document is for contributors and maintainers working on Loreli internals.
+
+For installation, setup, and operating Loreli as a consumer, use the root guide: [`README.md`](../README.md).
+
+## Published Package Documentation
+
+Loreli exposes subpath imports (for example, `loreli/mcp`, `loreli/agent`, `loreli/context`) through the root package `exports` map.
+Each exported subpackage has a README under `packages/<name>/README.md`, and these package READMEs are included in the published npm tarball.
+
+## Architecture
+
+```mermaid
+graph TD
+  User["User / Parent Agent"] -->|"MCP tools"| Server["loreli/mcp"]
+  Server -->|"spawns via tmux"| Claude["Claude Backend"]
+  Server -->|"spawns via tmux"| Cursor["Cursor Backend"]
+  Server -->|"spawns via tmux"| Codex["Codex Backend"]
+  Server --> Orch["loreli/orchestrator"]
+  Orch --> Planner["loreli/planner"]
+  Orch --> Action["loreli/action"]
+  Orch --> Review["loreli/review"]
+  Planner -->|"Discussions"| GH["GitHub API"]
+  Action -->|"Issues + PRs"| GH
+  Review -->|"PR Reviews"| GH
+  Server -->|"reads"| Config["loreli/config"]
+  Config -->|"loreli.yml"| GH
+  Server -->|"loreli/hub"| GH
+  Claude -->|"interactive"| GH
+  Cursor -->|"interactive, multi-provider"| GH
+  Codex -->|"interactive"| GH
+```
+
+## Subpackage Index
+
+| Import | Purpose | Documentation |
+|--------|---------|---------------|
+| `loreli/mcp` | MCP server with orchestration tools, workflow engine, and CLI entry | [`packages/mcp/README.md`](./mcp/README.md) |
+| `loreli/orchestrator` | Agent lifecycle coordination, reactor polling, stall detection | [`packages/orchestrator/README.md`](./orchestrator/README.md) |
+| `loreli/config` | Configuration loading, schema, and layered resolution | [`packages/config/README.md`](./config/README.md) |
+| `loreli/hub` | Provider-agnostic git hosting abstraction for GitHub APIs | [`packages/hub/README.md`](./hub/README.md) |
+| `loreli/agent` | Agent lifecycle and backend implementations | [`packages/agent/README.md`](./agent/README.md) |
+| `loreli/identity` | Theme-driven agent identity generation and pairing | [`packages/identity/README.md`](./identity/README.md) |
+| `loreli/tmux` | Node.js wrapper for tmux session and pane management | [`packages/tmux/README.md`](./tmux/README.md) |
+| `loreli/workspace` | Worktree lifecycle, workspace scaffolding, and git operations | [`packages/workspace/README.md`](./workspace/README.md) |
+| `loreli/session` | Persistent detached session storage and lifecycle | [`packages/session/README.md`](./session/README.md) |
+| `loreli/log` | Structured logging with per-session and per-agent context | [`packages/log/README.md`](./log/README.md) |
+| `loreli/workflow` | Base abstractions for role workflows and prompt rendering | [`packages/workflow/README.md`](./workflow/README.md) |
+| `loreli/planner` | Planning workflow via GitHub Discussions | [`packages/planner/README.md`](./planner/README.md) |
+| `loreli/action` | Issue claim-work PR execution workflow | [`packages/action/README.md`](./action/README.md) |
+| `loreli/review` | PR review workflow, signoff, and merge gating | [`packages/review/README.md`](./review/README.md) |
+| `loreli/risk` | Risk assessment workflow for pull requests | [`packages/risk/README.md`](./risk/README.md) |
+| `loreli/context` | Read-path context resolution across git and GitHub artifacts | [`packages/context/README.md`](./context/README.md) |
+| `loreli/knowledge` | Feedback classification and promotion workflow | [`packages/knowledge/README.md`](./knowledge/README.md) |
+| `loreli/marker` | Machine-readable marker parsing and serialization | [`packages/marker/README.md`](./marker/README.md) |
+| `loreli/test-utils` | Shared test helpers and integration test guards | [`packages/test-utils/README.md`](./test-utils/README.md) |
+
+## Development
+
+The example below demonstrates the standard setup and test commands for developing Loreli. This matters because local development requires a working dependency install and consistent test expectations, and you should expect each command to complete without errors with tests reporting pass or skip states.
+
+```bash
+# Setup
+cp .env.example .env   # then fill in GITHUB_TOKEN
+pnpm install
+
+# Run tests (includes --experimental-test-coverage)
+pnpm test
+
+# Run a specific package's tests
+node --test packages/tmux/test/index.test.js
+
+# Run end-to-end tests (requires LORELI_TEST_REPO)
+pnpm e2e
+```
+
+For CI or local unit-only runs, set `LORELI_TEST_MODE=unit` and use `pnpm test:ci`. This matters because it disables backend-dependent agentic suites, and you should expect those suites to be skipped with a clear reason.
+
+Secret scanning runs automatically on commit, git push, and npm publish. This matters because it keeps credentials from ever reaching npm or GitHub, and the expected behavior is a failed commit/push/publish with a secretlint report if anything suspicious is detected. The example below shows the manual scan command; you should expect a clean exit on success or a secretlint report when issues are found.
+
+```bash
+pnpm lint:secrets
+```
+
+## Test Utilities
+
+Integration-test helpers live in [`packages/test-utils/README.md`](./test-utils/README.md).
+
+Key shared values used by tests:
+
+| Name | Source | Purpose |
+|------|--------|---------|
+| `TEST_REPO` | `LORELI_TEST_REPO` env var | Target GitHub repo for integration/e2e tests. |
+| `TEST_SESSION` | `loreli-test-<pid>` | Per-process tmux session name used by test agents. |
+
+Common usage pattern:
+
+1. Guard tests with `skipWithoutToken()` and `skipWithoutTestRepo()`.
+2. Create real clients/helpers with `createHub()` and `createConfig()`.
+3. Use `resetTestSession()`/`killTestSession()` around suites that spawn agents.

package/packages/action/README.md

@@ -0,0 +1,98 @@
+# loreli/action
+
+Action workflow for Loreli's orchestration pipeline. Extends the `Workflow` base class to manage action agents — issue claiming, work dispatch, rework from human feedback, and the claim protocol.
+
+## Research Findings
+
+No existing npm packages cover a claim-work-review cycle with cross-provider pairing. This is domain-specific to Loreli's orchestration model.
+
+## API Reference
+
+### `ActionWorkflow` (extends Workflow)
+
+```js
+import { ActionWorkflow } from 'loreli/action';
+
+const action = new ActionWorkflow(orchestrator, hub);
+```
+
+#### Static Properties
+
+| Property | Value | Description |
+|----------|-------|-------------|
+| `role` | `'action'` | Agent role this workflow manages |
+| `template` | `prompts/action.md` | Mustache template for action prompts |
+
+### Methods
+
+#### `action.work(repo)` → Promise\<Array\<{issue, agent, reviewer}\>\>
+
+Dispatch the work cycle to action agents. Fetches unclaimed issues, assigns them round-robin to action agents, pairs each with an opposing-provider reviewer (auto-enlisting if needed), claims issues on GitHub, and renders/sends the action prompt.
+
+```js
+const assignments = await action.work('owner/repo');
+// [{ issue: 42, agent: 'optimus-0', reviewer: 'megatron-0' }]
+```
+
+#### `action.rework(repo, pr, feedback)` → Promise\<{reworkAgent, hitlAt}\>
+
+Handle human feedback on an HITL PR by dispatching to an existing action agent or spawning a fresh one. Renders the HITL section of the action prompt.
+
+#### `action.claim(repo, number)` → Promise\<void\>
+
+Post a claim comment on an issue using the hub's scoped identity.
+
+#### `action.claimant(repo, number)` → Promise\<string|null\>
+
+Determine who claimed an issue by parsing claim comments.
+
+### Reactor Handlers
+
+The action workflow registers a `dispatch` handler that runs on every reactor tick. It checks for unclaimed `loreli`-labeled issues and dispatches available existing agents (`spawned` or `dormant`). Agent creation is handled by orchestrator scaling (`scale()`), not by `dispatch()` itself.
+
+The reactive cycle is: spawn on demand, do work, get reaped when idle. On the next tick, if more work exists, another agent spawns.
+
+### Foreign Claim Gating
+
+When `dispatch()` encounters an issue claimed by an agent not in the local orchestrator's map, it classifies the claim before acting:
+
+| `_stale()` result | Meaning | Action |
+|-------------------|---------|--------|
+| `false` | Agent is local and active | Skip — already being worked |
+| `true` | Agent was locally killed/shut down, or is dormant | Release claim immediately |
+| `'foreign'` | Agent belongs to another orchestrator | Run proof-of-life protocol |
+
+For foreign claims, `_checkForeignClaim()` runs the four-gate eviction protocol (see root README) before releasing. This prevents an orchestrator restart from duplicating work that another orchestrator's agents are still actively performing.
+
+### Circuit Breaker
+
+The `_dispatch()` handler includes a circuit breaker to prevent infinite retry loops. After `maxClaims` (default 3) releases on a single issue, the issue is labeled `loreli:blocked` + `loreli:needs-attention` and skipped on all subsequent ticks.
+
+The circuit breaker counts `release` markers only after the most recent **high-water mark** — either a `circuit-breaker` marker (embedded in the escalation comment) or a `restart` marker (posted by the review workflow's `_restartAction()`). This ensures:
+
+- **System-initiated restarts** (dead action agent → `_restartAction()` posts `restart`) automatically reset the counter.
+- **Human unblock** (remove `loreli:blocked` label) works correctly — the escalation comment's `circuit-breaker` marker serves as the high-water mark, so zero releases exist after it.
+
+The escalation comment includes step-by-step guidance for humans: check closed PRs for failure patterns, review the issue description, update acceptance criteria, and remove the `loreli:blocked` label to retry.
+
+### Restart Marker
+
+The `restart` marker (`<!-- loreli:restart agent="..." -->`) is recognized by `claimant()` as a claim release (same as `release`) but also resets the circuit breaker counter. It is posted by the review workflow's `_restartAction()` when a dead action agent is detected during feedback forwarding.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `No action agents available` | work() called with no action agents and no backends discovered | Ensure at least one backend CLI is on PATH |
+
+## Autonomous Operation
+
+Action agents run in headless tmux panes with no human operator. The `Workflow.render()` method automatically prepends a shared autonomous-mode preamble to every rendered prompt, instructing agents to never ask clarifying questions, skip interactive skills, and proceed with best judgment. See the `loreli/workflow` README for details on the preamble.
+
+The orchestrator's 3-tier stall detection (`monitor()`) acts as a safety net: agents that stall despite these directives receive a nudge at 1x timeout, a warning at 2x, and are killed at 3x. See the `loreli/orchestrator` README for details.
+
+## Scope Boundary
+
+**In scope**: Issue claiming, work dispatch, rework, action prompt rendering, claim protocol.
+
+**Out of scope**: PR review (review package), planning (planner package), agent lifecycle (orchestrator).