loreli 0.0.0 → 2.0.0

package/packages/workflow/src/index.js

@@ -0,0 +1,660 @@
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Mustache from 'mustache';
+import { mark, has, parse } from 'loreli/marker';
+import { Tmux } from 'loreli/tmux';
+import { classify } from 'loreli/classify';
+import { logger } from 'loreli/log';
+
+export { responder } from './proof-of-life.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the shared autonomous-mode preamble prepended to
+ * every agent prompt. Lives in the workflow package because render()
+ * is the single funnel all prompts flow through.
+ *
+ * @type {string}
+ */
+const PREAMBLE = join(__dirname, '..', 'prompts', 'preamble.md');
+const log = logger('workflow');
+
+/** @type {string|null} Cached preamble text — loaded once, reused. */
+let _preamble = null;
+
+/**
+ * Maximum backend-diagnose checks after prompt dispatch.
+ *
+ * @type {number}
+ */
+const DISPATCH_NUDGE_CHECKS = 48;
+
+/**
+ * Delay between post-dispatch diagnose checks.
+ *
+ * @type {number}
+ */
+const DISPATCH_NUDGE_INTERVAL = 5000;
+
+/**
+ * Load the shared preamble, caching after the first read.
+ *
+ * @returns {Promise<string>}
+ */
+async function preamble() {
+  if (_preamble === null) _preamble = await readFile(PREAMBLE, 'utf8');
+  return _preamble;
+}
+
+/**
+ * Wait for the specified duration.
+ *
+ * @param {number} ms - Milliseconds to sleep.
+ * @returns {Promise<void>}
+ */
+async function sleep(ms) {
+  await new Promise(function onTimer(resolve) {
+    const handle = setTimeout(resolve, ms);
+    handle?.unref?.();
+  });
+}
+
+/**
+ * Normalize remedy values into tmux key sequences.
+ *
+ * Classifier output may provide remedy as a single space-delimited string,
+ * while backend fallback diagnosers usually return string arrays.
+ *
+ * @param {string|string[]|null|undefined} remedy - Remedy value from diagnosis.
+ * @returns {string[]} Keys to send through tmux.
+ */
+function keys(remedy) {
+  if (Array.isArray(remedy)) {
+    const list = remedy.filter(Boolean);
+    if (list.length > 0) return list;
+    return ['Enter'];
+  }
+
+  if (typeof remedy === 'string') {
+    const list = remedy.split(/\s+/).filter(Boolean);
+    if (list.length > 0) return list;
+    return ['Enter'];
+  }
+
+  return ['Enter'];
+}
+
+/**
+ * Return whether a diagnosis category requires immediate remediation.
+ *
+ * @param {string|undefined} category - Diagnosis category.
+ * @returns {boolean} True when remediation should be applied immediately.
+ */
+function actionable(category) {
+  return category === 'option_dialog'
+    || category === 'waiting_for_input'
+    || category === 'fatal'
+    || category === 'dead';
+}
+
+/**
+ * Run pane classification through loreli/classify.
+ *
+ * This is best-effort: classification errors should not block dispatch
+ * nudging because backend regex diagnosis can still recover option dialogs.
+ *
+ * @param {object} orchestrator - Orchestrator instance containing config/backends.
+ * @param {object} agent - Agent metadata.
+ * @param {string} pane - Captured pane output.
+ * @returns {Promise<object|null>} Classifier diagnosis, or null when unavailable/failed.
+ */
+async function diagnose(orchestrator, agent, pane) {
+  const backends = orchestrator?.backendRegistry;
+  if (!backends?.oneshot) return null;
+
+  try {
+    const result = await classify('pane-state', pane, {
+      backends,
+      config: orchestrator?.cfg,
+      vars: { model: agent.model, backend: agent.backend, role: agent.role }
+    });
+
+    if (result?.category === 'option_dialog') {
+      log.info(
+        `dispatch nudge classify: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+        + `${result.category} — ${result.reasoning}`
+      );
+    }
+
+    return result;
+  } catch (err) {
+    log.debug(`dispatch nudge classify failed for ${agent.identity?.name ?? 'unknown'}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Swallow background nudge errors.
+ *
+ * @returns {void}
+ */
+function ignoreNudgeError() {}
+
+/**
+ * Abstract base class for role-specific workflow packages.
+ *
+ * Subclasses must define `static role` (the agent role name) and
+ * `static template` (absolute path to the Mustache prompt file).
+ * They implement `reactor()` and `events()` to register handlers
+ * with the orchestrator's tick loop and EventEmitter respectively.
+ *
+ * This class absorbs the template rendering responsibility from the
+ * deleted `Role` class, adds agent filtering by role, and provides
+ * the `renderFrom()` method for cross-role rendering (e.g. the
+ * review package rendering the action prompt for `forward()`).
+ */
+export class Workflow {
+  /**
+   * @param {object} orchestrator - Orchestrator instance with agents Map and identityRegistry.
+   * @param {object} hub - GitHub hub instance for API calls.
+   */
+  constructor(orchestrator, hub) {
+    if (!new.target.role) {
+      throw new Error('Workflow subclass must define static role');
+    }
+
+    /** @type {object} The orchestrator for agent coordination. */
+    this.orchestrator = orchestrator;
+
+    /** @type {object} GitHub hub for API calls. */
+    this.hub = hub;
+
+    /** @type {Map<string, string|null>} Per-role cached custom prompt content. */
+    this._custom = new Map();
+  }
+
+  /**
+   * Return reactor handler map for the orchestrator's tick loop.
+   * Subclasses override to register their specific handlers.
+   *
+   * @returns {Record<string, Function>} Handler name to async function.
+   */
+  reactor() {
+    return {};
+  }
+
+  /**
+   * Return event listener map for orchestrator EventEmitter events.
+   * Subclasses override to register their specific listeners.
+   *
+   * @returns {Record<string, Function>} Event name to handler function.
+   */
+  events() {
+    return {};
+  }
+
+  /**
+   * Filter orchestrator agents to those matching this workflow's role.
+   *
+   * @returns {object[]} Agents whose role matches this workflow's static role.
+   */
+  agents() {
+    const role = this.constructor.role;
+    return [...this.orchestrator.agents.values()]
+      .filter(function byRole(a) { return a.role === role; });
+  }
+
+  /**
+   * Report the current demand signal for this workflow's role.
+   *
+   * Returns a structured object so the orchestrator can make informed
+   * scaling decisions — spawn decisions use `deficit`, cross-role
+   * prioritization uses `workload`, and logging uses all three.
+   *
+   * Subclasses override to compute real values from their hydrated
+   * state. The base implementation reports zero demand.
+   *
+   * @param {string} _repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(_repo) {
+    return { workload: 0, supply: 0, deficit: 0 };
+  }
+
+  /**
+   * Find the opposing-provider match for yin/yang review pairing.
+   * Delegates to the orchestrator's identity registry.
+   *
+   * @param {object} identity - The identity to find an opposite for.
+   * @param {object[]} candidates - Objects with an identity property.
+   * @returns {object|null} The matching candidate, or null.
+   */
+  pair(identity, candidates) {
+    return this.orchestrator.identityRegistry.pair(identity, candidates);
+  }
+
+  /**
+   * Create and spawn a new agent via the orchestrator's factory.
+   *
+   * @param {string} provider - AI provider.
+   * @param {string} role - Agent role.
+   * @param {object} [opts] - Additional factory options.
+   * @returns {Promise<object>} The spawned agent.
+   */
+  async enlist(provider, role, opts) {
+    return this.orchestrator.enlist(provider, role, opts);
+  }
+
+  /**
+   * Load the project-specific custom prompt for this workflow's role.
+   *
+   * Resolves `workflows.{role}.prompt` from config, reads the file
+   * once from the target repo via the hub, and caches the result on
+   * this instance. Returns an empty string when the config key is
+   * unset, the hub is unavailable, or the file cannot be read —
+   * prompt rendering never fails due to a missing custom prompt.
+   *
+   * @param {object} [opts] - Options.
+   * @param {string} [opts.role] - Role to resolve prompt for.
+   * @returns {Promise<string>} Custom prompt text, or empty string.
+   */
+  async custom(opts = {}) {
+    const role = opts.role ?? this.constructor.role;
+    if (this._custom.has(role)) return this._custom.get(role) ?? '';
+
+    const path = this.orchestrator.cfg?.get?.(`workflows.${role}.prompt`);
+    if (!path || !this.hub?.read || !this.orchestrator.repo) {
+      this._custom.set(role, null);
+      return '';
+    }
+
+    try {
+      const result = await this.hub.read(this.orchestrator.repo, path);
+      this._custom.set(role, result?.content ?? null);
+    } catch {
+      this._custom.set(role, null);
+    }
+
+    return this._custom.get(role) ?? '';
+  }
+
+  /**
+   * Load and render this workflow's prompt template.
+   *
+   * Automatically injects the workflow's `role` into the template
+   * variables so subclasses don't need to pass it explicitly.
+   * Prepends the shared autonomous-mode preamble and any project-
+   * specific custom prompt from `workflows.{role}.prompt` so every
+   * agent prompt carries the headless operation directive and project rules.
+   *
+   * @param {object} vars - Mustache template variables.
+   * @returns {Promise<string>} Rendered prompt text.
+   */
+  async render(vars) {
+    const [pre, ext, template] = await Promise.all([
+      preamble(),
+      this.custom({ role: this.constructor.role }),
+      readFile(this.constructor.template, 'utf8')
+    ]);
+    const body = Mustache.render(template, { ...vars, role: this.constructor.role });
+    const prefix = ext ? `${pre}\n${ext}\n` : `${pre}\n`;
+    return `${prefix}${body}`;
+  }
+
+  /**
+   * Load and render an arbitrary Mustache template by path.
+   *
+   * Used for cross-role rendering where one workflow needs another
+   * role's prompt (e.g. review rendering the action prompt for forward).
+   * Prepends the shared autonomous-mode preamble and any project-
+   * specific custom prompt from `workflows.{role}.prompt`.
+   *
+   * @param {string} path - Absolute path to a .md template file.
+   * @param {object} vars - Mustache template variables.
+   * @param {object} [opts] - Options.
+   * @param {string} [opts.role] - Role to resolve prompt for.
+   * @returns {Promise<string>} Rendered prompt text.
+   */
+  async renderFrom(path, vars, opts = {}) {
+    const role = opts.role ?? this.constructor.role;
+    const [pre, ext, template] = await Promise.all([
+      preamble(),
+      this.custom({ role }),
+      readFile(path, 'utf8')
+    ]);
+    const body = Mustache.render(template, vars);
+    const prefix = ext ? `${pre}\n${ext}\n` : `${pre}\n`;
+    return `${prefix}${body}`;
+  }
+
+  /**
+   * Write task context to the agent's session in storage.
+   *
+   * Called by workflows before dispatching an agent so the agent's
+   * MCP server can read the task context (discussion ID, PR number,
+   * etc.) without the agent needing to pass it as a parameter.
+   *
+   * No-op when sessionId or storage is not available (e.g. tests
+   * without persistent storage).
+   *
+   * @param {string} agentName - Agent identity name.
+   * @param {object} task - Task context object (e.g. { type: 'review_pr', pr: 42 }).
+   * @returns {Promise<void>}
+   */
+  async saveTask(agentName, task) {
+    const { storage, sessionId } = this.orchestrator;
+    if (!sessionId || !storage) return;
+
+    const data = await storage.load(sessionId, agentName);
+    if (!data) return;
+
+    data.task = task;
+    await storage.save(sessionId, agentName, data);
+  }
+
+  /**
+   * Render this workflow's template and send to an agent.
+   *
+   * @param {object} agent - Target agent with a send() method.
+   * @param {object} vars - Mustache template variables.
+   * @returns {Promise<void>}
+   */
+  async dispatch(agent, vars) {
+    const prompt = await this.render(vars);
+    await agent.send(prompt);
+    this.nudge(agent).catch(ignoreNudgeError);
+  }
+
+  /**
+   * Nudge known CLI option dialogs after prompt dispatch.
+   *
+   * Some backends surface interactive confirmation dialogs seconds
+   * after a prompt is submitted (for example MCP tool approvals).
+   * This helper polls pane output and applies backend-provided
+   * dialog remedies so workflows remain unattended.
+   *
+   * @param {object} agent - Target agent with backend/pane metadata.
+   * @returns {Promise<void>}
+   */
+  async nudge(agent) {
+    if (!agent?.backend || !agent?.paneId || !agent?.capture) return;
+
+    const registry = this.orchestrator?.backendRegistry;
+    if (!registry?.diagnose) return;
+
+    for (let i = 0; i < DISPATCH_NUDGE_CHECKS; i++) {
+      if (agent.state === 'dormant') return;
+
+      let pane;
+      try {
+        pane = await agent.capture(this.orchestrator?.cfg?.get?.('classify.maxLines') ?? 100);
+      } catch {
+        return;
+      }
+
+      const llm = await diagnose(this.orchestrator, agent, pane);
+      const fallback = registry.diagnose(agent.backend, pane);
+
+      let result = llm;
+      if (!result?.category && fallback?.category) {
+        result = fallback;
+        log.info(
+          `dispatch nudge fallback diagnose: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+          + `${fallback.category} — ${fallback.reasoning}`
+        );
+      } else if (actionable(fallback?.category) && !actionable(result?.category)) {
+        result = fallback;
+        log.info(
+          `dispatch nudge fallback override: ${agent.identity?.name ?? 'unknown'} ${agent.backend} `
+          + `${fallback.category} over ${llm?.category ?? 'unknown'} — ${fallback.reasoning}`
+        );
+      }
+
+      if (result?.category === 'option_dialog') {
+        const seq = keys(result.remedy);
+        log.info(`dispatch nudge: ${agent.identity?.name ?? 'unknown'} ${agent.backend} option_dialog — sending ${seq.join('+')}`);
+        try {
+          const tmux = new Tmux();
+          await tmux.keys(agent.paneId, ...seq);
+        } catch {
+          log.debug(`dispatch nudge: keys failed for ${agent.identity?.name ?? 'unknown'}`);
+          return;
+        }
+        this.orchestrator.activity?.(agent.identity?.name);
+
+        if (i < DISPATCH_NUDGE_CHECKS - 1)
+          await sleep(DISPATCH_NUDGE_INTERVAL);
+        continue;
+      }
+
+      if (i < DISPATCH_NUDGE_CHECKS - 1)
+        await sleep(DISPATCH_NUDGE_INTERVAL);
+    }
+  }
+
+  // ── Proof of Life ───────────────────────────────────
+
+  /**
+   * Post a themed proof-of-life request on an issue/PR.
+   *
+   * Uses the orchestrator's client identity for scoping and the
+   * council-level themed message from the identity's theme. Falls
+   * back to an unscoped invisible marker when no client identity
+   * is available (e.g. in tests with bare stubs).
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Name of the agent being checked.
+   * @returns {Promise<void>}
+   */
+  async requestProofOfLife(repo, number, agent) {
+    const orch = this.orchestrator.sessionId;
+    const payload = { agent, ts: String(Date.now()) };
+    if (orch) payload.orch = orch;
+    const marker = mark('proof-of-life', payload);
+    const identity = this.orchestrator.clientIdentity;
+    if (!identity) {
+      await this.hub.comment(repo, number, marker);
+      return;
+    }
+    const visible = identity.proofOfLife(agent);
+    const body = `${visible}\n\n${marker}`;
+    const scoped = this.hub.as(identity, 'orchestrator');
+    await scoped.comment(repo, number, body);
+  }
+
+  /**
+   * Post a themed alive response with an embedded machine-readable marker.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {object} identity - Agent identity for hub scoping.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {{alive: boolean, status: string, details: string, outputLength?: number}} verdict - Health check result.
+   * @returns {Promise<void>}
+   */
+  async respondProofOfLife(repo, number, identity, role, verdict) {
+    const marker = mark('alive', {
+      agent: identity.name,
+      ts: String(Date.now()),
+      status: verdict.status
+    });
+    const visible = `**${identity.name}** is **${verdict.status}** — ${verdict.details}`;
+    const body = `${visible}\n\n${marker}`;
+    const scoped = this.hub.as(identity, role);
+    await scoped.comment(repo, number, body);
+  }
+
+  /**
+   * Find a pending proof-of-life request for a specific agent.
+   *
+   * When `orch` is provided, only matches requests posted by that
+   * orchestrator session. When omitted, matches any request — used
+   * by the responder which answers regardless of who asked.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent name to search for.
+   * @param {string} [orch] - Orchestrator session ID filter.
+   * @returns {Promise<{agent: string, ts: string, orch?: string}|null>} Parsed request data, or null.
+   */
+  async findProofOfLifeRequest(repo, number, agent, orch) {
+    const comments = await this.hub.comments(repo, number);
+    for (const c of comments) {
+      if (!has(c.body, 'proof-of-life')) continue;
+      const data = parse(c.body, 'proof-of-life');
+      if (data?.agent !== agent) continue;
+      if (orch && data.orch !== orch) continue;
+      return data;
+    }
+    return null;
+  }
+
+  /**
+   * Find an alive response for a specific agent posted after a given timestamp.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent name to search for.
+   * @param {number} after - Only match responses with ts greater than this epoch ms.
+   * @returns {Promise<{agent: string, ts: string, status: string}|null>} Parsed response, or null.
+   */
+  async findAliveResponse(repo, number, agent, after) {
+    const comments = await this.hub.comments(repo, number);
+    for (const c of comments) {
+      if (!has(c.body, 'alive')) continue;
+      const data = parse(c.body, 'alive');
+      if (data?.agent !== agent) continue;
+      if (Number(data.ts) > after) return data;
+    }
+    return null;
+  }
+
+  /**
+   * Check whether an issue/PR has any GitHub comment within the timeout window.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {number} timeout - Maximum age in ms for activity to be considered recent.
+   * @returns {Promise<boolean>}
+   */
+  async hasRecentActivity(repo, number, timeout) {
+    const comments = await this.hub.comments(repo, number);
+    const cutoff = Date.now() - timeout;
+    return comments.some(function recent(c) {
+      return new Date(c.created_at).getTime() > cutoff;
+    });
+  }
+
+  /**
+   * Evaluate an agent through the proof-of-life protocol.
+   *
+   * Unified gate for ALL eviction decisions — foreign agents, local
+   * idle agents, and any future workflow that needs to verify liveness
+   * before releasing a claim. Posts a PoL request if none exists,
+   * checks for alive responses, and considers the response status
+   * (healthy vs unhealthy) when making the verdict.
+   *
+   * Status-aware: an alive response with `status: 'unhealthy'` means
+   * the agent's own orchestrator confirmed it is stalled, so the gate
+   * returns `'release'` instead of `'active'`.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent identity name to check.
+   * @returns {Promise<string>} 'active'|'requested'|'pending'|'release'.
+   */
+  async check(repo, number, agent) {
+    const timeout = this.orchestrator.cfg?.get?.('proofOfLife.timeout') ?? 300000;
+    const orch = this.orchestrator.sessionId;
+
+    const ours = await this.findProofOfLifeRequest(repo, number, agent, orch);
+    if (ours) {
+      const response = await this.findAliveResponse(repo, number, agent, Number(ours.ts));
+      if (response) return response.status === 'unhealthy' ? 'release' : 'active';
+      if (Date.now() - Number(ours.ts) > timeout) return 'release';
+      return 'pending';
+    }
+
+    const any = await this.findProofOfLifeRequest(repo, number, agent);
+    if (any) {
+      const response = await this.findAliveResponse(repo, number, agent, Number(any.ts));
+      if (response) return response.status === 'unhealthy' ? 'release' : 'active';
+      if (Date.now() - Number(any.ts) > timeout) {
+        await this.requestProofOfLife(repo, number, agent);
+        return 'requested';
+      }
+      return 'pending';
+    }
+
+    const recent = await this.hasRecentActivity(repo, number, timeout);
+    if (recent) return 'active';
+
+    await this.requestProofOfLife(repo, number, agent);
+    return 'requested';
+  }
+
+  // ── Optimistic Claim ─────────────────────────────────
+
+  /**
+   * Optimistic claim on an issue or PR: post a marker comment, then
+   * re-read comments to verify this agent was first.
+   *
+   * This eliminates the TOCTOU race in the check-then-claim pattern.
+   * By claiming first and verifying after, two participants racing on
+   * the same item will both post, but only the first poster wins.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} type - Marker type (e.g. 'claim', 'review-claim', 'risk-claim').
+   * @param {object} identity - Agent identity.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {string} [visible] - Optional visible text appended after the marker.
+   * @returns {Promise<boolean>} True if this agent was the first claimant.
+   */
+  async claimFirst(repo, number, type, identity, role, visible) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark(type, { agent: identity.name });
+    const body = visible ? `${marker}\n${visible}` : marker;
+    await scoped.comment(repo, number, body);
+
+    // Re-read all comments and find the first with this marker type.
+    // The first poster wins — all others back off.
+    const comments = await this.hub.comments(repo, number);
+    const first = comments.find(function isClaim(c) { return has(c.body, type); });
+    return parse(first?.body, type)?.agent === identity.name;
+  }
+
+  /**
+   * Optimistic claim on a discussion: post a marker comment, then
+   * re-read discussion comments to verify this agent was first.
+   *
+   * Identical pattern to {@link claimFirst} but uses the discussion
+   * comment API (node IDs, GraphQL) instead of issue/PR comments.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Discussion number (for reading).
+   * @param {string} discId - Discussion node ID (for posting).
+   * @param {string} type - Marker type (e.g. 'review-claim').
+   * @param {object} identity - Agent identity.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {string} [visible] - Optional visible text appended after the marker.
+   * @returns {Promise<boolean>} True if this agent was the first claimant.
+   */
+  async claimFirstDiscussion(repo, number, discId, type, identity, role, visible) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark(type, { agent: identity.name });
+    const body = visible ? `${marker}\n${visible}` : marker;
+    await scoped.discussionComment(discId, body);
+
+    // Use the LAST claim comment to determine the winner. Discussions
+    // that go through revise/re-review cycles accumulate old claim
+    // comments from previous cycles — checking the first would always
+    // match the stale claim and block re-dispatch.
+    const full = await this.hub.discussion(repo, number);
+    const last = full.comments?.findLast(function isClaim(c) { return has(c.body, type); });
+    return parse(last?.body, type)?.agent === identity.name;
+  }
+}