loreli 0.0.0 → 1.0.0

package/packages/agent/src/session.js

@@ -0,0 +1,162 @@
+/**
+ * Valid session states.
+ *
+ * @type {Set<string>}
+ */
+export const STATES = new Set([
+  'spawned', 'working', 'standby', 'reviewing', 'awaiting_hitl', 'dormant'
+]);
+
+/**
+ * Explicit state transition map.
+ *
+ * Each key is a current state, and the value is a Set of states
+ * it can transition to. Transitions not in this map are rejected.
+ *
+ * Uses an explicit graph instead of linear ordering because agent
+ * states have branching paths (e.g. working -> awaiting_hitl vs
+ * working -> dormant).
+ *
+ * @type {Record<string, Set<string>>}
+ */
+export const TRANSITIONS = {
+  spawned: new Set(['working', 'standby', 'dormant']),
+  working: new Set(['standby', 'reviewing', 'awaiting_hitl', 'dormant']),
+  standby: new Set(['working', 'reviewing', 'awaiting_hitl', 'dormant']),
+  reviewing: new Set(['working', 'standby', 'awaiting_hitl', 'dormant']),
+  awaiting_hitl: new Set(['working', 'standby', 'dormant']),
+  dormant: new Set([])
+};
+
+/**
+ * Tracks an active agent's runtime state.
+ *
+ * Sessions are persisted to disk so agents survive orchestrator shutdown.
+ * State transitions are validated against the TRANSITIONS map to catch
+ * bugs where agents are reactivated without proper re-initialization.
+ */
+export class Session {
+  /**
+   * @param {object} opts
+   * @param {object} opts.identity - Agent identity object.
+   * @param {string} opts.role - Agent role ('planner' | 'action' | 'reviewer').
+   * @param {string} opts.backend - Backend name ('claude', 'codex', etc.).
+   * @param {string} [opts.paneId] - Tmux pane ID.
+   * @param {number} [opts.pid] - Process ID.
+   * @param {string} [opts.repo] - Target repository (owner/name).
+   */
+  constructor({ identity, role, backend, paneId, pid, repo }) {
+    /** @type {object} Agent identity. */
+    this.identity = identity;
+
+    /** @type {string} Agent role. */
+    this.role = role;
+
+    /** @type {string} Backend name. */
+    this.backend = backend;
+
+    /** @type {string|null} Tmux pane ID. */
+    this.paneId = paneId ?? null;
+
+    /** @type {number|null} Process ID. */
+    this.pid = pid ?? null;
+
+    /** @type {string|null} Target repository. */
+    this.repo = repo ?? null;
+
+    /** @type {string} Current state. */
+    this.state = 'spawned';
+
+    /** @type {string} When the session started. */
+    this.startedAt = new Date().toISOString();
+
+    /** @type {string} Last activity timestamp. */
+    this.lastActivity = this.startedAt;
+
+    /** @type {number|null} Claimed issue number. */
+    this.claimedIssue = null;
+
+    /** @type {object|null} Dynamic task context from latest dispatch. */
+    this.task = null;
+
+    /** @type {string[]} Human reviewers assigned during HITL. */
+    this.reviewers = [];
+
+    /** @type {Array<{name: string, provider: string, timestamp: string}>} Agent approval records. */
+    this.agentApprovals = [];
+
+    /** @type {string|null} ISO timestamp when HITL was activated. */
+    this.hitlAt = null;
+
+    /**
+     * Token usage accumulator for the current task.
+     * Reset when a new task is assigned via dispatch.
+     *
+     * @type {{ input: number, output: number, model: string|null }}
+     */
+    this.usage = { input: 0, output: 0, model: null };
+  }
+
+  /**
+   * Transition to a new state with validation.
+   *
+   * Validates the transition against the TRANSITIONS map. Invalid
+   * transitions throw an error to catch bugs where agents are moved
+   * to impossible states (e.g. dormant -> working without re-spawn).
+   *
+   * @param {string} next - New state (spawned | working | standby | reviewing | awaiting_hitl | dormant).
+   * @throws {Error} If the transition is invalid.
+   */
+  transition(next) {
+    if (!STATES.has(next)) {
+      throw new Error(`Invalid state: "${next}". Valid: ${[...STATES].join(', ')}`);
+    }
+
+    const allowed = TRANSITIONS[this.state];
+    if (!allowed?.has(next)) {
+      throw new Error(
+        `Invalid transition: "${this.state}" -> "${next}". ` +
+        `Allowed from "${this.state}": ${allowed ? [...allowed].join(', ') || 'none (terminal)' : 'unknown'}`
+      );
+    }
+
+    this.state = next;
+    this.lastActivity = new Date().toISOString();
+  }
+
+  /**
+   * Check whether a transition to the given state is valid.
+   *
+   * @param {string} next - Target state to check.
+   * @returns {boolean} True if the transition is allowed.
+   */
+  canTransition(next) {
+    return TRANSITIONS[this.state]?.has(next) ?? false;
+  }
+
+  /**
+   * Serialize the session to a plain object for JSON storage.
+   *
+   * @returns {object} Plain object representation.
+   */
+  toJSON() {
+    return {
+      identity: this.identity,
+      role: this.role,
+      backend: this.backend,
+      paneId: this.paneId,
+      pid: this.pid,
+      repo: this.repo,
+      state: this.state,
+      startedAt: this.startedAt,
+      lastActivity: this.lastActivity,
+      claimedIssue: this.claimedIssue,
+      task: this.task,
+      reviewers: this.reviewers,
+      agentApprovals: this.agentApprovals,
+      hitlAt: this.hitlAt,
+      usage: this.usage
+    };
+  }
+
+}

