loreli 0.0.0 → 2.0.0

package/packages/mcp/src/tools/status.js

@@ -0,0 +1,149 @@
+import { has } from 'loreli/marker';
+import { select } from './repo.js';
+import { check } from 'loreli/config';
+
+export default {
+  team_status: {
+    title: 'Team Status',
+    description: 'Dashboard showing open issues, active PRs, agent states, review loops, merged count, and PRs awaiting human review.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository (owner/name).' }
+      }
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Status dashboard.
+     */
+    async exec(args, ctx) {
+      // Validate repo format eagerly before any other guard so callers always
+      // get a thrown error on malformed input regardless of hub state.
+      if (args.repo) check.repo(args.repo);
+
+      // When the user explicitly requests a repo but hub is not initialized,
+      // tell them to run start. This matches the pattern in start_work
+      // and start_planning. We only guard on args.repo (explicit request),
+      // not ctx.repo (set during start) — agent/storage status still
+      // works without GitHub.
+      if (args.repo && !ctx.hub) {
+        return { content: [{ type: 'text', text: 'Run start first to initialize the hub.' }], isError: true };
+      }
+
+      const repo = select(args.repo, ctx);
+      const lines = [`Team Status for ${repo ?? 'unknown repo'}`];
+
+      // --- Agent States ---
+      const orch = ctx.orchestrator;
+      if (orch?.reconcile) await orch.reconcile();
+      const agents = orch ? [...orch.agents.entries()] : [];
+      lines.push('', `Agents: ${agents.length}`);
+
+      for (const [name, agent] of agents) {
+        lines.push(`  ${name} | ${agent.role ?? '?'} | ${agent.state ?? '?'} | ${agent.identity?.provider ?? '?'}`);
+
+        try {
+          if (typeof agent.capture === 'function') {
+            const output = (await agent.capture(20))?.trim();
+            if (output) {
+              lines.push(`  Terminal:\n${output.split('\n').map(function indent(l) { return `    ${l}`; }).join('\n')}`);
+            } else {
+              lines.push('  Terminal: (no output)');
+            }
+          }
+        } catch { lines.push('  Terminal: (unavailable)'); }
+      }
+
+      // --- Live GitHub data (only if hub is available) ---
+      if (ctx.hub && repo) {
+        try {
+          const [openIssues, openPRs, closedPRs] = await Promise.all([
+            ctx.hub.issues(repo, { state: 'open' }),
+            ctx.hub.pulls(repo, { state: 'open' }),
+            ctx.hub.pulls(repo, { state: 'closed' })
+          ]);
+
+          const merged = closedPRs.filter(function isMerged(pr) { return pr.merged; });
+
+          lines.push('', `Open issues: ${openIssues.length}`);
+          lines.push(`Open PRs: ${openPRs.length}`);
+          lines.push(`Merged PRs: ${merged.length}`);
+
+          // Match PRs to agents by branch naming convention: {agent-name}/issue-{number}
+          if (openPRs.length) {
+            lines.push('', 'Active PRs:');
+            for (const pr of openPRs) {
+              const branchMatch = pr.head.match(/^(.+)\/issue-(\d+)$/);
+              const agentName = branchMatch ? branchMatch[1] : 'unknown';
+              const issueNum = branchMatch ? `#${branchMatch[2]}` : '?';
+
+              // Count review rounds
+              let reviewCount = 0;
+              try {
+                const revs = await ctx.hub.reviews(repo, pr.number);
+                reviewCount = revs.length;
+              } catch { /* best-effort */ }
+
+              lines.push(`  PR #${pr.number}: ${pr.title} (agent: ${agentName}, issue: ${issueNum}, reviews: ${reviewCount})`);
+            }
+          }
+        } catch {
+          lines.push('', 'GitHub data: unavailable (hub error)');
+        }
+      }
+
+      // --- Awaiting human review (from GitHub) ---
+      // Derive HITL state from GitHub labels and markers instead of local
+      // session storage. Any participant can see PRs awaiting human
+      // attention via the loreli:needs-attention label and hitl marker.
+      if (ctx.hub && repo) {
+        try {
+          const needsAttention = (await ctx.hub.pulls(repo, { state: 'open' }))
+            .filter(function isGated(pr) {
+              return pr.labels?.some(function isNA(l) {
+                return (l.name ?? l) === 'loreli:needs-attention';
+              });
+            });
+
+          if (needsAttention.length) {
+            lines.push('', `Awaiting human review: ${needsAttention.length}`);
+            for (const pr of needsAttention) {
+              let elapsed = 0;
+              try {
+                const comments = await ctx.hub.comments(repo, pr.number);
+                const hitlComment = comments.find(function isHitl(c) {
+                  return has(c.body, 'hitl');
+                });
+                if (hitlComment) {
+                  const ts = hitlComment.created ?? hitlComment.created_at;
+                  elapsed = Math.round((Date.now() - new Date(ts).getTime()) / 60000);
+                }
+              } catch { /* best-effort */ }
+
+              // Extract reviewers from PR requested_reviewers if available
+              const reviewers = pr.requested_reviewers?.map(function name(r) { return r.login ?? r; }) ?? [];
+
+              lines.push(`  PR #${pr.number}: ${pr.title} — reviewers: ${reviewers.join(', ') || 'none'} — waiting: ${elapsed}m`);
+            }
+          }
+        } catch { /* best-effort — fall through */ }
+      }
+
+      // --- Rate Limit ---
+      if (ctx.hub?.rates) {
+        const rl = ctx.hub.rates();
+        if (rl.remaining !== null) {
+          const pct = rl.ratio !== null ? ` (${Math.round(rl.ratio * 100)}%)` : '';
+          const resetStr = rl.reset ? ` resets ${rl.reset}` : '';
+          lines.push('', `Rate limit: ${rl.remaining}/${rl.limit}${pct}${resetStr}`);
+        }
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }]
+      };
+    }
+  }
+};

