loreli 0.0.0 → 1.0.0

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

@@ -0,0 +1,429 @@
+import { Session, models } from 'loreli/agent';
+import { prepare, pathFor, mirror, create as createWorktree } from 'loreli/workspace';
+import { definitions } from 'loreli/hub';
+import { vendor, side, pick } from 'loreli/identity';
+import { logger } from 'loreli/log';
+import { check } from 'loreli/config';
+
+const log = logger('agents');
+
+/**
+ * Persist session state and build the MCP result for a spawned agent.
+ *
+ * @param {object} identity - Agent identity.
+ * @param {string} provider - AI provider name.
+ * @param {string} model - Resolved model identifier.
+ * @param {string} role - Agent role.
+ * @param {string} backendName - Backend used.
+ * @param {object} agent - The spawned agent instance.
+ * @param {object} ctx - Execution context.
+ * @returns {Promise<object>} MCP tool result.
+ */
+async function buildResult(identity, provider, model, role, backendName, agent, ctx) {
+  const session = new Session({
+    identity: identity.toJSON(),
+    role,
+    backend: backendName,
+    paneId: agent.paneId ?? null,
+    repo: ctx.repo
+  });
+
+  if (ctx.sessionId) {
+    await ctx.storage.save(ctx.sessionId, identity.name, session.toJSON());
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: [
+        `Agent spawned: ${identity.name}`,
+        `Faction: ${identity.faction}`,
+        `Provider: ${provider}`,
+        `Model: ${model}`,
+        `Role: ${role}`,
+        `Backend: ${backendName}`,
+        agent.paneId ? `Pane: ${agent.paneId}` : ''
+      ].filter(Boolean).join('\n')
+    }]
+  };
+}
+
+export default {
+  add_agent: {
+    title: 'Add Agent',
+    description: 'Add an agent to the team. Acquires a themed identity, selects a backend, and prepares the agent for spawning.',
+    schema: {
+      type: 'object',
+      properties: {
+        provider: { type: 'string', description: 'AI provider: openai, anthropic, cursor-openai, or cursor-anthropic. Omit to randomly select from available providers.' },
+        role: { type: 'string', description: 'Agent role: planner, action, or reviewer.' },
+        model: { type: 'string', description: 'Model alias (fast/balanced/powerful) or exact model string.' },
+        theme: { type: 'string', description: 'Override theme for this agent (single theme name).' }
+      },
+      required: ['role']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Agent spawn result.
+     */
+    async exec(args, ctx) {
+      // Validate inputs before any side effects
+      check.role(args.role);
+      if (args.theme) check.theme(args.theme);
+
+      // Resolve provider: use explicit value, or pick randomly from
+      // discovered backends. Randomization ensures different models
+      // get exposure to all roles across runs — no single provider
+      // monopolizes planning or coding.
+      let provider = args.provider;
+      if (provider) {
+        check.provider(provider);
+      } else {
+        const available = ctx.backendRegistry.providers();
+        if (!available.length) throw new Error('No providers available. Ensure at least one CLI backend (claude, codex, cursor-agent) is on PATH.');
+        provider = available[Math.floor(Math.random() * available.length)];
+        log.info(`add_agent: no provider specified — randomly selected "${provider}" from [${available.join(', ')}]`);
+      }
+
+      const { role } = args;
+      const modelAlias = args.model ?? ctx.config?.get?.('model') ?? 'balanced';
+
+      // Theme coherence: explicit override > peer inheritance > random pick from config.
+      // When multiple themes are configured, the first agent picks randomly
+      // and all subsequent agents inherit from the existing peer so
+      // antagonist pairs always share the same theme universe.
+      let theme;
+      if (args.theme) {
+        theme = args.theme;
+      } else {
+        const existing = [...(ctx.orchestrator?.agents?.values?.() ?? [])];
+        const peer = existing.find(function hasIdentity(a) { return a.identity?.theme; });
+        theme = peer?.identity?.theme ?? pick(ctx.config?.get?.('theme') ?? 'transformers');
+      }
+
+      const repo = ctx.repo;
+
+      // Resolve backend first — model resolution needs the backend name
+      const backendName = ctx.backendRegistry.resolve(provider, args.backend);
+
+      // Resolve model alias to concrete identifier via backend-specific config.
+      // Virtual providers (cursor-openai, cursor-anthropic) normalize to the
+      // canonical vendor for config lookup (backends.cursor.models.balanced.openai).
+      const model = models.resolve(modelAlias, backendName, vendor(provider), ctx.config);
+      log.info(`add_agent: provider=${provider} role=${role} model=${model} backend=${backendName} theme=${theme}`);
+
+      // Seed taken names before first acquire — one-time cost, zero
+      // ongoing overhead because reactor ticks keep the set current.
+      await ctx.orchestrator.seed?.();
+
+      // Acquire themed identity — tracked for rollback
+      const identity = ctx.identityRegistry.acquire(theme, provider, model, ctx.orchestrator.takenNames);
+
+      /** @type {Array<{step: string, undo: function}>} Steps for rollback. */
+      const steps = [{
+        step: 'identity',
+        undo() { ctx.identityRegistry.release(identity); }
+      }];
+
+      try {
+        // Ensure model-specific labels exist (model labels are not known at start)
+        if (ctx.hub && repo && ctx.config?.get?.('labels.track') !== false) {
+          await ctx.hub.ensure(repo, definitions(identity.labels(role)));
+          // Labels are idempotent — no meaningful undo needed
+        }
+
+        log.debug(`resolved backend: ${backendName} for identity ${identity.name}`);
+
+        const denied = ctx.config?.get?.('agents.disallowedTools') ?? [];
+        const wsContext = ctx.sessionId ? {
+          session: ctx.sessionId,
+          agent: identity.name,
+          repo,
+          home: ctx.storage?.home,
+          token: process.env.GITHUB_TOKEN,
+          denied
+        } : undefined;
+
+        // When we have full orchestration context, create a git worktree
+        // from a shared bare mirror. The agent starts with the repo
+        // already checked out — no cloning needed. Falls back to plain
+        // config scaffolding when repo is unknown.
+        let cwd;
+        if (wsContext?.repo && wsContext?.home) {
+          const url = `https://github.com/${repo}.git`;
+          const bare = await mirror(url, { home: wsContext.home, token: wsContext.token });
+          cwd = await createWorktree(bare, 'HEAD', identity.name, undefined, wsContext);
+          log.info(`worktree ready at ${cwd} from mirror of ${repo}`);
+        } else {
+          cwd = repo ? pathFor(identity.name) : process.cwd();
+          await prepare(cwd, wsContext);
+        }
+
+        // Build prompt from the workflow's template for this role
+        const workflow = { planner: ctx.planner, action: ctx.action, reviewer: ctx.review }[role];
+        const prompt = await workflow.render({
+          name: identity.name,
+          repo: repo ?? 'unknown',
+          faction: identity.faction,
+          provider,
+          model,
+          labels: identity.labels(role)
+        });
+
+        // Create the agent instance via backend registry.
+        const opts = { identity, role, cwd, model: modelAlias, prompt, config: ctx.config };
+        if (wsContext) opts.context = wsContext;
+        const agent = ctx.backendRegistry.create(backendName, opts);
+
+        // Persist session data BEFORE spawn so the agent's MCP server
+        // subprocess can hydrate from storage on startup. The agent
+        // process starts during spawn() and immediately reads session
+        // data via _hydrate() — a race condition if we save afterward.
+        if (ctx.sessionId) {
+          const session = new Session({
+            identity: identity.toJSON(),
+            role,
+            backend: backendName,
+            paneId: null, // not yet known — updated after spawn
+            repo: ctx.repo
+          });
+          await ctx.storage.save(ctx.sessionId, identity.name, session.toJSON());
+        }
+
+        // Spawn via orchestrator (has its own internal rollback)
+        await ctx.orchestrator.spawn(agent);
+
+        // Cross-side validation: warn when yin/yang adversarial pairing is incomplete.
+        // Uses side-based matching so cursor-openai (yang) is satisfied by any yin agent.
+        const mySide = side(provider);
+        if (role === 'reviewer') {
+          const hasAction = [...ctx.orchestrator.agents.values()]
+            .some(function has(a) { return a.role === 'action' && side(a.identity.provider) !== mySide; });
+          if (!hasAction) {
+            log.warn(`reviewer ${identity.name} (${provider}) has no opposing-side action agent — adversarial review unavailable`);
+          }
+        }
+
+        if (role === 'action') {
+          const hasReviewer = [...ctx.orchestrator.agents.values()]
+            .some(function has(a) { return a.role === 'reviewer' && side(a.identity.provider) !== mySide; });
+          if (!hasReviewer) {
+            log.warn(`action ${identity.name} (${provider}) has no opposing-side reviewer — adversarial review unavailable`);
+          }
+        }
+
+        return buildResult(identity, provider, model, role, backendName, agent, ctx);
+      } catch (err) {
+        // Rollback all completed steps in reverse
+        for (let i = steps.length - 1; i >= 0; i--) {
+          try {
+            await steps[i].undo();
+            log.debug(`add_agent rollback: undid "${steps[i].step}"`);
+          } catch (rollbackErr) {
+            log.warn(`add_agent rollback "${steps[i].step}" failed: ${rollbackErr.message}`);
+          }
+        }
+        throw err;
+      }
+
+    }
+  },
+
+  agents: {
+    title: 'Agents',
+    description: [
+      'Query the state of your agent team. Use this to list all registered agents',
+      'or check whether a specific agent is alive and responsive.',
+      '',
+      'Actions:',
+      '- "list": Show all agents with their name, faction, provider, role, and state.',
+      '- "check": Query liveness of a specific agent (provide name) or all agents.',
+      '  Returns health status including alive flag, state, and pane ID.'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          description: 'Operation: "list" or "check".',
+          enum: ['list', 'check']
+        },
+        name: { type: 'string', description: 'Agent identity name (required for single-agent check, omit for all).' },
+        lines: { type: 'number', description: 'Number of terminal output lines to capture per agent in "list" mode. Defaults to 40.' }
+      },
+      required: ['action']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Agent list or health report.
+     */
+    async exec(args, ctx) {
+      const { action } = args;
+
+      if (action !== 'list' && action !== 'check') {
+        return {
+          content: [{ type: 'text', text: `Unknown action: "${action}". Valid: list, check` }],
+          isError: true
+        };
+      }
+
+      if (args.name) check.name(args.name);
+
+      if (ctx.orchestrator?.reconcile) await ctx.orchestrator.reconcile();
+
+      if (action === 'list') {
+        const agents = [...ctx.orchestrator.agents.entries()];
+
+        if (!agents.length) {
+          return { content: [{ type: 'text', text: 'No agents registered.' }] };
+        }
+
+        const captureLines = args.lines ?? 40;
+        const parts = [];
+        parts.push('Name | Theme | Faction | Provider | Role | State');
+
+        for (const [name, agent] of agents) {
+          parts.push([
+            name,
+            agent.identity?.theme ?? 'unknown',
+            agent.identity?.faction ?? 'unknown',
+            agent.identity?.provider ?? 'unknown',
+            agent.role ?? 'unknown',
+            agent.state ?? 'unknown'
+          ].join(' | '));
+
+          try {
+            if (typeof agent.capture === 'function') {
+              const output = (await agent.capture(captureLines))?.trim();
+              if (output) {
+                parts.push(`  Terminal:\n${output.split('\n').map(function indent(l) { return `    ${l}`; }).join('\n')}`);
+              } else {
+                parts.push('  Terminal: (no output)');
+              }
+            }
+          } catch { parts.push('  Terminal: (unavailable)'); }
+        }
+
+        return {
+          content: [{ type: 'text', text: parts.join('\n') }]
+        };
+      }
+
+      // action === 'check'
+      const orch = ctx.orchestrator;
+
+      if (args.name) {
+        const agent = orch.agents.get(args.name);
+        if (!agent) {
+          return { content: [{ type: 'text', text: `Agent "${args.name}" not found.` }], isError: true };
+        }
+
+        const alive = await agent.alive();
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              name: args.name,
+              alive,
+              state: agent.state,
+              role: agent.role,
+              paneId: agent.paneId ?? null
+            }, null, 2)
+          }]
+        };
+      }
+
+      // Check all agents
+      const results = [];
+      for (const [name, agent] of orch.agents) {
+        const alive = await agent.alive();
+        results.push({ name, alive, state: agent.state, role: agent.role });
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: results.length
+            ? JSON.stringify(results, null, 2)
+            : 'No agents to check.'
+        }]
+      };
+    }
+  },
+
+  stop: {
+    title: 'Stop Agent',
+    description: [
+      'Stop an agent by name. Use "shutdown" for graceful termination (agent finishes',
+      'current work, then cleans up) or "kill" for immediate forced termination of a',
+      'stuck or misbehaving agent. Graceful shutdown escalates to kill after timeout.',
+      '',
+      'Actions:',
+      '- "shutdown": Graceful stop. Agent completes current task, responds, then exits.',
+      '- "kill": Immediate forced termination. Kills tmux pane, cleans up session. Last resort.'
+    ].join('\n'),
+    schema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          description: 'Operation: "shutdown" or "kill".',
+          enum: ['shutdown', 'kill']
+        },
+        name: { type: 'string', description: 'Agent identity name to stop.' }
+      },
+      required: ['action', 'name']
+    },
+
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} Stop result.
+     */
+    async exec(args, ctx) {
+      const { action, name } = args;
+
+      if (action !== 'shutdown' && action !== 'kill') {
+        return {
+          content: [{ type: 'text', text: `Unknown action: "${action}". Valid: shutdown, kill` }],
+          isError: true
+        };
+      }
+
+      check.name(name);
+
+      if (ctx.orchestrator?.reconcile) await ctx.orchestrator.reconcile();
+
+      try {
+        if (action === 'shutdown') {
+          await ctx.orchestrator.shutdown(name);
+        } else {
+          await ctx.orchestrator.kill(name);
+        }
+      } catch (err) {
+        return { content: [{ type: 'text', text: err.message }], isError: true };
+      }
+
+      // Update storage to reflect dormant state
+      if (ctx.sessionId) {
+        try {
+          const data = await ctx.storage.load(ctx.sessionId, name);
+          if (data) {
+            data.state = 'dormant';
+            data.lastActivity = new Date().toISOString();
+            await ctx.storage.save(ctx.sessionId, name, data);
+          }
+        } catch { /* storage update is best-effort */ }
+      }
+
+      const verb = action === 'shutdown' ? 'shut down' : 'force killed';
+      return {
+        content: [{ type: 'text', text: `Agent "${name}" ${verb} successfully.` }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,199 @@
+/**
+ * Context resolution MCP tool.
+ *
+ * Exposes the context resolution engine as an MCP tool, auto-exposed
+ * as CLI commands by @mcp-layer/cli. Agents invoke via terminal:
+ * `loreli tools context --action blame --file src/index.js --line 42`
+ *
+ * Deliberately excluded from AGENT_TOOLS — agents access via CLI
+ * to avoid bloating the conversation context window.
+ *
+ * @module loreli/mcp/tools/context
+ */
+
+import { hub as createHub } from 'loreli/hub';
+import { blame, history, search, resolve } from 'loreli/context';
+import * as workspace from 'loreli/workspace';
+import { logger } from 'loreli/log';
+
+const log = logger('context');
+
+export default {
+  context: {
+    title: 'Context',
+    description: 'Resolve code context — trace lines to PRs, search decisions, view patterns. Best used via CLI: loreli tools context --action blame --file <path> --line <N>',
+    schema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['blame', 'history', 'search', 'patterns'],
+          description: 'The context action to perform.'
+        },
+        file: { type: 'string', description: 'Relative file path (blame/history).' },
+        line: { type: 'number', description: 'Line number (blame).' },
+        query: { type: 'string', description: 'Search keywords (search).' },
+        limit: { type: 'number', description: 'Max results (history, default 10).' },
+        category: { type: 'string', description: 'Filter by category (patterns).' },
+        threshold: { type: 'number', description: 'Min occurrences (patterns).' }
+      },
+      required: ['action']
+    },
+    /**
+     * @param {object} args - Tool arguments.
+     * @param {object} ctx - Execution context.
+     * @returns {Promise<object>} MCP tool response.
+     */
+    async exec(args, ctx) {
+      if (!ctx.hub) {
+        try {
+          ctx.hub = createHub({ config: ctx.config });
+        } catch (err) {
+          return {
+            content: [{ type: 'text', text: `Hub initialization failed: ${err.message}. Set GITHUB_TOKEN.` }],
+            isError: true
+          };
+        }
+      }
+
+      const repo = ctx.repo;
+      if (!repo) {
+        return {
+          content: [{ type: 'text', text: 'No repository configured. Run start first or set LORELI_REPO.' }],
+          isError: true
+        };
+      }
+
+      try {
+        switch (args.action) {
+          case 'blame': {
+            if (!args.file || !args.line) {
+              return {
+                content: [{ type: 'text', text: 'blame requires --file and --line' }],
+                isError: true
+              };
+            }
+            const cwd = process.cwd();
+            const result = await blame(workspace, ctx.hub, repo, cwd, args.file, args.line);
+            log.info(`blame: ${args.file}:${args.line} -> ${result.sha?.slice(0, 7)}`);
+
+            const lines = [
+              `## Blame: ${args.file}:${args.line}`,
+              '',
+              `**Commit**: ${result.sha}`,
+              `**Author**: ${result.author}`,
+              `**Date**: ${result.date}`,
+              `**Summary**: ${result.summary}`
+            ];
+
+            if (result.prs.length) {
+              lines.push('', '### Associated PRs');
+              for (const pr of result.prs) {
+                lines.push(`- #${pr.number}: ${pr.title} (${pr.state})`);
+              }
+
+              // Resolve the first PR's full chain
+              const full = await resolve(ctx.hub, repo, result.prs[0].number);
+              if (full.issues.length) {
+                lines.push('', '### Linked Issues');
+                for (const issue of full.issues) {
+                  lines.push(`- #${issue.number}: ${issue.title}`);
+                }
+              }
+              if (full.discussions.length) {
+                lines.push('', '### Linked Discussions');
+                for (const disc of full.discussions) {
+                  lines.push(`- #${disc.number}: ${disc.title}`);
+                }
+              }
+            }
+
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+          }
+
+          case 'history': {
+            if (!args.file) {
+              return {
+                content: [{ type: 'text', text: 'history requires --file' }],
+                isError: true
+              };
+            }
+            const cwd = process.cwd();
+            const limit = args.limit ?? 10;
+            const commits = await history(workspace, ctx.hub, repo, cwd, args.file, { limit });
+            log.info(`history: ${args.file} -> ${commits.length} commits`);
+
+            const lines = [`## History: ${args.file}`, ''];
+            for (const c of commits) {
+              const prRefs = c.prs.length
+                ? ` (${c.prs.map(function ref(p) { return `#${p.number}`; }).join(', ')})`
+                : '';
+              lines.push(`- \`${c.sha.slice(0, 7)}\` ${c.date} — ${c.message}${prRefs}`);
+            }
+
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+          }
+
+          case 'search': {
+            if (!args.query) {
+              return {
+                content: [{ type: 'text', text: 'search requires --query' }],
+                isError: true
+              };
+            }
+            const results = await search(ctx.hub, repo, args.query);
+            log.info(`search: "${args.query}" -> ${results.length} results`);
+
+            const lines = [`## Search: "${args.query}"`, ''];
+            for (const r of results) {
+              lines.push(`- [${r.type}] #${r.number}: ${r.title}`);
+            }
+            if (!results.length) lines.push('No results found.');
+
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+          }
+
+          case 'patterns': {
+            // Patterns delegates to packages/knowledge (Phase 6)
+            // For now, return a placeholder until knowledge package exists
+            try {
+              const { patterns } = await import('loreli/knowledge');
+              const opts = {};
+              if (args.category) opts.category = args.category;
+              if (args.threshold) opts.threshold = args.threshold;
+              const found = await patterns(ctx.hub, repo, opts);
+
+              const lines = ['## Review Patterns', ''];
+              for (const p of found) {
+                lines.push(`### ${p.summary} (${p.category}, ${p.count} occurrences)`);
+                for (const ref of p.refs) {
+                  lines.push(`  - PR #${ref.pr}: "${ref.excerpt}"`);
+                }
+                lines.push('');
+              }
+              if (!found.length) lines.push('No patterns detected above threshold.');
+
+              return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch {
+              return {
+                content: [{ type: 'text', text: 'Knowledge package not yet available. Patterns will be enabled after packages/knowledge is implemented.' }]
+              };
+            }
+          }
+
+          default:
+            return {
+              content: [{ type: 'text', text: `Unknown action: ${args.action}. Use blame, history, search, or patterns.` }],
+              isError: true
+            };
+        }
+      } catch (err) {
+        log.error(`context/${args.action} failed: ${err.message}`);
+        return {
+          content: [{ type: 'text', text: `context/${args.action} failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  }
+};