package/packages/agent/src/trace.js

@@ -0,0 +1,186 @@
+/**
+ * Agent trace formatting and token parsing utilities.
+ *
+ * Produces marker-wrapped `<details>` blocks for embedding agent
+ * reasoning, terminal output, and token usage in PR bodies and
+ * review comments. Uses the loreli marker system for programmatic
+ * detection and stripping.
+ *
+ * @module loreli/agent/trace
+ */
+
+import { mark } from 'loreli/marker';
+
+/**
+ * Registry of regex patterns for extracting token usage from CLI output.
+ * Each entry has a `name`, a `pattern` regex, and an `extract` function
+ * that receives the match and returns `{ input, output }`.
+ *
+ * New backends or updated CLI versions can be supported by adding
+ * entries here without changing the `tokens()` function itself.
+ *
+ * @type {Array<{name: string, pattern: RegExp, extract: function}>}
+ */
+const TOKEN_PATTERNS = [
+  {
+    name: 'codex',
+    pattern: /tokens?\s+used\s*\n?\s*(\d[\d,]*)/i,
+    extract(m) {
+      const total = parseInt(m[1].replaceAll(',', ''), 10);
+      return { input: 0, output: total };
+    }
+  },
+  {
+    name: 'codex-split',
+    pattern: /input[:\s]+(\d[\d,]*)\s*(?:tokens?)?\s*[,|/]\s*output[:\s]+(\d[\d,]*)/i,
+    extract(m) {
+      return {
+        input: parseInt(m[1].replaceAll(',', ''), 10),
+        output: parseInt(m[2].replaceAll(',', ''), 10)
+      };
+    }
+  },
+  {
+    name: 'claude',
+    pattern: /total\s+tokens?[:\s]+input\s*=\s*(\d[\d,]*)\s+output\s*=\s*(\d[\d,]*)/i,
+    extract(m) {
+      return {
+        input: parseInt(m[1].replaceAll(',', ''), 10),
+        output: parseInt(m[2].replaceAll(',', ''), 10)
+      };
+    }
+  }
+];
+
+/**
+ * Parse token usage from CLI terminal output.
+ *
+ * Iterates the pattern registry and returns the first match.
+ * Returns `null` when no recognized pattern is found — this is
+ * expected for backends like cursor-agent that do not print
+ * token info.
+ *
+ * @param {string} text - Cleaned terminal output.
+ * @returns {{ input: number, output: number } | null}
+ */
+export function tokens(text) {
+  if (!text) return null;
+
+  for (const entry of TOKEN_PATTERNS) {
+    const m = text.match(entry.pattern);
+    if (m) return entry.extract(m);
+  }
+
+  return null;
+}
+
+/**
+ * Escape captured output so it cannot interfere with the loreli
+ * marker system or break markdown rendering.
+ *
+ * Strips:
+ * - HTML comments that look like loreli markers (`<!-- loreli:... -->`)
+ * - Null bytes and other ASCII control characters (except newline/tab)
+ *
+ * @param {string} text - Raw captured output.
+ * @returns {string} Sanitized text safe for embedding in code fences.
+ */
+export function escape(text) {
+  if (!text) return '';
+  return text
+    .replace(/<!-- loreli:[^>]*-->/g, '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+}
+
+/**
+ * Determine the minimum number of backticks needed for a code fence
+ * that will not be broken by backtick sequences in the content.
+ *
+ * @param {string} text - Content to be fenced.
+ * @returns {number} Fence length (at least 3).
+ */
+function fenceLength(text) {
+  let max = 0;
+  const re = /`+/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m[0].length > max) max = m[0].length;
+  }
+  return Math.max(3, max + 1);
+}
+
+/**
+ * Format a complete agent trace block.
+ *
+ * Produces a marker-delimited `<details>` section suitable for
+ * embedding in PR bodies or review comments. The block is wrapped
+ * with `loreli:trace` / `loreli:trace-end` markers so downstream
+ * consumers can strip it via `excise(body, 'trace')`.
+ *
+ * Sections are omitted when their data is absent:
+ * - `reasoning` — agent-provided summary of approach
+ * - `output` — captured terminal output (in a code fence)
+ * - `usage` — token counts from `tokens()`
+ *
+ * @param {string} name - Agent identity name (e.g. 'bumblebee-0').
+ * @param {object} data - Trace data.
+ * @param {string} [data.reasoning] - Agent-provided reasoning summary.
+ * @param {string} [data.output] - Captured terminal output.
+ * @param {{ input: number, output: number } | null} [data.usage] - Token usage.
+ * @param {string} [data.model] - Model identifier for the usage table.
+ * @param {number} [data.duration] - Duration in milliseconds.
+ * @returns {string} Complete trace block with markers.
+ */
+export function format(name, data = {}) {
+  const { reasoning, output: raw, usage, model, duration } = data;
+  const sections = [];
+
+  if (reasoning) {
+    sections.push('### Reasoning\n');
+    sections.push(reasoning);
+  }
+
+  if (raw) {
+    const cleaned = escape(raw);
+    const len = fenceLength(cleaned);
+    const fence = '`'.repeat(len);
+    sections.push('### Output\n');
+    sections.push(`${fence}\n${cleaned}\n${fence}`);
+  }
+
+  if (usage || model || duration != null) {
+    const rows = [];
+    if (usage?.input != null) rows.push(`| Input tokens | ${usage.input.toLocaleString()} |`);
+    if (usage?.output != null) rows.push(`| Output tokens | ${usage.output.toLocaleString()} |`);
+    if (model) rows.push(`| Model | ${model} |`);
+    if (duration != null) {
+      const secs = Math.round(duration / 1000);
+      const mins = Math.floor(secs / 60);
+      const rem = secs % 60;
+      const display = mins > 0 ? `${mins}m ${rem}s` : `${secs}s`;
+      rows.push(`| Duration | ${display} |`);
+    }
+    if (rows.length) {
+      sections.push('### Usage\n');
+      sections.push(`| Metric | Value |\n|--------|-------|\n${rows.join('\n')}`);
+    }
+  }
+
+  if (!sections.length) return '';
+
+  const body = sections.join('\n\n');
+  const startMarker = mark('trace', { agent: name });
+  const endMarker = `<!-- loreli:trace-end -->`;
+
+  return [
+    startMarker,
+    `<details>`,
+    `<summary>Agent Trace (${name})</summary>`,
+    '',
+    body,
+    '',
+    `</details>`,
+    endMarker
+  ].join('\n');
+}