loreli 0.0.0 → 2.0.0

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

@@ -0,0 +1,162 @@
+import { logger } from 'loreli/log';
+import { check } from 'loreli/config';
+import { has, parse } from 'loreli/marker';
+import { select } from './repo.js';
+
+const log = logger('hitl');
+
+/**
+ * Human In The Loop (HITL) tools.
+ *
+ * `hitl` hands off a PR to human reviewers after agent approval.
+ * `watch` checks for new human feedback using timestamp filtering.
+ */
+export default {
+  hitl: {
+    title: 'HITL',
+    description: 'Hand off a PR to human reviewers. Requests review, assigns users, posts a summary comment tagging reviewers. Only meaningful when merge.hitl is true.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository (owner/name).' },
+        pr: { type: 'number', description: 'Pull request number.' }
+      },
+      required: ['pr']
+    },
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} HITL result with reviewer list.
+     */
+    async exec(args, ctx) {
+      check.positive(args.pr, 'PR number');
+      const repo = select(args.repo, ctx);
+      const pr = args.pr;
+      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
+        };
+      }
+      const reviewers = ctx.config?.get?.('reviewers') ?? [];
+
+      if (!reviewers.length) {
+        return {
+          content: [{
+            type: 'text',
+            text: `No reviewers configured — merge.hitl is false. PR #${pr} can be merged directly.`
+          }]
+        };
+      }
+
+      log.info(`hitl PR #${pr} for human review: ${reviewers.join(', ')}`);
+
+      // Delegate to review workflow which handles request, assign, comment, and agent cleanup
+      const result = await ctx.review.hitl(repo, pr);
+
+      // Persist HITL state for watch polling
+      if (ctx.sessionId && ctx.storage) {
+        try {
+          const agents = ctx.storage.agents ? await ctx.storage.agents(ctx.sessionId) : [];
+          for (const name of agents) {
+            const data = await ctx.storage.load(ctx.sessionId, name);
+            if (data) {
+              data.state = 'awaiting_hitl';
+              data.reviewers = result.reviewers;
+              data.hitlAt = result.hitlAt;
+              await ctx.storage.save(ctx.sessionId, name, data);
+            }
+          }
+        } catch { /* best-effort persistence */ }
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            `PR #${pr} handed to Human In The Loop`,
+            `Reviewers: ${result.reviewers.join(', ')}`,
+            `HITL at: ${result.hitlAt}`,
+            'All active agents have been shut down.'
+          ].join('\n')
+        }]
+      };
+    }
+  },
+
+  watch: {
+    title: 'Watch',
+    description: 'Check an HITL PR for new human feedback. Returns comments posted after the HITL timestamp, filtering out known agent comments.',
+    schema: {
+      type: 'object',
+      properties: {
+        repo: { type: 'string', description: 'Target repository (owner/name).' },
+        pr: { type: 'number', description: 'Pull request number.' },
+        since: { type: 'string', description: 'ISO timestamp to filter comments after (hitlAt).' }
+      },
+      required: ['pr', 'since']
+    },
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Watch result with status and optional feedback.
+     */
+    async exec(args, ctx) {
+      check.positive(args.pr, 'PR number');
+      const repo = select(args.repo, ctx);
+      const { pr, since } = args;
+      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
+        };
+      }
+
+      // Inline: pending() was a 3-line hub method — timestamp filter on comments()
+      const allComments = await ctx.hub.comments(repo, pr);
+      const comments = allComments.filter(function afterHitl(c) { return c.created > since; });
+
+      // Filter out comments whose agent marker names an identity in the
+      // registry's active list. Both agent and human comments may carry
+      // the agent marker when posted via hub.as(identity, role).comment();
+      // we distinguish by whether the marker's name is a known agent.
+      const activeNames = new Set(
+        (ctx.identityRegistry?.active?.() ?? []).map(function name(i) { return i.name; })
+      );
+      const human = comments.filter(function notAgent(c) {
+        if (!has(c.body, 'agent')) return true;
+        const data = parse(c.body, 'agent');
+        return !data?.name || !activeNames.has(data.name);
+      });
+
+      if (!human.length) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({ status: 'waiting', pr, checked: new Date().toISOString() })
+          }]
+        };
+      }
+
+      // Human feedback found — trigger rework via action workflow
+      if (ctx.action) {
+        try {
+          await ctx.action.rework(repo, pr, human);
+        } catch { /* rework is best-effort; we still return the feedback */ }
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            status: 'feedback',
+            pr,
+            comments: human.map(function format(c) {
+              return { author: c.author, body: c.body, created: c.created };
+            })
+          })
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,18 @@
+import start from './start.js';
+import agents from './agents.js';
+import work from './work.js';
+import status from './status.js';
+import hitl from './hitl.js';
+import github from './github.js';
+import context from './context.js';
+import refactor from './refactor.js';
+
+/**
+ * All tool definitions aggregated from individual modules.
+ *
+ * @returns {Record<string, object>} Map of tool name to tool definition.
+ */
+export function allTools() {
+  return { ...start, ...agents, ...work, ...status, ...hitl, ...github, ...context, ...refactor };
+}
+

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

