loreli 0.0.0 → 1.0.0

package/packages/agent/README.md

@@ -0,0 +1,517 @@
+# loreli/agent
+
+Agent lifecycle management with pluggable backends, session persistence, and role-based prompt templating.
+
+## API Reference
+
+### Agent (Base Class)
+
+Abstract base class for all backends. Extends `EventEmitter`.
+
+```js
+import { Agent } from 'loreli/agent';
+
+const agent = new Agent({ identity, role: 'action', cwd: '/path/to/repo' });
+agent.state;           // 'idle' | 'spawned' | 'working' | 'standby' | 'reviewing' | 'dormant'
+agent.canTransition('spawned'); // true — check before transitioning
+await agent.spawn();   // Start the agent
+await agent.send(msg); // Deliver work
+await agent.capture();   // Read latest output (default 500 lines)
+await agent.capture(40); // Read last 40 lines
+await agent.stop();    // Graceful shutdown
+```
+
+#### State Machine
+
+Agent state transitions are validated. Invalid transitions throw an error. The `dormant` state is terminal — a dormant agent cannot be reactivated without a fresh spawn.
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> spawned
+    idle --> dormant
+    spawned --> working
+    spawned --> standby
+    spawned --> dormant
+    working --> standby
+    working --> reviewing
+    working --> awaiting_hitl
+    working --> dormant
+    standby --> working
+    standby --> reviewing
+    standby --> awaiting_hitl
+    standby --> dormant
+    reviewing --> working
+    reviewing --> standby
+    reviewing --> awaiting_hitl
+    reviewing --> dormant
+    awaiting_hitl --> working
+    awaiting_hitl --> standby
+    awaiting_hitl --> dormant
+    dormant --> [*]
+```
+
+### Session State Machine
+
+Sessions track the same states as agents (minus `idle`) with the same validated transitions:
+
+```js
+import { Session, STATES, TRANSITIONS } from 'loreli/agent';
+
+const s = new Session({ identity, role: 'action', backend: 'claude' });
+s.state;                    // 'spawned'
+s.canTransition('working'); // true
+s.transition('working');    // valid
+s.transition('dormant');    // valid (terminal)
+s.transition('working');    // throws: Invalid transition: "dormant" -> "working"
+```
+
+### CliAgent
+
+Tmux-managed CLI agent. Each agent gets its own window in the `loreli` tmux session.
+
+All backends use a **launcher script** pattern for spawn: a `/bin/sh` script is written to the agent's cwd and executed directly via `tmux new-window`, bypassing the user's login shell (`.zshrc`, etc.) and its initialization prompts.
+
+```js
+import { CliAgent } from 'loreli/agent';
+
+const agent = new CliAgent({
+  identity, role: 'action', cwd: '/path/to/repo',
+  command: 'claude --dangerously-skip-permissions --model claude-sonnet-4-20250514'
+});
+
+await agent.spawn();    // Writes launcher script, creates tmux window
+await agent.send(msg);  // tmux send-keys (single-line) or file-based (multi-line)
+await agent.capture(n); // tmux capture-pane (optional line count, defaults to 500)
+await agent.alive();    // tmux pane alive check
+await agent.stop();     // kill pane
+```
+
+### Backend Hierarchy
+
+```mermaid
+graph TD
+  Agent["Agent (abstract, EventEmitter)"]
+  CliAgent["CliAgent (tmux-managed)"]
+  Claude["ClaudeBackend (interactive)"]
+  Cursor["CursorBackend (interactive, multi-provider)"]
+  Codex["CodexBackend (interactive)"]
+
+  Agent --> CliAgent
+  CliAgent --> Claude
+  CliAgent --> Cursor
+  CliAgent --> Codex
+```
+
+### Backends
+
+#### ClaudeBackend
+
+Interactive backend using the `claude` CLI. Stays running in a tmux pane. Provider: `anthropic`.
+
+Uses `--dangerously-skip-permissions` to bypass all startup dialogs (workspace trust, permission bypass). Uses `--mcp-config` to load the scaffolded `.mcp.json` that connects the agent back to Loreli. Prompts are delivered via `send()` (not `--prompt`) to avoid shell injection.
+
+```js
+import { ClaudeBackend } from 'loreli/agent';
+
+const agent = new ClaudeBackend({
+  identity, role: 'action', cwd: '/path/to/repo',
+  model: 'balanced',  // resolves via config, defaults to claude-sonnet-4-5-20250929
+  config              // optional Config instance for model resolution
+});
+// command: claude --dangerously-skip-permissions --model claude-sonnet-4-5-20250929 --mcp-config /path/to/repo/.mcp.json
+```
+
+#### CursorBackend
+
+Interactive backend using the `cursor-agent` CLI. Multi-provider — runs models from Anthropic, OpenAI, Google, and others via a single binary. This makes it the natural fallback when provider-specific CLIs (`claude`, `codex`) are unavailable or their API endpoints are unreachable (e.g. behind a VPN-dependent proxy).
+
+The yin/yang adversarial pairing is preserved because each agent's identity carries its provider. Model aliases resolve directly from config via `backends.cursor.models.{tier}.{provider}` — no translation table. Unknown model names are passed through directly, so cursor-specific names like `gemini-3-pro` work out of the box.
+
+The command includes `--force` (auto-approve tool usage), `--sandbox disabled` (no sandbox prompts), and `--approve-mcps` (auto-approve the scaffolded Loreli MCP server). Multi-line prompts are written to a temporary Markdown file and delivered via a single-line reference, matching the `ClaudeBackend` pattern.
+
+```js
+import { CursorBackend } from 'loreli/agent';
+
+// Anthropic-side agent — resolves balanced to sonnet-4.5-thinking from config
+const action = new CursorBackend({
+  identity: anthropicIdentity, role: 'action', cwd: '/path/to/repo',
+  model: 'balanced'
+});
+// command: cursor-agent --model sonnet-4.5-thinking --force --sandbox disabled --approve-mcps --workspace /path/to/repo
+
+// OpenAI-side agent — resolves balanced to gpt-5.3-codex from config
+const reviewer = new CursorBackend({
+  identity: openaiIdentity, role: 'reviewer', cwd: '/path/to/repo',
+  model: 'balanced'
+});
+// command: cursor-agent --model gpt-5.3-codex --force --sandbox disabled --approve-mcps --workspace /path/to/repo
+```
+
+#### CodexBackend
+
+Interactive backend using the `codex` CLI. Stays running in a tmux pane. Provider: `openai`.
+
+Uses `-a never` (disable approval prompts), `-s workspace-write` (sandboxed write access), and `--no-alt-screen` (inline TUI mode for tmux capture compatibility). MCP servers are injected via `-c` flags because Codex only reads `~/.codex/config.toml` (global), not local config. When token context is present, Codex forwards `GITHUB_TOKEN` via `mcp_servers.loreli.env_vars` so no literal token appears in command flags. Multi-line prompts are written to a Markdown file and delivered via a single-line reference, matching the ClaudeBackend pattern.
+
+```js
+import { CodexBackend } from 'loreli/agent';
+
+const agent = new CodexBackend({
+  identity, role: 'action', cwd: '/path/to/repo',
+  model: 'fast',  // resolves via config, defaults to gpt-5-mini
+  config           // optional Config instance for model resolution
+});
+// command: codex --model gpt-5-mini -a never -s workspace-write --no-alt-screen -C /path/to/repo
+```
+
+### Session
+
+Tracks runtime state. Persisted to disk for resilience.
+
+```js
+import { Session } from 'loreli/agent';
+
+const session = new Session({
+  identity: { name: 'optimus-0', provider: 'openai' },
+  role: 'action', backend: 'claude', paneId: '%3'
+});
+
+session.transition('working');
+session.toJSON();
+await session.save('/path/to/file.json');
+```
+
+**States**: `spawned` -> `working` -> `standby` -> `reviewing` -> `awaiting_hitl` -> `dormant`
+
+#### Session State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> spawned
+    spawned --> working
+    working --> standby
+    working --> reviewing
+    standby --> working
+    reviewing --> working: feedback
+    reviewing --> awaiting_hitl: HITL
+    awaiting_hitl --> working: rework
+    awaiting_hitl --> dormant: human merges
+    working --> dormant
+    reviewing --> dormant
+```
+
+#### HITL Fields
+
+When HITL (human in the loop) is active, sessions track additional state:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `reviewers` | `string[]` | `[]` | GitHub usernames assigned as human reviewers |
+| `agentApprovals` | `Array<{name, provider, timestamp}>` | `[]` | Agent approval records |
+| `hitlAt` | `string\|null` | `null` | ISO timestamp when HITL was activated |
+
+### BackendRegistry
+
+Discovers available backends at startup by checking which CLI binaries exist on PATH.
+
+```js
+import { BackendRegistry } from 'loreli/agent';
+
+const registry = new BackendRegistry();
+await registry.discover();
+
+registry.available();   // [{ name, provider, binary }]
+registry.providers();   // ['anthropic', 'openai', 'cursor-openai', 'cursor-anthropic']
+registry.has('cursor'); // true if cursor-agent is installed
+registry.has('claude'); // true if claude is installed
+
+// Dynamic registration
+registry.register('custom', CustomBackend, { provider: 'custom' });
+```
+
+The registry auto-detects these built-in backends:
+
+| Name | Binary | Provider |
+|------|--------|----------|
+| `claude` | `claude` | `anthropic` |
+| `codex` | `codex` | `openai` |
+| `cursor` | `cursor-agent` | `multi` |
+
+#### `forProvider(provider)` — Provider-Aware Backend Selection
+
+The primary entry point for choosing a backend by AI provider. The orchestrator and any other consumer should call this instead of implementing their own discovery logic.
+
+Resolution order:
+1. **Exact match** — backend whose `provider` matches (e.g. `claude` for `'anthropic'`)
+2. **Multi-provider fallback** — `cursor` (runs any provider via cursor-agent)
+3. **Default fallback** — `defaultBackend()` chain (claude → cursor → first)
+
+This example shows how cursor-agent acts as a transparent fallback when the `claude` binary is absent or its API endpoint is unreachable:
+
+```js
+const registry = new BackendRegistry();
+await registry.discover();
+
+// When claude is installed and reachable:
+registry.forProvider('anthropic'); // 'claude'
+registry.forProvider('openai');    // 'codex'
+
+// When only cursor-agent is installed (VPN down, or no claude/codex):
+registry.forProvider('anthropic'); // 'cursor' — runs sonnet-4.5
+registry.forProvider('openai');    // 'cursor' — runs gpt-5.2
+```
+
+### Factory
+
+Centralizes the agent creation pipeline: discover → acquire identity → create working directory → select backend → instantiate. This eliminates duplication between the orchestrator's `enlist()` and `rework()` paths and ensures consistent backend selection via `forProvider()`.
+
+The factory **creates** agents but does not **spawn** them. Spawning and registration is the caller's responsibility.
+
+```js
+import { Factory, BackendRegistry } from 'loreli/agent';
+import { Registry } from 'loreli/identity';
+import { Config } from 'loreli/config';
+
+const config = new Config();
+await config.load(hub, 'owner/repo');
+
+const factory = new Factory({
+  backends: new BackendRegistry(),
+  identities: new Registry(),
+  config
+});
+
+// Create an action agent for the anthropic side
+const agent = await factory.create('anthropic', 'action', {
+  theme: 'transformers',
+  model: 'balanced'
+});
+
+// agent.state === 'idle' — caller spawns when ready
+await agent.spawn();
+```
+
+The factory threads `config` to each backend constructor for config-driven model resolution. A per-create config override is also supported via `opts.config`.
+
+### Output Utilities
+
+Agent output processing: ANSI stripping, truncation, and cleaning.
+
+```js
+import { output } from 'loreli/agent';
+
+const raw = await agent.capture();
+const cleaned = output.clean(raw);       // strip ANSI + truncate to 12000 chars
+const stripped = output.strip(raw);       // strip ANSI only
+const short = output.truncate(raw, 5000); // truncate only, custom limit
+```
+
+### Workspace Preparation Re-export
+
+`loreli/agent` re-exports `prepare` from `loreli/workspace` for callers that build agents and workspaces together.
+
+```js
+import { prepare } from 'loreli/agent';
+
+await prepare('~/.loreli/workspaces/loreli-optimus-0', {
+  session: 's1',
+  agent: 'optimus-0',
+  repo: 'owner/repo'
+});
+```
+
+### Model Aliases
+
+Loreli provides human-friendly model aliases that resolve to backend-specific and provider-specific identifiers. Resolution is config-driven — aliases map to concrete model IDs through the standard config resolution chain (overrides > loreli.yml > defaults).
+
+The `resolve()` function takes an alias, backend name, provider, and optional `config` parameter. It looks up `config.get('backends.{backend}.models.{alias}.{provider}')` first, then falls through to built-in defaults from `defaults.js`. Exact model strings (not matching any alias) are returned unchanged.
+
+The following example demonstrates basic alias resolution using built-in defaults. Each backend has its own model mappings — the claude backend resolves to provider-specific model IDs, while the cursor backend resolves to cursor-agent short names:
+
+```js
+import { models } from 'loreli/agent';
+
+models.resolve('fast', 'claude', 'anthropic');    // 'claude-haiku-4-5-20251001'
+models.resolve('fast', 'codex', 'openai');        // 'gpt-5-mini'
+models.resolve('fast', 'cursor', 'anthropic');    // 'sonnet-4.5'
+models.resolve('gpt-custom', 'codex', 'openai'); // 'gpt-custom' (passthrough)
+```
+
+The following example demonstrates overriding model IDs via config. This is useful when your environment routes through a different proxy or you have access to newer model versions:
+
+```js
+import { models } from 'loreli/agent';
+import { Config } from 'loreli/config';
+
+const config = new Config();
+config.file = {
+  backends: {
+    codex: {
+      models: {
+        fast: { openai: 'my-custom-gpt' }
+      }
+    }
+  }
+};
+
+models.resolve('fast', 'codex', 'openai', config);     // 'my-custom-gpt'
+models.resolve('balanced', 'codex', 'openai', config);  // 'gpt-5.1-codex' (falls to defaults)
+```
+
+#### Default Model Mappings
+
+**Claude backend** (Anthropic model IDs):
+
+| Alias | Anthropic |
+|-------|-----------|
+| `fast` | `claude-haiku-4-5-20251001` |
+| `balanced` | `claude-sonnet-4-5-20250929` |
+| `powerful` | `claude-opus-4-5-20251101` |
+
+**Codex backend** (OpenAI model IDs):
+
+| Alias | OpenAI |
+|-------|--------|
+| `fast` | `gpt-5-mini` |
+| `balanced` | `gpt-5.1-codex` |
+| `powerful` | `gpt-5.2-pro` |
+
+**Cursor backend** (cursor-agent short names):
+
+| Alias | Anthropic | OpenAI |
+|-------|-----------|--------|
+| `fast` | `sonnet-4.5` | `gpt-5.3-codex-low` |
+| `balanced` | `sonnet-4.5-thinking` | `gpt-5.3-codex` |
+| `powerful` | `opus-4.6-thinking` | `gpt-5.1-codex-max` |
+
+#### Overriding via `loreli.yml`
+
+Add a `backends` section to the target repo's `loreli.yml` to override the defaults. Unknown backends, tiers, and providers are passed through, so custom configurations work out of the box:
+
+```yaml
+backends:
+  claude:
+    models:
+      fast:
+        anthropic: my-proxy-haiku
+      balanced:
+        anthropic: my-proxy-sonnet
+  codex:
+    models:
+      fast:
+        openai: my-proxy-gpt-mini
+```
+
+#### Resolution Chain
+
+Model resolution follows the same priority as all config values:
+
+1. **Start params** — `config.merge({ backends: { claude: { models: { ... } } } })`
+2. **`loreli.yml`** — `backends.{name}.models` section in the target repo
+3. **Built-in defaults** — hardcoded in `defaults.js`
+
+Exact model strings (those not matching any alias) bypass resolution entirely.
+
+### Backend Environment Variables
+
+The `models.env()` function collects environment variables for a backend's launcher script. It merges two layers:
+
+1. **Inherited** — `process.env` vars matching the backend's known prefixes (e.g. `ANTHROPIC_*`, `CLAUDE_*` for the `claude` backend) are collected automatically
+2. **Config overrides** — `backends.{name}.env` from `loreli.yml` or `config.merge()` take precedence on key collision
+
+This ensures critical variables like `ANTHROPIC_BASE_URL` (proxy URL), `ANTHROPIC_AUTH_TOKEN`, and `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` are forwarded from the orchestrator's `process.env` into tmux-spawned agents — even when the tmux server's environment doesn't have them.
+
+The following example demonstrates how `env()` collects process.env vars and merges with config overrides. This is what each backend calls in its constructor to populate `this._env`:
+
+```js
+import { models } from 'loreli/agent';
+
+// With ANTHROPIC_BASE_URL set in process.env:
+const vars = models.env('claude');
+// { ANTHROPIC_BASE_URL: '...', ANTHROPIC_AUTH_TOKEN: '...', CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '...' }
+
+// Config overrides take precedence:
+const config = new Config();
+config.file = { backends: { claude: { env: { ANTHROPIC_BASE_URL: 'https://override.example.com' } } } };
+const vars2 = models.env('claude', config);
+// { ANTHROPIC_BASE_URL: 'https://override.example.com', ...inherited }
+```
+
+| Backend | Inherited Prefixes |
+|---------|-------------------|
+| `claude` | `ANTHROPIC_*`, `CLAUDE_*` |
+| `codex` | `OPENAI_*`, `CODEX_*` |
+| `cursor` | `ANTHROPIC_*`, `OPENAI_*`, `CLAUDE_*`, `CURSOR_*` |
+
+Returns `undefined` when no matching vars exist in either layer.
+
+### Formatting Env for Launcher Scripts
+
+The `models.format()` function converts an env object into shell `export` lines for launcher scripts. Values are single-quoted to prevent shell expansion.
+
+```js
+import { models } from 'loreli/agent';
+
+models.format({ ANTHROPIC_BASE_URL: 'https://proxy.example.com', FOO: 'bar' });
+// "export ANTHROPIC_BASE_URL='https://proxy.example.com'\nexport FOO='bar'\n"
+
+models.format(undefined); // '' (empty string)
+models.format({});        // '' (empty string)
+```
+
+All three CLI backends (`ClaudeBackend`, `CodexBackend`, `CursorBackend`) use `format(this._env)` when writing their launcher scripts.
+
+### Model Display Names
+
+Convert full API model identifiers to human-readable labels. Uses a date-stripping heuristic — strips trailing `-YYYYMMDD` date suffixes.
+
+```js
+import { models } from 'loreli/agent';
+
+models.display('claude-haiku-4-5-20251001');  // 'claude-haiku-4-5'
+models.display('claude-sonnet-4-5-20250929'); // 'claude-sonnet-4-5'
+models.display('gpt-5-mini');                 // 'gpt-5-mini'
+models.display('o3');                         // 'o3'
+
+// Unknown models: strips trailing date suffix
+models.display('claude-sonnet-5-20260101');   // 'claude-sonnet-5'
+
+// No date suffix: returned unchanged
+models.display('gemini-3-pro');               // 'gemini-3-pro'
+```
+
+| Full Identifier | Display Name |
+|----------------|-------------|
+| `claude-haiku-4-5-20251001` | `claude-haiku-4-5` |
+| `claude-sonnet-4-5-20250929` | `claude-sonnet-4-5` |
+| `claude-opus-4-5-20251101` | `claude-opus-4-5` |
+| `gpt-5-mini` | `gpt-5-mini` |
+| `gpt-5.1-codex` | `gpt-5.1-codex` |
+| `gpt-5.2-pro` | `gpt-5.2-pro` |
+
+## Fallback Strategies
+
+Backend selection is handled entirely by `BackendRegistry.forProvider()`. The orchestrator never implements its own discovery logic.
+
+| Environment | Strategy |
+|-------------|----------|
+| claude + codex installed | Yin/Yang: dedicated CLIs per provider |
+| Only cursor-agent installed | Yin/Yang: cursor-agent runs both sides with different models |
+| Mixed (e.g. claude + cursor-agent) | Exact match first, cursor fills the gap |
+| Nothing available | Error with installation guidance |
+
+## Session Persistence
+
+Agents are spawned detached — they survive orchestrator shutdown. State is persisted to `~/.loreli/sessions/<id>/`:
+
+```
+~/.loreli/sessions/<id>/
+  config.json           (repo, theme, strategy)
+  agents/
+    optimus-0.json      (identity, state, paneId)
+  registry.json         (name tracking)
+  logs/
+    orchestrator.log
+    optimus-0.log
+```