loreli 0.0.0 → 2.0.0

package/packages/risk/src/index.js

@@ -0,0 +1,439 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Workflow } from 'loreli/workflow';
+import { logger } from 'loreli/log';
+import { mark, has, parse } from 'loreli/marker';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const log = logger('risk');
+
+/**
+ * Pattern matching GitHub's issue-closing keywords in PR bodies.
+ * Captures the issue number from "Closes #N", "Fixes #N", etc.
+ *
+ * @type {RegExp}
+ */
+const CLOSES_RE = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/i;
+
+/**
+ * Risk assessment workflow for Loreli's orchestration pipeline.
+ *
+ * Manages risk agents — dispatching them for new PRs, reading their
+ * verdicts, applying risk labels, and routing CRITICAL PRs to HITL.
+ * Runs before ReviewWorkflow in the reactor chain so labels are
+ * applied before scan() checks for them.
+ *
+ * The contract with ReviewWorkflow is GitHub labels:
+ * - `loreli:low-risk` — PR cleared for normal review
+ * - `loreli:medium-risk` — PR cleared with risk context warning
+ * - `loreli:critical-risk` — PR escalated to HITL, no reviewer dispatched
+ * - `loreli:risk-unassessed` — assessment failed; escalated to HITL (fail-safe)
+ *
+ * @extends Workflow
+ */
+export class RiskWorkflow extends Workflow {
+  /** @type {string} Agent role this workflow manages. */
+  static role = 'risk';
+
+  /** @type {string} Mustache template path for risk prompts. */
+  static template = join(__dirname, '..', 'prompts', 'risk.md');
+
+  /**
+   * PRs awaiting risk assessment before reviewer dispatch.
+   * Keys are PR numbers, values are { riskAgent, dispatchedAt }.
+   *
+   * @type {Map<number, {riskAgent: string, dispatchedAt: number}>}
+   */
+  _assessing = new Map();
+
+  /**
+   * PRs that have completed risk assessment (verdict received or timed out).
+   * Prevents assess() from re-dispatching risk agents for already-handled PRs.
+   *
+   * @type {Set<number>}
+   */
+  _assessed = new Set();
+
+  /**
+   * Report risk demand: how many PRs need risk assessment vs how many
+   * risk agents are active. Uses hydrated state so no extra API calls.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(repo) {
+    const skip = this.orchestrator.cfg?.get?.('workflows.risk.skip') ?? false;
+    if (skip) return { workload: 0, supply: 0, deficit: 0 };
+
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+
+    let workload = 0;
+    for (const pr of prs) {
+      if (this._assessing.has(pr.number)) continue;
+      if (this._assessed.has(pr.number)) continue;
+
+      const hasRiskLabel = pr.labels?.some(function isRisk(l) {
+        const name = l.name ?? l;
+        return (name.endsWith('-risk') || name === 'loreli:risk-unassessed') && name.startsWith('loreli:');
+      });
+      if (hasRiskLabel) continue;
+
+      workload++;
+    }
+
+    const supply = this._assessing.size;
+
+    return { workload, supply, deficit: Math.max(0, workload - supply) };
+  }
+
+  /**
+   * Register reactor handlers for the orchestrator's tick loop.
+   * Hydrate → Assess → Verdict → Reap runs sequentially on each tick,
+   * before ReviewWorkflow's scan() so labels are applied first.
+   *
+   * @returns {Record<string, function>} Handler map.
+   */
+  reactor() {
+    const self = this;
+    return {
+      async 'risk-hydrate'(repo) { await self.hydrate(repo); },
+      async assess(repo) { await self.assess(repo); },
+      async verdict(repo) { await self.verdict(repo); },
+      async 'risk-reap'(repo) { await self.reap(repo); }
+    };
+  }
+
+  /**
+   * Rehydrate in-memory risk state from GitHub artifacts.
+   *
+   * Called at the start of each reactor tick so that PRs assessed or
+   * being assessed by other participants are visible to verdict() and
+   * reap(). Without this, a process that restarts (or a second
+   * participant) would miss PRs already in the assessment pipeline.
+   *
+   * Derives state from two sources:
+   * - `loreli:*-risk` labels → marks PR as assessed
+   * - `risk-claim` marker comments → marks PR as mid-assessment
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async hydrate(repo) {
+    if (!this.hub) return;
+
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+
+    for (const pr of prs) {
+      if (this._assessing.has(pr.number) || this._assessed.has(pr.number)) continue;
+
+      const hasRiskLabel = pr.labels?.some(function isRisk(l) {
+        const name = l.name ?? l;
+        return (name.endsWith('-risk') || name === 'loreli:risk-unassessed') && name.startsWith('loreli:');
+      });
+      if (hasRiskLabel) {
+        this._assessed.add(pr.number);
+        continue;
+      }
+
+      const comments = await this.hub.comments(repo, pr.number);
+      const riskClaim = comments.find(function isClaim(c) { return has(c.body, 'risk-claim'); });
+      if (!riskClaim) continue;
+
+      // Verdict already posted → assessed
+      const hasVerdict = comments.some(function isVerdict(c) { return has(c.body, 'risk'); });
+      if (hasVerdict) {
+        this._assessed.add(pr.number);
+      } else {
+        const agentName = parse(riskClaim.body, 'risk-claim')?.agent;
+        this._assessing.set(pr.number, {
+          riskAgent: agentName ?? 'unknown',
+          dispatchedAt: new Date(riskClaim.created ?? riskClaim.created_at).getTime()
+        });
+      }
+    }
+  }
+
+  // ── Helpers ───────────────────────────────────────────
+
+  /**
+   * Extract the first "Closes #N" or "Fixes #N" issue number from a body.
+   *
+   * @param {string} body - PR or issue body.
+   * @returns {number|null} Issue number, or null if not found.
+   */
+  closesIssue(body) {
+    if (!body) return null;
+    const m = body.match(CLOSES_RE);
+    return m ? parseInt(m[1], 10) : null;
+  }
+
+  /**
+   * Resolve the planning objective from the parent issue.
+   * Finds parent via loreli:parent label and sub-issue linkage.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} childNumber - Child issue number (from Closes #N).
+   * @returns {Promise<string>} Objective string, or fallback.
+   */
+  async objective(repo, childNumber) {
+    const parents = await this.hub.issues(repo, { state: 'open', labels: ['loreli:parent'] });
+    const confirmed = parents.filter(function withMarker(i) { return has(i.body, 'parent'); });
+
+    for (const parent of confirmed) {
+      let subs;
+      try {
+        subs = await this.hub.subs(repo, parent.number);
+      } catch {
+        continue;
+      }
+      const isChild = subs.some(function match(s) { return s.number === childNumber; });
+      if (isChild) {
+        const data = parse(parent.body, 'parent');
+        return data?.objective ?? 'Planning objective';
+      }
+    }
+    return 'Planning objective';
+  }
+
+  // ── Assess ───────────────────────────────────────────
+
+  /**
+   * Scan for new PRs from action agents and dispatch risk agents.
+   * Only targets PRs that haven't been assessed yet and don't already
+   * have a risk label. Gathers diff, file stats, issue body, and
+   * planning objective as context for the risk agent.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{pr: number, agent: string}>>}
+   */
+  async assess(repo) {
+    const skip = this.orchestrator.cfg?.get?.('workflows.risk.skip') ?? false;
+    if (skip) return [];
+
+    const dispatched = [];
+    const prs = await this.hub.pulls(repo, { state: 'open' });
+    const actions = [...this.orchestrator.agents.values()]
+      .filter(function isAction(a) { return a.role === 'action'; });
+
+    for (const pr of prs) {
+      if (this._assessing.has(pr.number)) continue;
+      if (this._assessed.has(pr.number)) continue;
+
+      // Skip PRs that already have a risk label (from a previous assessment)
+      // or a risk-unassessed label (from a failed assessment)
+      const hasRiskLabel = pr.labels?.some(function isRisk(l) {
+        const name = l.name ?? l;
+        return (name.endsWith('-risk') || name === 'loreli:risk-unassessed') && name.startsWith('loreli:');
+      });
+      if (hasRiskLabel) continue;
+
+      const agent = actions.find(function owns(a) {
+        return pr.head.startsWith(a.identity.name + '/');
+      });
+      if (!agent) continue;
+
+      // Verify a risk agent is available BEFORE claiming. Claiming
+      // without an available agent creates a deadlock: hydrate() sees the
+      // claim on the next tick, adds the PR to _assessing, and assess()
+      // skips it forever — but no agent was dispatched.
+      const riskAgents = this.agents().filter(function ready(a) {
+        return a.state === 'spawned' || a.state === 'working';
+      });
+      const assessing = this._assessing;
+      const riskAgent = riskAgents.find(function free(a) {
+        return ![...assessing.values()].some(function busy(t) { return t.riskAgent === a.identity.name; });
+      });
+      if (!riskAgent) {
+        log.debug(`assess: no risk agent available for PR #${pr.number} — waiting for scale()`);
+        continue;
+      }
+
+      // Check for existing risk-claim marker — another participant
+      // may have already dispatched a risk agent for this PR.
+      const prComments = await this.hub.comments(repo, pr.number);
+      if (prComments.some(function isClaimed(c) { return has(c.body, 'risk-claim'); })) continue;
+
+      // Optimistic claim: post a risk-claim marker as the risk agent, then verify first.
+      const visible = riskAgent.identity.claim?.() ?? `Claimed by **${riskAgent.identity.name}**`;
+      const won = await this.claimFirst(repo, pr.number, 'risk-claim', riskAgent.identity, riskAgent.role, visible);
+      if (!won) {
+        log.info(`assess: lost risk-claim race for PR #${pr.number} — skipping`);
+        continue;
+      }
+
+      try {
+        const childNum = this.closesIssue(pr.body);
+        let issueBody = pr.body;
+        if (childNum && typeof this.hub.issue === 'function') {
+          const linked = await this.hub.issue(repo, childNum);
+          issueBody = linked?.body ?? pr.body;
+        }
+        const obj = childNum && typeof this.hub.issues === 'function' && typeof this.hub.subs === 'function'
+          ? await this.objective(repo, childNum)
+          : 'Planning objective';
+
+        const files = await this.hub.files(repo, pr.number);
+        let diff = '';
+        if (typeof this.hub.diff === 'function') {
+          diff = await this.hub.diff(repo, pr.number);
+        }
+
+        await this.saveTask(riskAgent.identity.name, {
+          type: 'assess_risk',
+          pr: pr.number
+        });
+
+        const mapped = files.map(function fmt(f) {
+          return {
+            filename: f.filename,
+            status: f.status,
+            additions: f.additions ?? 0,
+            deletions: f.deletions ?? 0
+          };
+        });
+
+        const stats = {
+          total: mapped.length,
+          additions: mapped.reduce(function sum(s, f) { return s + f.additions; }, 0),
+          deletions: mapped.reduce(function sum(s, f) { return s + f.deletions; }, 0)
+        };
+
+        const prompt = await this.render({
+          objective: obj,
+          issue: issueBody,
+          number: pr.number,
+          title: pr.title,
+          head: pr.head,
+          base: pr.base,
+          author: agent.identity.name,
+          authorProvider: agent.identity.provider,
+          files: mapped,
+          stats,
+          diff
+        });
+
+        await riskAgent.send(prompt);
+        this.orchestrator.activity(riskAgent.identity.name);
+        this._assessing.set(pr.number, {
+          riskAgent: riskAgent.identity.name,
+          dispatchedAt: Date.now()
+        });
+        dispatched.push({ pr: pr.number, agent: riskAgent.identity.name });
+        log.info(`assess: dispatched ${riskAgent.identity.name} for PR #${pr.number}`);
+      } catch (err) {
+        log.warn(`assess: dispatch failed for PR #${pr.number}: ${err.message}`);
+        try { await this.orchestrator.kill(riskAgent.identity.name); } catch { /* best-effort */ }
+
+        // Fail-safe: unassessed PRs must not pass as low-risk.
+        // The risk-unassessed label routes to HITL in ReviewWorkflow.scan().
+        try {
+          const label = 'loreli:risk-unassessed';
+          await this.hub.ensure(repo, [{ name: label, color: 'e11d48', description: 'Risk: assessment failed — requires human review' }]);
+          await this.hub.label(repo, pr.number, [label]);
+          log.info(`assess: applied fail-safe ${label} to PR #${pr.number}`);
+        } catch { /* best-effort */ }
+
+        this._assessed.add(pr.number);
+      }
+    }
+
+    return dispatched;
+  }
+
+  // ── Verdict ──────────────────────────────────────────
+
+  /**
+   * Check for risk verdicts on PRs being assessed. When a verdict
+   * comment is found, kills the risk agent and marks the PR as assessed.
+   * CRITICAL verdicts escalate to HITL via ReviewWorkflow.
+   *
+   * Labels are applied by the comment tool when the risk agent posts
+   * its verdict with `risk: true`. This handler just reads the result
+   * and routes accordingly.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{pr: number, level: string}>>}
+   */
+  async verdict(repo) {
+    if (!this._assessing.size) return [];
+
+    const results = [];
+    const stallTimeout = this.orchestrator.stallTimeout;
+    const now = Date.now();
+
+    for (const [prNum, tracking] of this._assessing) {
+      const elapsed = now - tracking.dispatchedAt;
+
+      // Stall timeout — risk agent didn't respond. Fail-safe: apply
+      // risk-unassessed label so ReviewWorkflow escalates to HITL
+      // instead of silently passing as low-risk.
+      if (elapsed > stallTimeout) {
+        log.warn(`verdict: risk assessment timed out for PR #${prNum} — applying fail-safe label`);
+        this._assessing.delete(prNum);
+        this._assessed.add(prNum);
+        try { await this.orchestrator.kill(tracking.riskAgent); } catch { /* best-effort */ }
+
+        try {
+          const label = 'loreli:risk-unassessed';
+          await this.hub.ensure(repo, [{ name: label, color: 'e11d48', description: 'Risk: assessment failed — requires human review' }]);
+          await this.hub.label(repo, prNum, [label]);
+          log.info(`verdict: applied fail-safe ${label} to PR #${prNum}`);
+        } catch (err) {
+          log.warn(`verdict: failed to apply fail-safe label to PR #${prNum}: ${err.message}`);
+        }
+
+        results.push({ pr: prNum, level: 'TIMEOUT' });
+        continue;
+      }
+
+      const comments = await this.hub.comments(repo, prNum);
+      const riskComment = comments.find(function hasRisk(c) { return has(c.body, 'risk'); });
+      if (!riskComment) continue;
+
+      const data = parse(riskComment.body, 'risk');
+      const level = data?.level?.toUpperCase?.() ?? 'LOW';
+
+      try { await this.orchestrator.kill(tracking.riskAgent); } catch { /* best-effort */ }
+      this._assessing.delete(prNum);
+      this._assessed.add(prNum);
+
+      log.info(`verdict: PR #${prNum} assessed as ${level}`);
+      results.push({ pr: prNum, level });
+    }
+
+    return results;
+  }
+
+  // ── Reap ─────────────────────────────────────────────
+
+  /**
+   * Clean up stale risk assessments. Risk agents that die without
+   * posting a verdict leave PRs stuck in _assessing forever. This
+   * handler checks for dead agents and marks their PRs as assessed
+   * so ReviewWorkflow can proceed.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async reap(repo) {
+    for (const [prNum, tracking] of this._assessing) {
+      const agent = this.orchestrator.agents.get(tracking.riskAgent);
+      if (!agent) {
+        log.info(`reap: risk agent ${tracking.riskAgent} gone — clearing PR #${prNum}`);
+        this._assessing.delete(prNum);
+        this._assessed.add(prNum);
+
+        // Fail-safe: unassessed PRs must not pass as low-risk.
+        // The risk-unassessed label routes to HITL in ReviewWorkflow.scan().
+        try {
+          const label = 'loreli:risk-unassessed';
+          await this.hub.ensure(repo, [{ name: label, color: 'e11d48', description: 'Risk: assessment failed — requires human review' }]);
+          await this.hub.label(repo, prNum, [label]);
+          log.info(`reap: applied fail-safe ${label} to PR #${prNum}`);
+        } catch (err) {
+          log.warn(`reap: failed to apply fail-safe label to PR #${prNum}: ${err.message}`);
+        }
+      }
+    }
+  }
+}

package/packages/session/README.md

@@ -0,0 +1,165 @@
+# loreli/session
+
+Persistent session storage for detached Loreli agents.
+
+This package manages the `~/.loreli/` state directory where agent sessions and their runtime data are persisted. It exists as a standalone package because session persistence is needed by multiple packages (agent, orchestrator, MCP server) — centralizing it avoids duplication and provides a single, generic solution for `~/.loreli` state management.
+
+## Installation
+
+```bash
+pnpm add loreli
+```
+
+## Directory Layout
+
+Storage organizes state into per-session directories under `~/.loreli/sessions/`:
+
+```
+~/.loreli/
+  sessions/
+    <session-id>/
+      config.json          # Session metadata (id, created, repo, etc.)
+      agents/
+        optimus-0.json     # Agent runtime state
+        megatron-0.json
+      logs/                # Session-scoped log files
+      registry.json        # Identity registry snapshot
+```
+
+## API Reference
+
+### `new Storage(opts?)`
+
+Create a new Storage instance.
+
+- `opts.home` `{string}` — Override the base directory. Falls back to `LORELI_HOME` env var, then `~/.loreli`.
+
+The following example shows the precedence order for resolving the home directory. Options take priority over environment variables, which take priority over the default.
+
+```js
+import { Storage } from 'loreli/session';
+
+// Uses ~/.loreli by default
+const storage = new Storage();
+
+// Explicit override
+const custom = new Storage({ home: '/tmp/test-loreli' });
+
+// Environment variable fallback
+// LORELI_HOME=/opt/loreli node app.js
+const envStorage = new Storage(); // uses /opt/loreli
+```
+
+### `storage.init(id, config?)` → `Promise<string>`
+
+Initialize a session directory. Creates the `agents/` and `logs/` subdirectories and writes `config.json` with the session ID, creation timestamp, and any additional config fields. Returns the session ID.
+
+Safe to call multiple times (idempotent) — existing directories are preserved. The `github.token` field is automatically stripped from the persisted `config.json` to prevent plaintext credential storage on disk.
+
+```js
+const id = await storage.init('session-abc', { repo: 'owner/repo', theme: 'transformers' });
+```
+
+### `storage.save(sessionId, agentName, data)` → `Promise<void>`
+
+Save agent state to disk. Writes atomically (temp file + rename) to prevent corruption from crashes during write.
+
+The following example shows saving an agent's runtime state, which is typically called during state transitions or periodic checkpoints.
+
+```js
+await storage.save('session-abc', 'optimus-0', {
+  identity: { name: 'optimus-0', provider: 'openai' },
+  state: 'working',
+  paneId: '%3',
+  claimedIssue: 42
+});
+```
+
+### `storage.load(sessionId, agentName)` → `Promise<object|null>`
+
+Load agent state from disk. Returns `null` if the agent file does not exist.
+
+```js
+const data = await storage.load('session-abc', 'optimus-0');
+if (data) {
+  console.log(`Agent ${data.identity.name} was in state: ${data.state}`);
+}
+```
+
+### `storage.agents(sessionId)` → `Promise<string[]>`
+
+List all agent names in a session (filenames without `.json` extension). Returns empty array for missing sessions.
+
+```js
+const names = await storage.agents('session-abc');
+// ['optimus-0', 'megatron-0']
+```
+
+### `storage.sessions()` → `Promise<string[]>`
+
+List all session IDs (directory names under `sessions/`). Returns empty array when no sessions exist.
+
+```js
+const ids = await storage.sessions();
+// ['session-abc', 'session-def']
+```
+
+### `storage.sessionDir(id)` → `string`
+
+Get the absolute path to a session's directory. Synchronous.
+
+```js
+storage.sessionDir('session-abc');
+// '/Users/you/.loreli/sessions/session-abc'
+```
+
+### `storage.remove(id)` → `Promise<void>`
+
+Remove a single session and all its contents (agents, logs, config). Does not throw when the session does not exist.
+
+```js
+await storage.remove('session-abc');
+```
+
+### `storage.prune(maxAge)` → `Promise<string[]>`
+
+Remove sessions older than `maxAge` milliseconds. Reads each session's `config.json` for the `created` timestamp. Sessions with missing or unparseable config are treated as stale and pruned. Returns an array of pruned session IDs.
+
+Called automatically at start when `cleanup.autoprune` is `true` (the default), using `cleanup.retention` as the max age.
+
+```js
+const pruned = await storage.prune(12 * 60 * 60 * 1000); // 12 hours
+// ['old-session-1', 'old-session-2']
+```
+
+### `storage.sweep()` → `Promise<string[]>`
+
+Remove known stray files from the loreli home root directory. Files like `mcp-ready` can end up at the root level when the MCP server's working directory happens to be `~/.loreli`. Returns an array of removed file names.
+
+```js
+const swept = await storage.sweep();
+// ['mcp-ready']
+```
+
+### `storage.atomic(filePath, content)` → `Promise<void>`
+
+Write a file atomically using temp file + rename. Used internally by `save()` and `init()`, but exposed for custom state files that need crash-safe writes.
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Session directory missing | `load()` and `agents()` return `null` / `[]` — no throw |
+| No sessions directory | `sessions()` and `prune()` return `[]` — no throw |
+| Missing session for `remove()` | Silent no-op |
+| Missing/invalid `config.json` during prune | Session treated as stale and pruned |
+| `github.token` in config | Automatically stripped during `init()` |
+| File write interrupted | Atomic writes prevent partial files from appearing at the target path |
+
+## Testing
+
+```bash
+node --test packages/session/test/index.test.js
+```
+
+Tests use temporary directories and do not require tmux.