package/packages/mcp/src/tools/work.js

@@ -0,0 +1,134 @@
+import { logger } from 'loreli/log';
+import { select } from './repo.js';
+
+const log = logger('work');
+
+/**
+ * Work orchestration tools.
+ *
+ * These tools drive the plan-action-review loop by delegating to
+ * autonomous agents. Agents have their own GitHub access and interact
+ * with the repo directly; the orchestrator monitors via GitHub activity
+ * and tmux capture.
+ */
+export default {
+  start_planning: {
+    title: 'Start Planning',
+    description: 'Activate planner agent(s) to analyze the repository and create draft work items on the GitHub project board.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository (owner/name).' },
+        objective: { type: 'string', description: 'What should the planner analyze and plan for?' }
+      },
+      required: ['objective']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Planning initiation result.
+     */
+    async exec(args, ctx) {
+      const repo = select(args.repo, ctx);
+      const objective = args.objective;
+      if (!repo) {
+        return {
+          content: [{ type: 'text', text: 'No repository configured. Pass --repo, run start, set LORELI_REPO, or set repo in loreli.yml.' }],
+          isError: true
+        };
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Run start first to initialize the hub.' }], isError: true };
+      }
+
+      log.info(`start_planning: ${repo} — ${objective}`);
+
+      // Delegate to planner workflow which handles category discovery, prompt building, and dispatch
+      const result = await ctx.planner.plan(repo, objective);
+
+      // Persist categoryId in context for downstream tools (escalate, etc.)
+      ctx.categoryId = result.categoryId;
+
+      // Start the reactor loop so planner handlers (review, revise, promote)
+      // run automatically. Without this, discussions sit unreviewed forever.
+      ctx.orchestrator.watch(repo);
+      ctx.orchestrator.monitor();
+
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            `Planning initiated for ${repo}`,
+            `Objective: ${objective}`,
+            `Category: Loreli (${result.categoryId})`,
+            `Planners dispatched: ${result.planners.join(', ')}`,
+            'Plan review and promotion will run automatically via the reactor tick pipeline.'
+          ].filter(Boolean).join('\n')
+        }]
+      };
+    }
+  },
+
+  start_work: {
+    title: 'Start Work',
+    description: 'Begin the action/review cycle. Action agents claim issues, do work, and create PRs. Review agents are auto-assigned based on yin/yang pairing.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository (owner/name).' }
+      }
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Work cycle initiation result.
+     */
+    async exec(args, ctx) {
+      const repo = select(args.repo, ctx);
+      if (!repo) {
+        return {
+          content: [{ type: 'text', text: 'No repository configured. Pass --repo, run start, set LORELI_REPO, or set repo in loreli.yml.' }],
+          isError: true
+        };
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Run start first to initialize the hub.' }], isError: true };
+      }
+
+      const actionAgents = ctx.action.agents?.() ?? [];
+      if (!actionAgents.length) {
+        throw new Error('No action agents available. Add an agent first.');
+      }
+
+      log.info(`start_work: ${repo}`);
+
+      // Delegate to action workflow which handles claim, label, prompt, dispatch
+      const assignments = await ctx.action.work(repo);
+
+      // Start stall detection monitor and the PR lifecycle reactor
+      ctx.orchestrator.monitor();
+      ctx.orchestrator.watch(repo);
+
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            `Work cycle started for ${repo}`,
+            `Assigned: ${assignments.length}`,
+            '',
+            ...assignments.map(function format(a) {
+              return `#${a.issue} -> ${a.agent} (reviewer: ${a.reviewer ?? 'none'})`;
+            })
+          ].join('\n')
+        }]
+      };
+    }
+  },
+
+  // propose and escalate have been consolidated into the `plan` agent tool
+  // in packages/mcp/src/tools/github.js — see plan action=create and action=escalate
+};

