loreli 0.0.0 → 1.0.0

package/packages/log/README.md

@@ -0,0 +1,93 @@
+# loreli/log
+
+Structured, session-aware logging for all Loreli packages. Writes to both console and `~/.loreli/` log files with per-agent log separation.
+
+## API Reference
+
+### `logger(pkg)` → Logger
+
+Create or retrieve a logger scoped to a package name. Every entry is tagged with `{ package: pkg }`.
+
+```js
+import { logger } from 'loreli/log';
+
+const log = logger('agent');
+log.info('claimed issue', { issue: 42 });
+log.warn('rate limit approaching', { remaining: 50 });
+log.error('spawn failed', { error: 'binary not found' });
+log.debug('tmux capture', { paneId: '%3' });
+```
+
+### `logger(pkg).agent(name)` → Logger
+
+Create a per-agent sub-logger. Writes to a dedicated `<name>.log` file and tags every entry with `{ agent: name }`.
+
+```js
+const log = logger('agent');
+const agentLog = log.agent('optimus-0');
+agentLog.info('PR created', { pr: 17 });
+// -> writes to ~/.loreli/sessions/<id>/logs/optimus-0.log
+```
+
+### `bind(opts)`
+
+Bind the logging subsystem to a session. After binding, all loggers gain a file transport.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `session` | `string` | Session ID — logs write to `~/.loreli/sessions/<session>/logs/` |
+| `home` | `string` | Override the base directory (default: `~/.loreli/`) |
+
+```js
+import { bind } from 'loreli/log';
+bind({ session: 'a1b2c3d4', home: process.env.LORELI_HOME });
+```
+
+When only `home` is provided (no session), logs write to `<home>/loreli.log` as a pre-session fallback.
+
+### `reset()`
+
+Clear all cached loggers and state. Used in tests to ensure isolation between runs.
+
+## Log File Layout
+
+```
+~/.loreli/
+  loreli.log                             (pre-session fallback)
+  sessions/
+    a1b2c3d4/
+      logs/
+        orchestrator.log                 (server-level events)
+        optimus-0.log                    (per-agent log)
+        megatron-0.log
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LORELI_LOG_LEVEL` | `info` | Console log level (`error`, `warn`, `info`, `debug`) |
+| `LORELI_HOME` | `~/.loreli/` | Base directory for log files |
+
+File transport always writes at `debug` level in JSON format for post-mortem analysis. Console transport respects `LORELI_LOG_LEVEL`.
+
+### Configuration via loreli/config
+
+When used through Loreli's orchestration layer, logging settings are configurable via `loreli.yml`:
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `log.level` | `info` | Console log level |
+| `log.maxSize` | `10485760` | Max size per log file in bytes (10 MB) |
+| `log.maxFiles` | `3` | Number of rotated log files to keep |
+
+The `LORELI_LOG_LEVEL` environment variable still works and is resolved as an environment layer in config's resolution chain (between `loreli.yml` and built-in defaults).
+
+## Design Decisions
+
+- **Lazy file transport**: File transport is only added after `bind()`. Before that, only console is active.
+- **Per-agent isolation**: Each agent gets its own log file for easy debugging.
+- **Size-based rotation**: 10MB per file, 3 rotated files kept.
+- **JSON file format**: Machine-parseable for CI/monitoring. Console uses human-readable format.

package/packages/log/src/index.js