@@ -0,0 +1,227 @@
+import { context } from './agent-context.js';
+import { logger } from 'loreli/log';
+
+const log = logger('refactor-tool');
+
+/**
+ * Valid observation categories.
+ *
+ * @type {Set<string>}
+ */
+const KINDS = new Set(['bug', 'refactor', 'smell', 'debt']);
+
+/**
+ * Valid impact levels.
+ *
+ * @type {Set<string>}
+ */
+const IMPACTS = new Set(['low', 'medium', 'high']);
+
+/**
+ * Validates file path entries against the allowed formats:
+ * plain path or path with GitHub-style line range hint.
+ *
+ * @type {RegExp}
+ */
+const FILE_PATTERN = /^[^\s#]+(?:#R\d+-R\d+)?$/;
+
+/**
+ * Check whether a normalized title appears in an existing item's title.
+ *
+ * @param {string} needle - Normalized title to search for.
+ * @param {string} haystack - Item title to compare against.
+ * @returns {boolean} True when considered a match.
+ */
+function titleMatch(needle, haystack) {
+  return haystack.toLowerCase().includes(needle);
+}
+
+/**
+ * Build a structured discussion body from the refactor observation.
+ *
+ * @param {object} agent - Resolved agent context.
+ * @param {object} args - Tool arguments.
+ * @returns {string} Formatted Markdown body.
+ */
+function body(agent, args) {
+  const lines = [
+    `## ${args.kind}: ${args.title}`,
+    '',
+    args.description,
+    '',
+    `**Kind**: ${args.kind}`,
+    `**Impact**: ${args.impact ?? 'medium'}`,
+    `**Reported by**: ${agent.identity.name} (${agent.role})`,
+  ];
+
+  if (agent.issue) lines.push(`**Source issue**: #${agent.issue}`);
+
+  if (args.files?.length) {
+    lines.push('', '### Affected files', '');
+    for (const f of args.files) lines.push(`- \`${f}\``);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Refactor tool — opportunistic improvement intake for action agents.
+ *
+ * Creates a labeled discussion in the Loreli category after dedup
+ * checks. Existing planner review/revise/promote handles the rest.
+ */
+export default {
+  refactor: {
+    title: 'Refactor',
+    description: [
+      'Flag a bug, code smell, or tech debt you encounter during implementation.',
+      'Call immediately on discovery — do not wait until your PR is complete.',
+      'Provide kind, title, and description with stable identifiers (function names, class names, patterns).',
+      'Optionally include affected files (with optional #R<start>-R<end> range hints) and impact level.',
+      'The tool checks for duplicates and creates a Loreli discussion for planning. Action agents only.'
+    ].join(' '),
+    schema: {
+      type: 'object',
+      properties: {
+        kind: {
+          type: 'string',
+          description: 'Category of observation.',
+          enum: ['bug', 'refactor', 'smell', 'debt']
+        },
+        title: {
+          type: 'string',
+          description: 'Concise improvement title.'
+        },
+        description: {
+          type: 'string',
+          description: 'Problem statement with stable identifiers (function names, class names, error messages). Not line numbers.'
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Affected file paths. Optionally append #R<start>-R<end> for line range hints, e.g. "src/hub.js#R40-R50".'
+        },
+        impact: {
+          type: 'string',
+          description: 'Estimated impact: low, medium, or high. Defaults to medium.',
+          enum: ['low', 'medium', 'high']
+        }
+      },
+      required: ['kind', 'title', 'description']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool result.
+     */
+    async exec(args, ctx) {
+      if (!KINDS.has(args.kind)) {
+        return {
+          content: [{ type: 'text', text: `Invalid kind: "${args.kind}". Valid: ${[...KINDS].join(', ')}` }],
+          isError: true
+        };
+      }
+
+      if (!args.title?.trim()) {
+        return { content: [{ type: 'text', text: 'title is required.' }], isError: true };
+      }
+
+      if (!args.description?.trim()) {
+        return { content: [{ type: 'text', text: 'description is required.' }], isError: true };
+      }
+
+      if (args.impact && !IMPACTS.has(args.impact)) {
+        return {
+          content: [{ type: 'text', text: `Invalid impact: "${args.impact}". Valid: ${[...IMPACTS].join(', ')}` }],
+          isError: true
+        };
+      }
+
+      if (args.files?.length) {
+        for (const f of args.files) {
+          if (!FILE_PATTERN.test(f)) {
+            return {
+              content: [{ type: 'text', text: `Invalid file entry: "${f}". Use "<path>" or "<path>#R<start>-R<end>".` }],
+              isError: true
+            };
+          }
+        }
+      }
+
+      if (!ctx.hub) {
+        return { content: [{ type: 'text', text: 'Hub not initialized. Run start first.' }], isError: true };
+      }
+
+      let agent;
+      try {
+        agent = await context(ctx);
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      if (agent.role !== 'action') {
+        return {
+          content: [{ type: 'text', text: 'refactor is restricted to action agents.' }],
+          isError: true
+        };
+      }
+
+      // ── Dedup gate ────────────────────────────────────────
+      const normalized = args.title.trim().toLowerCase();
+      const cat = await ctx.hub.category(agent.repo, 'Loreli');
+
+      // 1. Search existing issues and PRs
+      try {
+        const existing = await ctx.hub.searchIssues(agent.repo, args.title);
+        const match = existing.find(function dup(i) { return titleMatch(normalized, i.title); });
+        if (match) {
+          log.info(`refactor: dedup hit via issue search — #${match.number}: ${match.title}`);
+          return {
+            content: [{ type: 'text', text: `Already tracked at #${match.number} (${match.url}). Skipping.` }]
+          };
+        }
+      } catch (err) {
+        log.debug(`refactor: issue search failed, proceeding: ${err.message}`);
+      }
+
+      // 2. Scan open Loreli discussions with loreli:refactor label
+      try {
+        const discussions = await ctx.hub.discussions(agent.repo, cat.id);
+        const match = discussions.find(function dup(d) {
+          return !d.closed &&
+            d.labels.includes('loreli:refactor') &&
+            titleMatch(normalized, d.title);
+        });
+        if (match) {
+          log.info(`refactor: dedup hit via discussion scan — #${match.number}: ${match.title}`);
+          return {
+            content: [{ type: 'text', text: `Already tracked at discussion #${match.number} (${match.url}). Skipping.` }]
+          };
+        }
+      } catch (err) {
+        log.debug(`refactor: discussion scan failed, proceeding: ${err.message}`);
+      }
+
+      // ── Create discussion ─────────────────────────────────
+      const scoped = ctx.hub.as(agent.identity, agent.role);
+      const labels = [...(agent.identity.labels?.(agent.role) ?? ['loreli']), 'loreli:refactor'];
+
+      const disc = await scoped.discuss(agent.repo, {
+        title: `[${args.kind}] ${args.title}`,
+        body: body(agent, args),
+        categoryId: cat.id,
+        repositoryId: cat.repositoryId,
+        labels
+      });
+
+      log.info(`refactor: created discussion #${disc.number} — [${args.kind}] ${args.title}`);
+      return {
+        content: [{
+          type: 'text',
+          text: `Refactor flagged as discussion #${disc.number}: [${args.kind}] ${args.title}\nURL: ${disc.url}`
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,44 @@
+import { check } from 'loreli/config';
+
+/**
+ * Resolve repository context from the shared execution context.
+ *
+ * Priority order:
+ * 1. Runtime `ctx.repo` (set by start/session hydration)
+ * 2. Config fallback (`repo` key from loreli.yml or env)
+ *
+ * @param {object} ctx - Tool execution context.
+ * @returns {string|null} Repository slug (`owner/name`) or null.
+ */
+export function repoOf(ctx) {
+  if (ctx?.repo) return ctx.repo;
+
+  const repo = ctx?.config?.get?.('repo') ?? null;
+  if (!repo) return null;
+
+  // Validate env/config fallback immediately so tool errors are explicit.
+  check.repo(repo);
+  if (ctx && typeof ctx === 'object') ctx.repo = repo;
+  return repo;
+}
+
+/**
+ * Resolve a repository from tool arguments with shared fallback behavior.
+ *
+ * Priority order:
+ * 1. Explicit `--repo` argument
+ * 2. `repoOf(ctx)` fallback
+ *
+ * @param {string|undefined} arg - Explicit repo argument from tool input.
+ * @param {object} ctx - Tool execution context.
+ * @returns {string|null} Repository slug (`owner/name`) or null.
+ */
+export function select(arg, ctx) {
+  if (arg) {
+    check.repo(arg);
+    if (ctx && typeof ctx === 'object') ctx.repo = arg;
+    return arg;
+  }
+
+  return repoOf(ctx);
+}