package/packages/orchestrator/README.md

@@ -0,0 +1,192 @@
+# loreli/orchestrator
+
+Generic agent lifecycle coordination via EventEmitter. Manages agent spawn/shutdown/kill, reactor polling, stall detection, and activity tracking. Contains zero role-specific logic — all planner/action/review behavior lives in the role packages.
+
+## Research Findings
+
+Node.js built-in `EventEmitter` provides everything needed for lifecycle event dispatch. No external libraries required.
+
+## API Reference
+
+### `Orchestrator` (extends EventEmitter)
+
+```js
+import { Orchestrator } from 'loreli/orchestrator';
+
+const orch = new Orchestrator({
+  hub, identityRegistry, backendRegistry, storage, config
+});
+```
+
+#### Constructor Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `hub` | `BaseHub` | Git hosting abstraction |
+| `identityRegistry` | `Registry` | Identity assignment and pairing |
+| `backendRegistry` | `BackendRegistry` | CLI backend discovery |
+| `storage` | `Storage` | Session persistence |
+| `config` | `Config` | Optional runtime config |
+
+### Lifecycle Methods
+
+#### `orchestrator.spawn(agent)` → Promise\<void\>
+
+Spawn and register an agent with rollback support. Each step (process start, map registration, activity tracking) is tracked and reversed on failure.
+
+**Emits**: `'spawned'` with `{ name, role, provider }`
+
+#### `orchestrator.shutdown(name, timeout?, reason?)` → Promise\<{acknowledged}\>
+
+Graceful 3-phase shutdown: send request, poll for acknowledgment, force stop.
+
+**Emits**: `'removed'` with `{ name, reason: 'shutdown' }`
+
+#### `orchestrator.kill(name)` → Promise\<void\>
+
+Immediate termination. Last resort for stuck agents.
+
+**Emits**: `'removed'` with `{ name, reason: 'killed' }`
+
+### Coordination Methods
+
+#### `orchestrator.enlist(provider, role, opts?)` → Promise\<object\>
+
+Create and spawn a new agent via the Factory.
+
+#### `orchestrator.activity(name)` → void
+
+Record a heartbeat timestamp for an agent. Resets the stall timer. Called by workflow packages when they dispatch work to an agent.
+
+#### `orchestrator.refresh(name)` → Promise\<boolean\>
+
+Check whether an agent's tmux pane has new output since the last check. When output changes, the agent is provably active — `_lastActivity` is updated and `true` is returned. This is the ground truth signal that feeds into `health()` and, transitively, the proof-of-life responder.
+
+Agent-side MCP tool calls (file reads, code analysis, `pr review`) don't update `_lastActivity` because the agent's MCP server runs in a separate process. But every agent action produces terminal output, which `refresh()` detects by comparing MD5 hashes of the last 50 lines of captured pane output.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Agent identity name |
+
+**Returns**: `true` when pane output changed (agent is active), `false` otherwise.
+
+#### `orchestrator.health(name)` → Promise\<{alive, status, details, outputLength?}\>
+
+Multi-signal health assessment for a named agent. Evaluates tmux/process liveness, agent state machine, tmux pane activity (via `refresh()`), and activity recency.
+
+| Signal | Check | Unhealthy When |
+|--------|-------|----------------|
+| Process | `agent.alive()` — is the tmux pane alive? | Pane is dead |
+| State | `agent.state` — is the agent dormant? | State is `dormant` |
+| Pane activity | `refresh()` — has tmux output changed? | (Updates `_lastActivity` if changed) |
+| Activity | `_lastActivity` timestamp vs stall timeout | Last activity exceeds stall timeout |
+| Output | `agent.capture()` — terminal output length | Included for diagnostics (not a failure signal) |
+
+**Returns**: `{ alive: boolean, status: 'healthy' | 'unhealthy' | 'not-found', details: string, outputLength?: number }`
+
+Used by the proof-of-life reactor responder to answer liveness queries. The `refresh()` call inside `health()` ensures that agents actively working (producing terminal output) are reported as healthy even when `_lastActivity` is stale — this is what makes PoL verdicts accurate for local agents.
+
+#### `orchestrator._removed` → Set\<string\>
+
+Tracks agents locally killed or shut down during this orchestrator's lifetime. Populated by `kill()` and `shutdown()`. Used by workflow eviction logic to distinguish between genuinely foreign agents (from other orchestrators) and agents this orchestrator already cleaned up — preventing unnecessary proof-of-life network calls.
+
+### Scaling
+
+#### `orchestrator.scale(repo)` → Promise\<Array\<{role, agent}\>\>
+
+Demand-driven scaling: collect demand signals from all registered workflows, then spawn agents to fill deficits — respecting global caps, per-role caps, rate limits, and cooldowns.
+
+Runs after all workflow handlers in the reactor chain so demand signals reflect the latest hydrated state. Spawns are capped by `maxPerTick` to avoid resource spikes.
+
+**Priority order**: reviewer > risk > action > planner. Reviewers unblock merges, risk unblocks reviewers, so they are filled first when at the global cap.
+
+**Cross-provider preference with topology fallback**: Reviewer and risk agents are spawned on the opposite side (yin/yang) of the action agents they will pair with when dual-side capability exists. In single-side environments, `scale()` falls back to same-side spawning so review/risk coverage remains functional.
+
+**Provider alternation**: When spawning multiple agents for a role, providers are alternated (yin/yang) to maintain adversarial diversity.
+
+**Provider alternation** ensures adversarial diversity. All backends (Claude, Cursor, Codex) are interactive and equally suitable for any role.
+
+```js
+const spawned = await orchestrator.scale('owner/repo');
+// [{ role: 'reviewer', agent: 'jazz-0' }, { role: 'action', agent: 'optimus-1' }]
+```
+
+#### `orchestrator.workflows` → Map\<string, Workflow\>
+
+Map of role name to workflow instance. Populated during start. Used by `scale()` to collect demand signals.
+
+### Reactor (Polling Loop)
+
+#### `orchestrator.register(name, handler)` → void
+
+Register a reactor handler called on every tick.
+
+#### `orchestrator.tick(repo)` → Promise\<void\>
+
+Execute one polling iteration: call all registered handlers.
+
+#### `orchestrator.watch(repo)` → void
+
+Start the polling reactor loop on a configurable interval.
+
+#### `orchestrator.unwatch()` → void
+
+Stop the polling reactor loop.
+
+### Monitor (Stall Detection)
+
+#### `orchestrator.monitor()` → void
+
+Start stall detection with 3-tier escalation:
+- **Tier 1** (1x timeout): Nudge agent with a status request
+- **Tier 2** (2x timeout): Emit `'stall'` event with severity `'warning'`
+- **Tier 3** (3x timeout): Kill agent and emit `'stall'` with `'critical'`
+
+**Emits**: `'stall'` with `{ name, elapsed, severity }`
+
+This serves as the safety net for agents that become stuck despite the autonomous-mode directives in their prompt templates. All agent prompts (action, planner, reviewer) include explicit instructions prohibiting interactive behavior — but if an agent ignores those directives and blocks on user input, stall detection will eventually kill it and release the claimed work for re-dispatch.
+
+#### `orchestrator.stopMonitor()` → void
+
+Stop the stall detection interval.
+
+### Death Snapshots
+
+#### `orchestrator.snapshot(name, agent)` -> Promise\<void\>
+
+Capture a dying agent's terminal output and persist it to `~/.loreli/sessions/<sessionId>/logs/<name>.death.log`. Called automatically before `agent.stop()` in all exit paths (`reconcile`, `kill`, `shutdown`) so diagnostic output is never lost.
+
+Requires `remain-on-exit` on the agent's tmux pane — interactive agents (`CliAgent.spawn()`) set this automatically so the pane survives after the process exits, preserving output for capture.
+
+Non-fatal: silently skips when session or storage is unavailable, or when pane capture fails. Death snapshots are subject to the same session cleanup lifecycle as other session data — `Storage.prune()` removes them when the session expires.
+
+```
+~/.loreli/sessions/<sessionId>/logs/
+  optimus-0.death.log     # captured terminal output at time of death
+  megatron-0.death.log
+```
+
+### Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `spawned` | `{ name, role, provider }` | Agent successfully spawned |
+| `removed` | `{ name, reason }` | Agent shut down or killed |
+| `stall` | `{ name, elapsed, severity }` | Stall threshold exceeded |
+| `rapid-death` | `{ name, backend, reason? }` | Agent died within seconds of spawn |
+
+Role packages subscribe to these events via their `events()` method on the Workflow base class. The orchestrator itself never posts GitHub comments or claims issues — that's the role packages' responsibility.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `Agent "{name}" not found` | shutdown/kill called with unknown name | Check agent exists via `agents` Map |
+| `Spawn failed` | Agent process could not start | Check backend CLI availability |
+| `No backends available` | Factory has no discovered backends | Run `backendRegistry.discover()` |
+
+## Scope Boundary
+
+**In scope**: Agent lifecycle (spawn, shutdown, kill), reactor polling, stall detection, activity tracking, event emission, demand-driven scaling, agent health assessment.
+
+**Out of scope**: Role-specific logic (claiming, reviewing, planning), GitHub comments, prompt rendering, workspace preparation.