loreli 0.0.0 → 2.0.0

package/packages/mcp/src/index.js

@@ -0,0 +1,600 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { allTools } from './tools/index.js';
+import { Identity, Registry, side, infer, council, pick } from 'loreli/identity';
+import { BackendRegistry } from 'loreli/agent';
+import { Storage } from 'loreli/session';
+import { Orchestrator } from 'loreli/orchestrator';
+import { PlannerWorkflow } from 'loreli/planner';
+import { ActionWorkflow } from 'loreli/action';
+import { RiskWorkflow } from 'loreli/risk';
+import { ReviewWorkflow } from 'loreli/review';
+import { Config } from 'loreli/config';
+import { logger } from 'loreli/log';
+
+const log = logger('mcp');
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Empty JSON Schema used when a tool defines no input parameters.
+ *
+ * @type {object}
+ */
+const EMPTY_SCHEMA = { type: 'object', properties: {} };
+
+/**
+ * Tools that agent MCP sessions are allowed to call.
+ *
+ * Agent subprocesses (spawned CLI backends) share the same MCP server
+ * code but must NOT access orchestration tools like add_agent or
+ * start_work. Exposing those tools leads to confused agents calling
+ * them, which destroys workspaces and starts duplicate reactor loops.
+ *
+ * `start` was previously included so agents would receive a no-op
+ * response ("already configured") instead of an error. However, when
+ * agent hydration fails or env vars are missing, the no-op guard
+ * (`ctx.sessionId && ctx.agentName`) doesn't fire and the call falls
+ * through to the real implementation — which reaps the tmux session,
+ * killing every running agent. Observed in E2E: a Cursor Agent called
+ * `start` on its own repo, destroying the session it was living in.
+ * Safer to block it entirely and return a clean "not available" error.
+ *
+ * @type {Set<string>}
+ */
+const AGENT_TOOLS = new Set(['plan', 'pr', 'comment', 'read', 'environment', 'context', 'refactor']);
+
+/**
+ * Loreli MCP server for agentic team orchestration.
+ *
+ * Uses the low-level MCP SDK Server instead of McpServer because our
+ * tool definitions use plain JSON Schema, not Zod. The low-level API
+ * gives us full control over schema serialization and argument passing.
+ *
+ * Follows the uprising start pattern: constructor creates the
+   * Server, _prepare() registers tools/resources/prompts, start()
+   * connects a transport.
+ *
+ * @example
+ * ```js
+ * const loreli = new Loreli();
+ * await loreli.start();
+ * ```
+ */
+export class Loreli {
+  /**
+   * @param {object} [configuration] - Server configuration.
+   */
+  constructor(configuration = {}) {
+    /** @type {object} Server configuration. */
+    this.config = configuration;
+
+    const instructions = this.loadInstructions();
+
+    /** @type {Server} The low-level MCP server instance. */
+    this.server = new Server(
+      { name: 'loreli', version: '0.0.0' },
+      {
+        capabilities: { tools: {}, prompts: {}, resources: {} },
+        ...(instructions ? { instructions } : {})
+      }
+    );
+
+    /** @type {object} Shared runtime context injected into every tool handler. */
+    this.ctx = null;
+
+    /** @type {Record<string, object>} Registered tool definitions. */
+    this._tools = {};
+
+    /** @type {Promise<void>} Prepared promise. */
+    this.prepared = this._prepare();
+  }
+
+  /**
+   * Load instructions from the instructions.md file.
+   *
+   * @returns {string|null} Instructions text, or null if file not found.
+   */
+  loadInstructions() {
+    try {
+      return readFileSync(join(__dirname, '..', 'instructions.md'), 'utf8');
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Dynamically update a tool's description and schema after runtime
+   * discovery (e.g. available backends, models). Emits a
+   * `tools/list_changed` notification so MCP clients refresh.
+   *
+   * @param {string} name - Tool name to update.
+   * @param {object} updates - Properties to merge (description, schema).
+   */
+  updateTool(name, updates) {
+    const tool = this._tools[name];
+    if (!tool) return;
+
+    if (updates.description) tool.description = updates.description;
+    if (updates.schema) tool.schema = updates.schema;
+
+    // Notify MCP clients that the tool list has changed
+    this.server.sendToolListChanged?.();
+    log.debug(`tool updated: ${name}`);
+  }
+
+  /**
+   * Register tool definitions and set up the tools/list and tools/call
+   * request handlers on the low-level Server.
+   *
+   * Each tool handler receives the shared ctx merged with the SDK extra,
+   * so tools get real Storage, Registry, BackendRegistry instances.
+   *
+   * @param {Record<string, object>} tools - Map of tool name to definition.
+   */
+  tools(tools) {
+    this._tools = { ...this._tools, ...tools };
+    const registered = this._tools;
+    const ctx = this.ctx;
+    const prepared = this.prepared;
+
+    this.server.setRequestHandler(
+      ListToolsRequestSchema,
+      async function list() {
+        // Agent sessions only see agent-scoped tools. Without this
+        // filter, confused agents call add_agent/start_work which
+        // destroys workspaces and starts duplicate reactor loops.
+        const entries = Object.entries(registered)
+          .filter(function scoped([name]) {
+            return !ctx.agentName || AGENT_TOOLS.has(name);
+          });
+
+        return {
+          tools: entries.map(function serialize([name, tool]) {
+            return {
+              name,
+              description: tool.description,
+              inputSchema: tool.schema ?? EMPTY_SCHEMA
+            };
+          })
+        };
+      }
+    );
+
+    this.server.setRequestHandler(
+      CallToolRequestSchema,
+      async function call(request, extra) {
+        const name = request.params.name;
+        const tool = registered[name];
+
+        if (!tool) {
+          return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true
+          };
+        }
+
+        // Block agent sessions from calling orchestration-only tools
+        if (ctx.agentName && !AGENT_TOOLS.has(name)) {
+          log.warn(`agent ${ctx.agentName} blocked from calling host tool: ${name}`);
+          return {
+            content: [{ type: 'text', text: `Tool "${name}" is not available to agents. Use plan, pr, comment, read, refactor, environment, or context.` }],
+            isError: true
+          };
+        }
+
+        // Gate execution on hydration — tools are registered eagerly so
+        // clients can list them, but execution requires hydrated ctx
+        // (hub, config, identity). If hydration is still in progress,
+        // the call blocks here until it completes.
+        await prepared;
+
+        try {
+          // Pass ctx directly so tools can mutate shared state (e.g.
+          // start attaching ctx.hub and ctx.config). SDK extra is
+          // available as ctx._extra for tools that need protocol context.
+          ctx._extra = extra;
+          log.debug(`tool call: ${name}`, { args: request.params.arguments });
+          const result = await tool.exec(request.params.arguments ?? {}, ctx);
+          log.debug(`tool done: ${name}`);
+          return result;
+        } catch (err) {
+          log.error(`tool error: ${name} — ${err.message}`);
+          return {
+            content: [{ type: 'text', text: err.message }],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+
+  /**
+   * Register prompt definitions on the server.
+   *
+   * @param {Record<string, object>} prompts - Map of prompt name to definition.
+   */
+  prompts(prompts) {
+    const registered = prompts;
+
+    this.server.setRequestHandler(
+      ListPromptsRequestSchema,
+      async function list() {
+        return {
+          prompts: Object.entries(registered).map(function serialize([name, prompt]) {
+            return { name, description: prompt.description };
+          })
+        };
+      }
+    );
+
+    this.server.setRequestHandler(
+      GetPromptRequestSchema,
+      async function get(request) {
+        const prompt = registered[request.params.name];
+        if (!prompt) throw new Error(`Unknown prompt: ${request.params.name}`);
+        return prompt.exec(request.params.arguments ?? {});
+      }
+    );
+  }
+
+  /**
+   * Register resource definitions on the server.
+   *
+   * @param {Record<string, object>} resources - Map of resource URI to definition.
+   */
+  resources(resources) {
+    const registered = resources;
+
+    this.server.setRequestHandler(
+      ListResourcesRequestSchema,
+      async function list() {
+        return {
+          resources: Object.entries(registered).map(function serialize([uri, resource]) {
+            return { uri, name: resource.name };
+          })
+        };
+      }
+    );
+
+    this.server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async function read(request) {
+        const resource = registered[request.params.uri];
+        if (!resource) throw new Error(`Unknown resource: ${request.params.uri}`);
+        return resource.exec();
+      }
+    );
+  }
+
+  /**
+   * Async initialization: create real dependencies, build the shared
+   * context, then register all tools.
+   *
+   * The ctx object is a live reference — tools that mutate it (e.g.
+   * start attaches ctx.hub and ctx.config at runtime) affect all
+   * subsequent tool calls.
+   *
+   * @returns {Promise<void>}
+   */
+  async _prepare() {
+    const home = this.config.home ?? process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+    const config = new Config();
+    config.loadLocal('loreli.yml');
+    config.merge(this.config);
+
+    const identityRegistry = new Registry();
+    const backendRegistry = new BackendRegistry();
+    const storage = new Storage({ home });
+
+    const orchestrator = new Orchestrator({ hub: null, identityRegistry, backendRegistry, storage });
+    orchestrator.cfg = config;
+
+    this.ctx = {
+      hub: null,
+      storage,
+      identityRegistry,
+      backendRegistry,
+      orchestrator,
+      planner: new PlannerWorkflow(orchestrator, null),
+      action: new ActionWorkflow(orchestrator, null),
+      risk: new RiskWorkflow(orchestrator, null),
+      review: new ReviewWorkflow(orchestrator, null),
+      clientIdentity: null,
+      clientName: null,
+      clientVersion: null,
+      config,
+      repo: config.get('repo') ?? null,
+      categoryId: null,
+      sessionId: null,
+      server: this
+    };
+
+    // Register tools, prompts, and resources BEFORE hydration so MCP
+    // clients can list capabilities immediately after connecting.
+    // Tool execution is gated on this.prepared (see tools() wrapper),
+    // so calling a tool before hydration finishes will block until ready
+    // rather than returning a -32601 "Method not found" error.
+    const tools = allTools();
+    this.tools(tools);
+
+    // Register empty prompts and resources handlers so MCP clients
+    // don't get -32601 errors when listing them. The server declares
+    // these capabilities in its constructor; without handlers the SDK
+    // returns "Method not found" which clients treat as a server failure.
+    this.prompts({});
+    this.resources({});
+
+    this._hookInitialized();
+
+    // Hydrate agent context from session storage when env vars are present.
+    // These are injected by workspace.prepare() into each agent's .mcp.json
+    // so the agent's MCP server knows its identity without parameters.
+    // Runs AFTER tool registration so clients aren't blocked.
+    await this._hydrate(storage);
+  }
+
+  /**
+   * Hydrate ctx from persisted session storage when agent env vars are set.
+   *
+   * Reads LORELI_SESSION and LORELI_AGENT from process.env, loads the
+   * agent's stored state, and populates ctx fields. This enables agent
+   * tools to resolve repo, identity, role, and task context server-side
+   * without requiring the agent to pass identifiers as parameters.
+   *
+   * @param {Storage} storage - Session storage instance.
+   * @returns {Promise<void>}
+   */
+  async _hydrate(storage) {
+    const sessionId = process.env.LORELI_SESSION;
+    const agentName = process.env.LORELI_AGENT;
+    if (!sessionId || !agentName) return;
+
+    this.ctx.sessionId = sessionId;
+    this.ctx.agentName = agentName;
+
+    const data = await storage.load(sessionId, agentName);
+    if (data) {
+      this.ctx.repo = data.repo ?? process.env.LORELI_REPO ?? this.ctx.repo ?? null;
+      if (data.identity) {
+        // Identity.toJSON() stores `name` as full name and `character`
+        // as the raw character. The constructor expects `name` = character.
+        const raw = data.identity;
+        this.ctx.clientIdentity = new Identity({
+          name: raw.character ?? raw.name,
+          instance: raw.instance ?? 0,
+          faction: raw.faction,
+          provider: raw.provider,
+          model: raw.model,
+          theme: raw.theme
+        });
+      }
+      log.info(`agent context hydrated: ${agentName} (session: ${sessionId}, repo: ${this.ctx.repo})`);
+    } else {
+      // Fallback to env var when storage has no data yet (first startup)
+      this.ctx.repo = process.env.LORELI_REPO ?? this.ctx.repo ?? null;
+      log.warn(`agent session data not found for ${agentName} in ${sessionId}, using env fallback`);
+    }
+
+    // Agent MCP servers need a working hub for plan/pr/comment tools.
+    // The host process sets up the hub via start, but agent
+    // subprocesses never call start — they hydrate from env vars
+    // instead. Create the hub here so agent tools work immediately.
+    await this._hydrateHub();
+  }
+
+  /**
+   * Create a GitHubHub for agent MCP servers.
+   *
+   * Uses GITHUB_TOKEN from the environment (inherited from the parent
+   * process that spawned this agent). If no token is available, the
+   * hub stays null and tools that need it will return clear errors.
+   *
+   * Also loads the loreli.yml config from the target repo when possible
+   * so agent tools have access to labels, merge settings, etc.
+   *
+   * @returns {Promise<void>}
+   */
+  async _hydrateHub() {
+    let token = process.env.GITHUB_TOKEN;
+
+    // Keep a file-based fallback for startup paths where the host did
+    // not provide GITHUB_TOKEN to this process. create() writes
+    // .git/loreli.env inside .git/ (inherently unstageable by git).
+    if (!token) {
+      try {
+        const { readFileSync } = await import('node:fs');
+        const env = readFileSync(join(process.cwd(), '.git', 'loreli.env'), 'utf8');
+        const match = env.match(/^GITHUB_TOKEN=(.+)$/m);
+        if (match) token = match[1].trim();
+      } catch {
+        // File doesn't exist — not a workspace created by create()
+      }
+    }
+
+    if (!token) {
+      log.debug('no GITHUB_TOKEN — agent hub not created');
+      return;
+    }
+
+    try {
+      const { GitHubHub } = await import('loreli/hub');
+      this.ctx.hub = new GitHubHub({ token });
+
+      // Wire hub to workflows so agent tools that delegate work
+      if (this.ctx.planner) this.ctx.planner.hub = this.ctx.hub;
+      if (this.ctx.action) this.ctx.action.hub = this.ctx.hub;
+      if (this.ctx.risk) this.ctx.risk.hub = this.ctx.hub;
+      if (this.ctx.review) this.ctx.review.hub = this.ctx.hub;
+
+      log.info('agent hub created from GITHUB_TOKEN');
+    } catch (err) {
+      log.warn(`agent hub creation failed: ${err.message}`);
+    }
+
+    // Load config from loreli.yml when repo is known
+    if (this.ctx.repo && this.ctx.hub) {
+      try {
+        const config = new Config();
+        config.merge(this.config);
+        await config.load(this.ctx.hub, this.ctx.repo);
+        config.merge(this.config);
+        this.ctx.config = config;
+        this.ctx.orchestrator.cfg = config;
+        log.info(`agent config loaded from ${this.ctx.repo}/loreli.yml`);
+      } catch (err) {
+        log.debug(`agent config load skipped: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Hook into the SDK's `oninitialized` callback to extract client identity
+   * from the standard MCP handshake. The SDK's `Server._oninitialize()`
+   * already handles the initialize request, stores `clientInfo` via
+   * `this._clientVersion`, and negotiates protocol version. We must NOT
+   * override that handler — doing so would break capability negotiation.
+   *
+   * Instead, we use `server.oninitialized` (fired after the SDK completes
+   * its own initialization) and read back the stored values via
+   * `getClientVersion()` and `getClientCapabilities()`.
+   */
+  _hookInitialized() {
+    const ctx = this.ctx;
+    const server = this.server;
+
+    server.oninitialized = function onInitialized() {
+      const client = server.getClientVersion?.() ?? { name: 'unknown', version: 'unknown' };
+      const name = client.name ?? 'unknown';
+      const ver = client.version ?? 'unknown';
+
+      log.info(`MCP client connected: ${name} v${ver}`);
+
+      ctx.clientName = name;
+      ctx.clientVersion = ver;
+
+      const theme = pick(ctx.config?.get?.('theme'));
+
+      ctx.clientIdentity = new Identity({
+        name: 'Loreli',
+        provider: 'loreli',
+        model: 'mcp',
+        theme,
+        faction: council(theme),
+        council: true
+      });
+
+      log.info(`client identity set: ${ctx.clientIdentity.name} (${council(theme)})`);
+
+      // Write a readiness marker so CLI backends (Claude, Cursor) can
+      // detect that MCP tools are discoverable. Without this, the backend
+      // sends the prompt before Claude Code finishes its MCP handshake,
+      // and the agent starts working without access to MCP tools.
+      try {
+        const dir = join(process.cwd(), '.loreli');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'mcp-ready'), String(Date.now()));
+      } catch { /* cwd may not be writable — best-effort */ }
+    };
+  }
+
+  /**
+   * Start the server with a given transport.
+   * Registers SIGINT/SIGTERM handlers that persist session state,
+   * garbage-collect orphaned tmux panes, and exit cleanly.
+   * Tracked agent panes are preserved so agents survive orchestrator restart.
+   *
+   * @param {object} [transport] - MCP transport (defaults to stdio).
+   * @returns {Promise<Server>} The connected server.
+   */
+  async start(transport) {
+    // Do NOT await this.prepared here — tool schemas are registered
+    // eagerly so clients can list them immediately. Tool execution
+    // gates on this.prepared internally (see hydration gate in tools()).
+    // Blocking here would delay the transport connection until hydration
+    // finishes, which defeats the purpose of eager registration.
+
+    if (!transport) {
+      const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+      transport = new StdioServerTransport();
+    }
+
+    // Signal handlers: persist state, gc orphans, preserve tracked panes.
+    // Agent sessions (running inside tmux panes) create a local stub
+    // orchestrator with zero registered agents. Running gc() from that
+    // stub would treat every pane in the session as orphaned and kill
+    // all sibling agents. Only the host process owns the real registry.
+    const self = this;
+
+    /**
+     * @param {'SIGINT'|'SIGTERM'|'transport-close'} reason - What triggered shutdown.
+     */
+    async function gracefulExit(reason) {
+      if (self.ctx?.agentName) {
+        log.info(`agent ${self.ctx.agentName} MCP server exiting (${reason})`);
+        process.exit(0);
+        return;
+      }
+
+      log.info(`host MCP server exiting (${reason})`);
+
+      self.ctx?.orchestrator?.unwatch?.();
+      self.ctx?.orchestrator?.stopMonitor?.();
+
+      if (self.ctx?.sessionId && self.ctx?.storage) {
+        for (const [name, agent] of self.ctx.orchestrator?.agents ?? []) {
+          try {
+            await self.ctx.storage.save(self.ctx.sessionId, name, {
+              identity: agent.identity?.toJSON?.() ?? agent.identity,
+              role: agent.role,
+              state: agent.state,
+              paneId: agent.paneId ?? null,
+              lastActivity: new Date().toISOString()
+            });
+          } catch { /* best-effort persistence */ }
+        }
+      }
+
+      // Clean orphaned tmux panes that aren't tracked by any agent.
+      // Tracked agent panes are preserved for rehydration on next start.
+      try { await self.ctx?.orchestrator?.gc?.(); } catch { /* best-effort */ }
+
+      process.exit(0);
+    }
+
+    process.on('SIGINT', function onSigint() { gracefulExit('SIGINT'); });
+    process.on('SIGTERM', function onSigterm() { gracefulExit('SIGTERM'); });
+
+    log.info('loreli MCP server starting');
+
+    transport.onerror = function onTransportError(err) {
+      log.error(`MCP transport error: ${err?.message ?? err}`);
+    };
+
+    await this.server.connect(transport);
+
+    this.server.onerror = function onServerError(err) {
+      log.error(`MCP server error: ${err?.message ?? err}`);
+    };
+
+    // Transport disconnect (client closed pipe, host exited) bypasses
+    // process signals entirely. Wire the SDK's onclose so cleanup runs
+    // regardless of how the connection ends.
+    this.server.onclose = function onTransportClose() { gracefulExit('transport-close'); };
+
+    log.info('loreli MCP server connected');
+
+    return this.server;
+  }
+}

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

@@ -0,0 +1,44 @@
+import { Identity } from 'loreli/identity';
+
+/**
+ * Resolve agent context from session storage.
+ *
+ * Reads the agent's persisted session data using the sessionId and
+ * agentName from ctx (hydrated at MCP server startup from env vars).
+ * Reconstructs a live Identity instance so hub stamping and label
+ * methods work correctly. Throws when context is not available — this
+ * means the tool was called from a non-agent MCP client.
+ *
+ * @param {object} ctx - Execution context with sessionId, agentName, storage.
+ * @returns {Promise<{repo: string, identity: Identity, role: string, task: object|null, issue: number|null, paneId: string|null}>}
+ * @throws {Error} When agent context is not available.
+ */
+export async function context(ctx) {
+  if (!ctx.sessionId || !ctx.agentName) {
+    throw new Error('Agent context not available. This tool can only be called by spawned agents.');
+  }
+
+  const data = await ctx.storage.load(ctx.sessionId, ctx.agentName);
+  if (!data) {
+    throw new Error(`Session data not found for agent "${ctx.agentName}" in session "${ctx.sessionId}".`);
+  }
+
+  const raw = data.identity;
+  const identity = new Identity({
+    name: raw.character ?? raw.name,
+    instance: raw.instance ?? 0,
+    faction: raw.faction,
+    provider: raw.provider,
+    model: raw.model,
+    theme: raw.theme
+  });
+
+  return {
+    repo: data.repo,
+    identity,
+    role: data.role,
+    task: data.task ?? null,
+    issue: data.claimedIssue ?? data.task?.issue ?? null,
+    paneId: data.paneId ?? null
+  };
+}