@@ -0,0 +1,252 @@
+import winston from 'winston';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * Module-level state for the logging subsystem.
+ * `home` is the base directory for log files (~/.loreli/ by default).
+ * `session` is the active session ID (set via bind()).
+ * `loggers` caches loggers by package name.
+ */
+let home = process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+let session = null;
+let bound = false;
+
+/** @type {object|null} loreli/config instance, set via bind(). */
+let cfg = null;
+
+const loggers = new Map();
+const agentLoggers = new Map();
+
+/**
+ * Resolve the effective max file size in bytes.
+ * Delegates to loreli/config if bound, else hardcoded default.
+ *
+ * @returns {number}
+ */
+function effectiveMaxSize() {
+  return cfg?.get?.('log.maxSize') ?? 10 * 1024 * 1024;
+}
+
+/**
+ * Resolve the effective max files count.
+ * Delegates to loreli/config if bound, else hardcoded default.
+ *
+ * @returns {number}
+ */
+function effectiveMaxFiles() {
+  return cfg?.get?.('log.maxFiles') ?? 3;
+}
+
+/**
+ * Resolve the effective log level for file transports.
+ * Delegates to loreli/config if bound, else env > hardcoded default.
+ *
+ * @returns {string}
+ */
+function effectiveLevel() {
+  return cfg?.get?.('log.level') ?? process.env.LORELI_LOG_LEVEL ?? 'debug';
+}
+
+/**
+ * Create the JSON format used for file transports.
+ *
+ * @returns {winston.Logform.Format} JSON format with timestamp.
+ */
+function fileFormat() {
+  return winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  );
+}
+
+/**
+ * Ensure a directory exists, creating it recursively if needed.
+ *
+ * @param {string} dir - Directory path.
+ */
+function ensure(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Get the logs directory path for the current session.
+ *
+ * @returns {string|null} Logs directory or null if no session is bound.
+ */
+function logsDir() {
+  if (!session) return null;
+  return join(home, 'sessions', session, 'logs');
+}
+
+/**
+ * Create the pre-session fallback file transport.
+ * Writes to `~/.loreli/loreli.log` before a session is bound.
+ *
+ * @returns {winston.transports.FileTransportInstance} File transport.
+ */
+function fallbackTransport() {
+  ensure(home);
+  return new winston.transports.File({
+    filename: join(home, 'loreli.log'),
+    format: fileFormat(),
+    level: effectiveLevel(),
+    maxsize: effectiveMaxSize(),
+    maxFiles: effectiveMaxFiles()
+  });
+}
+
+/**
+ * Add the appropriate file transport to a logger after bind().
+ * When a session is active, writes to the session's orchestrator log.
+ * Otherwise falls back to `home/loreli.log`.
+ *
+ * @param {winston.Logger} log - The winston logger to augment.
+ */
+function addBoundTransport(log) {
+  const dir = logsDir();
+  if (!dir) {
+    // No session — add fallback transport at current home
+    ensure(home);
+    log.add(new winston.transports.File({
+      filename: join(home, 'loreli.log'),
+      format: fileFormat(),
+      level: effectiveLevel(),
+      maxsize: effectiveMaxSize(),
+      maxFiles: effectiveMaxFiles()
+    }));
+    return;
+  }
+
+  ensure(dir);
+  log.add(new winston.transports.File({
+    filename: join(dir, 'orchestrator.log'),
+    format: fileFormat(),
+    level: effectiveLevel(),
+    maxsize: effectiveMaxSize(),
+    maxFiles: effectiveMaxFiles()
+  }));
+}
+
+/**
+ * Create a per-agent file-only logger that writes to a dedicated log file.
+ *
+ * @param {string} name - Agent identity name (e.g. 'optimus-0').
+ * @param {string} pkg - Package name for the logger's defaultMeta.
+ * @returns {winston.Logger} A logger writing to the agent's log file.
+ */
+function createAgentLogger(name, pkg) {
+  const dir = logsDir();
+  const transports = [fallbackTransport()];
+
+  if (dir) {
+    ensure(dir);
+    transports.push(new winston.transports.File({
+      filename: join(dir, `${name}.log`),
+      format: fileFormat(),
+      level: effectiveLevel(),
+      maxsize: effectiveMaxSize(),
+      maxFiles: effectiveMaxFiles()
+    }));
+  }
+
+  return winston.createLogger({
+    level: effectiveLevel(),
+    defaultMeta: { package: pkg, agent: name },
+    transports
+  });
+}
+
+/**
+ * Create or retrieve a logger scoped to a package name.
+ *
+ * All output goes to file only — no console transports — so stdout
+ * and stderr stay clean for protocols like MCP stdio.
+ *
+ * Before `bind()`, logs write to `~/.loreli/loreli.log`.
+ * After `bind()`, a session-scoped transport is added that writes to
+ * `~/.loreli/sessions/<session>/logs/orchestrator.log`.
+ *
+ * @param {string} pkg - The package name (e.g. 'agent', 'hub', 'mcp').
+ * @returns {object} A logger with info/warn/error/debug methods and an agent() factory.
+ */
+export function logger(pkg) {
+  if (loggers.has(pkg)) return loggers.get(pkg);
+
+  const log = winston.createLogger({
+    level: effectiveLevel(),
+    defaultMeta: { package: pkg },
+    transports: [fallbackTransport()]
+  });
+
+  // Attach bound transport if already bound
+  if (bound) addBoundTransport(log);
+
+  /**
+   * Create a per-agent sub-logger that writes to a dedicated log file.
+   *
+   * @param {string} name - Agent identity name (e.g. 'optimus-0').
+   * @returns {object} A logger with info/warn/error/debug methods.
+   */
+  log.agent = function agent(name) {
+    const key = `${pkg}:${name}`;
+    if (agentLoggers.has(key)) return agentLoggers.get(key);
+
+    const agentLog = createAgentLogger(name, pkg);
+    agentLoggers.set(key, agentLog);
+    return agentLog;
+  };
+
+  loggers.set(pkg, log);
+  return log;
+}
+
+/**
+ * Bind the logging subsystem to a session, home directory, and/or config.
+ *
+ * After binding, all existing loggers gain an additional file transport.
+ * When a session is provided, it writes to the session's logs directory.
+ * Without a session, it writes to `home/loreli.log`. New loggers created
+ * after bind() also receive the bound transport automatically.
+ *
+ * Log settings (level, maxSize, maxFiles) are resolved through the config
+ * instance's full resolution chain: overrides > loreli.yml > env > defaults.
+ *
+ * @param {object} opts - Bind options.
+ * @param {string} [opts.session] - Session ID for log file path.
+ * @param {string} [opts.home] - Override the base directory (~/.loreli/).
+ * @param {object} [opts.config] - loreli/config instance with a get() method.
+ */
+export function bind(opts = {}) {
+  if (opts.home) home = opts.home;
+  if (opts.session) session = opts.session;
+  if (opts.config) cfg = opts.config;
+  bound = true;
+
+  // Add file transports to all existing loggers
+  for (const log of loggers.values()) {
+    addBoundTransport(log);
+  }
+}
+
+/**
+ * Reset the logging subsystem. Clears all cached loggers and state.
+ * Primarily used in tests to ensure a clean slate between runs.
+ */
+export function reset() {
+  // Close all transports to prevent file handle leaks
+  for (const log of loggers.values()) {
+    log.close();
+  }
+  for (const log of agentLoggers.values()) {
+    log.close();
+  }
+
+  loggers.clear();
+  agentLoggers.clear();
+  session = null;
+  bound = false;
+  cfg = null;
+  home = process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+}

package/packages/marker/README.md

@@ -0,0 +1,200 @@
+# loreli/marker
+
+Machine-readable HTML comment markers for GitHub content. Decouples workflow-state detection from human-visible text so themed messages can change freely without breaking parsing logic.
+
+## Why
+
+Loreli embeds metadata in GitHub comments, PR bodies, and discussion posts. Previously, parsing relied on human-visible strings like `"Claimed by"` or `"| Agent |"`, which broke when text was themed or reformatted. This package standardizes a single marker format across all packages.
+
+## Marker Format
+
+```
+<!-- loreli:TYPE key="value" key="value" -->
+```
+
+Markers are HTML comments — invisible to GitHub readers but reliably parseable. The `loreli:` prefix namespaces them to avoid collisions with other tooling.
+
+## Installation
+
+Already available as a workspace export:
+
+```js
+import { mark, has, parse, strip, stripLast, excise } from 'loreli/marker';
+```
+
+## API Reference
+
+### `mark(type, data?)`
+
+Produces a marker string.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `string` | yes | Marker type (e.g. `'claim'`, `'signature'`, `'agent'`). |
+| `data` | `Object<string, string>` | no | Key-value pairs to embed in the marker. |
+
+**Returns:** `string` — an HTML comment marker.
+
+**Throws:** `Error` — if `type` is falsy or empty.
+
+The following example creates a claim marker with an agent identifier, which is the most common pattern used by the action package to tag issue claims:
+
+```js
+mark('claim', { agent: 'optimus-0' });
+// → '<!-- loreli:claim agent="optimus-0" -->'
+```
+
+Type-only markers (no data) are used for structural markers like signatures, where presence is all that matters:
+
+```js
+mark('signature');
+// → '<!-- loreli:signature -->'
+```
+
+### `has(body, type)`
+
+Checks whether a body contains a marker of the given type.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to look for. |
+
+**Returns:** `boolean` — `true` if the marker type is present.
+
+This is the primary detection function. Use it to branch on workflow state without inspecting visible text. Safe to call on null or empty bodies — always returns `false`:
+
+```js
+has(body, 'claim');    // true if body contains a loreli:claim marker
+has(null, 'claim');    // false
+```
+
+### `parse(body, type)`
+
+Extracts the key-value data from the first marker of the given type.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to extract. |
+
+**Returns:** `Object<string, string> | null` — parsed key-value data, or `null` if not found. Returns an empty object `{}` for type-only markers.
+
+Use `parse` when you need the embedded data, not just presence. For example, extracting which agent claimed an issue:
+
+```js
+parse(body, 'claim');
+// → { agent: 'optimus-0' }
+
+parse(body, 'signature');
+// → {} (type-only marker — present but no data)
+
+parse('no markers', 'claim');
+// → null
+```
+
+### `strip(body, type)`
+
+Removes the first marker of the given type and everything after it, trimming trailing whitespace.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to strip from. |
+
+**Returns:** `string | null | undefined` — body with the marker and all trailing content removed. Returns the input unchanged if the marker is not found or the input is null/empty.
+
+This is designed for signature stripping — removing the agent signature block that appears at the end of every stamped comment:
+
+```js
+const body = 'Review feedback here\n<!-- loreli:signature -->\n***\n| Agent | Model | ...';
+strip(body, 'signature');
+// → 'Review feedback here'
+```
+
+### `stripLast(body, type)`
+
+Removes the **last** marker of the given type and everything after it, trimming trailing whitespace. Use when multiple markers exist and only the trailing one should be removed (e.g. duplicate signatures at end of body).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to strip from. |
+
+**Returns:** `string | null | undefined` — body with the last marker and all trailing content removed. Returns the input unchanged if the marker is not found or the input is null/empty.
+
+```js
+const body = '## Content\n<!-- loreli:signature -->\n***\n...\n<!-- loreli:signature -->\n***\n...';
+stripLast(body, 'signature');
+// → '## Content\n<!-- loreli:signature -->\n***\n...' (one signature remains)
+```
+
+### `excise(body, type)`
+
+Removes content between paired markers of the given type. Finds the opening `<!-- loreli:TYPE ... -->` and closing `<!-- loreli:TYPE-end -->`, removes both markers and everything between them, and collapses extra blank lines at the join point.
+
+Unlike `strip()`, which removes a marker and everything after it, `excise()` removes only the delimited section and preserves content on both sides. Designed for trace blocks and other self-contained sections embedded within larger bodies.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `body` | `string \| null \| undefined` | yes | GitHub comment/PR/discussion body. |
+| `type` | `string` | yes | Marker type to excise (matches TYPE and TYPE-end). |
+
+**Returns:** `string | null | undefined` — body with the marker-delimited section removed. Returns input unchanged if start or end marker is missing.
+
+Use `excise` to remove trace blocks from PR bodies before passing content to reviewer prompts or returning it through the `read` MCP tool:
+
+```js
+const body = 'Closes #42\n\n<!-- loreli:trace agent="bee-0" -->\n<details>...</details>\n<!-- loreli:trace-end -->\n\nMore content';
+excise(body, 'trace');
+// → 'Closes #42\nMore content'
+```
+
+When the end marker is missing, the body is returned unchanged to avoid accidental content loss:
+
+```js
+excise('text<!-- loreli:trace -->orphaned', 'trace');
+// → 'text<!-- loreli:trace -->orphaned'
+```
+
+## Error Behavior
+
+| Scenario | Function | Behavior |
+|----------|----------|----------|
+| Falsy/empty `type` | `mark()` | Throws `Error: type is required` |
+| Null/undefined/empty `body` | `has()` | Returns `false` |
+| Null/undefined/empty `body` | `parse()` | Returns `null` |
+| Null/undefined `body` | `strip()` | Returns input unchanged |
+| Null/undefined `body` | `excise()` | Returns input unchanged |
+| Marker not found | `has()` | Returns `false` |
+| Marker not found | `parse()` | Returns `null` |
+| Marker not found | `strip()` | Returns body unchanged |
+| Start marker not found | `excise()` | Returns body unchanged |
+| End marker not found | `excise()` | Returns body unchanged |
+
+## Marker Types in Use
+
+| Type | Emitted By | Consumed By | Purpose |
+|------|-----------|-------------|---------|
+| `claim` | action `claim()` | action `claimant()` | Issue claim detection |
+| `signoff` | review `signoff()` | review tests | Approval detection |
+| `release` | action `reassign()` | — | Release tracking (consistency) |
+| `gate` | review `gate()` | — | HITL state tracking (consistency) |
+| `agent` | hub `_stamp()` | gate tool | Agent comment filtering |
+| `signature` | `Identity.signature()` | `Identity.strip()` | Signature block detection/removal |
+| `review-event` | hub `_stamp()` | hub review patching | Review event type embedding |
+| `parent` | planner `link()` | planner `link()` | Parent tracking issue detection for sub-issue linking |
+| `trace` | agent trace `format()` | `excise(body, 'trace')` | Agent reasoning/output block (paired with `trace-end`) |
+| `trace-end` | agent trace `format()` | `excise(body, 'trace')` | Closing marker for trace block |