loreli 0.0.0 → 2.0.0

package/packages/workflow/README.md

@@ -0,0 +1,317 @@
+# loreli/workflow
+
+Shared contract for role-specific workflow packages. Provides a `Workflow` base class that planner, action, and review packages extend to implement their orchestration logic.
+
+## Research Findings
+
+Evaluated Temporal, Effect, and Flowcraft as potential base frameworks. All are full-featured workflow engines with durable execution, DAG-based routing, or functional effect systems — far too heavy for our lightweight abstract base class needs. Built from scratch using Node.js built-ins.
+
+## API Reference
+
+### `Workflow` (abstract base class)
+
+Subclasses define a `role` and a `template` path to their Mustache prompt file, then implement reactor handlers and event listeners.
+
+```js
+import { Workflow } from 'loreli/workflow';
+
+class Planner extends Workflow {
+  static role = 'planner';
+  static template = new URL('./prompts/planner.md', import.meta.url).pathname;
+
+  reactor() {
+    return { promote: this.promote.bind(this) };
+  }
+
+  events() {
+    return {}; // no orchestrator events needed
+  }
+
+  async promote(hub, repo) { /* ... */ }
+}
+```
+
+#### Constructor
+
+```js
+new Workflow(orchestrator, hub)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `orchestrator` | `Orchestrator` | The orchestrator instance for agent coordination |
+| `hub` | `BaseHub` | GitHub hub instance for API calls |
+
+#### `static role` → string
+
+The role name this workflow handles (`'planner'`, `'action'`, `'reviewer'`). Must be overridden by subclasses.
+
+#### `static template` → string
+
+Absolute path to the Mustache prompt template file for this role. Must be overridden by subclasses.
+
+#### `workflow.reactor()` → Record\<string, Function\>
+
+Return a map of reactor handler names to functions. The orchestrator's `tick()` calls each registered handler on every reactor cycle. Subclasses override this to register their specific handlers.
+
+**Returns**: `object` — Map of handler name to async function.
+
+#### `workflow.events()` → Record\<string, Function\>
+
+Return a map of orchestrator event names to listener functions. These are auto-wired to the orchestrator's EventEmitter when the workflow is attached.
+
+**Returns**: `object` — Map of event name (e.g. `'removed'`, `'stall'`) to handler.
+
+#### `workflow.agents()` → Agent[]
+
+Filter the orchestrator's agent map to only those matching this workflow's role.
+
+**Returns**: `Agent[]` — Agents whose `role` matches `static role`.
+
+#### `workflow.demand(repo)` → Promise\<{workload, supply, deficit}\>
+
+Report the current demand signal for this workflow's role. Returns a structured object with three fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workload` | `number` | Items that need an agent (unclaimed issues, unreviewed PRs, etc.) |
+| `supply` | `number` | Active (non-dormant) agents of this role |
+| `deficit` | `number` | `max(0, workload - supply)` — how many agents are needed |
+
+The base class returns `{ workload: 0, supply: 0, deficit: 0 }`. Each workflow overrides this using data from its hydrated state — no extra API calls. The orchestrator's `scale()` handler collects these signals and spawns agents proportional to deficit, respecting configurable caps and cooldowns.
+
+The following example shows how the demand signal drives scaling decisions — `scale()` calls `demand()` on each registered workflow and spawns agents for roles with a positive deficit:
+
+```js
+const signal = await reviewWorkflow.demand('owner/repo');
+// { workload: 3, supply: 1, deficit: 2 } — needs 2 more reviewers
+```
+
+#### `workflow.pair(identity, candidates)` → object | null
+
+Find the opposing-provider agent for yin/yang review pairing. Delegates to the orchestrator's identity registry.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `identity` | `Identity` | The identity to find an opposite for |
+| `candidates` | `object[]` | Candidate objects with an `identity` field |
+
+**Returns**: The matching agent, or `null`.
+
+#### `workflow.enlist(provider, role, opts?)` → Promise\<Agent\>
+
+Create and spawn a new agent via the orchestrator's factory. Convenience wrapper that delegates to `orchestrator.enlist()`.
+
+#### `workflow.custom(opts?)` → Promise\<string\>
+
+Load the project-specific custom prompt from the `workflows.{role}.prompt` config key (e.g. `workflows.action.prompt`, `workflows.reviewer.prompt`, `workflows.planner.prompt`, `workflows.risk.prompt`). By default, resolves this workflow's `static role`; pass `opts.role` to resolve another role during cross-role rendering. Reads each role-specific file once from the target repo via the hub and caches it on the instance. Returns an empty string when:
+
+- `workflows.{role}.prompt` is not configured for this workflow's role
+- The hub is unavailable (e.g. unit tests)
+- The repo is not set on the orchestrator
+- The file cannot be read (missing or inaccessible)
+
+Rendering never fails due to a missing custom prompt — this method degrades silently.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts.role` | `string` | Optional role override for `workflows.{role}.prompt` lookup |
+
+**Returns**: `Promise<string>` — Custom prompt text, or empty string.
+
+#### `workflow.render(vars)` → Promise\<string\>
+
+Load and render this workflow's prompt template with Mustache variables. Automatically prepends the shared autonomous-mode preamble and any per-role custom prompt from `workflows.{role}.prompt` (see [Autonomous Preamble](#autonomous-preamble) and [Custom Prompt Extensions](#custom-prompt-extensions) below).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `vars` | `object` | Template variables (name, repo, faction, provider, model, labels) |
+
+**Returns**: `Promise<string>` — Rendered prompt text with preamble and custom prompt prepended.
+
+#### `workflow.renderFrom(path, vars, opts?)` → Promise\<string\>
+
+Load and render an arbitrary Mustache template. Used for cross-role rendering (e.g. review package rendering the action prompt for `forward()`). Automatically prepends the shared autonomous-mode preamble and any per-role custom prompt.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | Absolute path to a `.md` template file |
+| `vars` | `object` | Template variables |
+| `opts.role` | `string` | Optional role override for custom prompt lookup. When set, resolves `workflows.{opts.role}.prompt` instead of this workflow's `static role` |
+
+**Returns**: `Promise<string>` — Rendered prompt text with preamble and custom prompt prepended.
+
+#### `workflow.dispatch(agent, vars)` → Promise\<void\>
+
+Send a rendered prompt to an agent. Renders this workflow's template and dispatches it to the agent's `send()` method.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agent` | `Agent` | Target agent |
+| `vars` | `object` | Template variables |
+
+### Proof-of-Life Protocol
+
+These methods implement the distributed coordination protocol for verifying agent liveness before eviction. The `check()` method is the unified gate — all eviction decisions (local and foreign) route through it as the single authority.
+
+#### `workflow.check(repo, number, agent)` → Promise\<string\>
+
+Unified proof-of-life gate for all eviction decisions. Posts a PoL request if none exists, checks for alive responses, and considers the response status when making the verdict.
+
+**Status-aware**: an alive response with `status: 'unhealthy'` returns `'release'` (the agent's own orchestrator confirmed it is stalled). A `'healthy'` response returns `'active'`. This is what enables local agent eviction through PoL — when `health()` (enhanced with tmux pane detection via `refresh()`) confirms the agent is truly stalled, the PoL system correctly signals eviction.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `agent` | `string` | Agent identity name to check |
+
+**Returns**: `'active'` | `'requested'` | `'pending'` | `'release'`
+
+| Return Value | Meaning |
+|-------------|---------|
+| `'active'` | Agent proved alive (healthy alive response or recent activity) |
+| `'requested'` | PoL request posted, check again next tick |
+| `'pending'` | PoL request exists, waiting for response |
+| `'release'` | Agent confirmed stalled (unhealthy alive, expired request, or timeout) |
+
+#### Low-Level Methods
+
+These are the building blocks that `check()` composes. They can be used directly for custom liveness logic.
+
+#### `workflow.requestProofOfLife(repo, number, agent)` → Promise\<void\>
+
+Post a themed proof-of-life request on an issue or PR. When the orchestrator has a `clientIdentity`, the comment includes a visible council-themed message (from the identity's theme) and is posted via a scoped hub (`hub.as(identity, 'orchestrator')`), which appends the orchestrator's signature. The machine-readable marker is embedded alongside the visible text.
+
+The marker includes the orchestrator's `sessionId` (as `orch`) when available. This enables orchestrator-scoped proof-of-life: a new orchestrator can distinguish its own requests from those left by a dead predecessor, and post a fresh request instead of blindly evicting based on an expired foreign request.
+
+Falls back to an unscoped invisible marker when no `clientIdentity` is available.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `agent` | `string` | Name of the agent being checked |
+
+#### `workflow.respondProofOfLife(repo, number, identity, role, verdict)` → Promise\<void\>
+
+Post a themed alive response with an embedded machine-readable marker. The response includes the agent's identity branding and the health check result.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `identity` | `Identity` | Agent identity for hub scoping and branding |
+| `role` | `string` | Agent role for hub scoping |
+| `verdict` | `object` | Health check result: `{ alive, status, details, outputLength? }` |
+
+#### `workflow.findProofOfLifeRequest(repo, number, agent, orch?)` → Promise\<object|null\>
+
+Find a pending proof-of-life request for a specific agent by scanning comments for `proof-of-life` markers.
+
+When `orch` is provided, only matches requests posted by that orchestrator session (the `orch` field in the marker must match). When omitted, matches any request for the agent — this is used by the responder, which answers regardless of who asked.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `agent` | `string` | Agent name to search for |
+| `orch` | `string?` | Orchestrator session ID filter (optional) |
+
+**Returns**: `{ agent, ts, orch? }` or `null` if no request exists.
+
+#### `workflow.findAliveResponse(repo, number, agent, after)` → Promise\<object|null\>
+
+Find an alive response for a specific agent posted after a given timestamp.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `agent` | `string` | Agent name to search for |
+| `after` | `number` | Only match responses with timestamp greater than this epoch ms |
+
+**Returns**: `{ agent, ts, status }` or `null` if no matching response exists.
+
+#### `workflow.hasRecentActivity(repo, number, timeout)` → Promise\<boolean\>
+
+Check whether an issue or PR has any GitHub comment within the timeout window.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | `string` | Repository in "owner/name" format |
+| `number` | `number` | Issue or PR number |
+| `timeout` | `number` | Maximum age in ms for activity to be considered recent |
+
+**Returns**: `true` if any comment was posted within the timeout window.
+
+### `responder(orchestrator, hub)` → Function
+
+Factory that creates the proof-of-life reactor handler. The handler scans all open `loreli`-labeled issues and PRs for proof-of-life request markers targeting agents in the local orchestrator's agents map, runs `health()` checks, and posts themed alive responses.
+
+Registered once during start and runs on every reactor tick. Ignores requests for agents not in the local map — only the managing orchestrator responds.
+
+```js
+import { responder } from 'loreli/workflow';
+
+orchestrator.register('proof-of-life', responder(orchestrator, hub));
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `orchestrator` | `Orchestrator` | Orchestrator with `agents` map and `health()` method |
+| `hub` | `BaseHub` | GitHub hub for reading/posting comments |
+
+**Returns**: `async function(repo)` — Reactor handler.
+
+## Autonomous Preamble
+
+All agent prompts run through `render()` or `renderFrom()`, which automatically prepend a shared preamble from `prompts/preamble.md`. This preamble instructs agents that they are running autonomously in a headless tmux pane and must never ask clarifying questions, invoke interactive skills, or wait for user input.
+
+The preamble is the single source of truth for autonomous-mode directives. Role-specific templates (action, planner, reviewer) do not duplicate this text — they inherit it through the rendering pipeline. This ensures every agent prompt carries the directive without per-template maintenance.
+
+The preamble is loaded once and cached for the lifetime of the process.
+
+## Custom Prompt Extensions
+
+Projects can inject per-role custom instructions into agent prompts by setting `workflows.{role}.prompt` in `loreli.yml`. Each role maps to a workflow and the value is a file path relative to the repository root.
+
+```yaml
+# loreli.yml
+workflows:
+  action:
+    prompt: .loreli/action.md
+  reviewer:
+    prompt: .loreli/review.md
+  planner:
+    prompt: .loreli/planner.md
+  risk:
+    prompt: .loreli/risk.md
+```
+
+When configured, `render()` and `renderFrom()` resolve `workflows.{role}.prompt` from config, read the file from the target repo via the hub, and insert its content between the autonomous preamble and the role-specific template:
+
+1. **Autonomous preamble** (`prompts/preamble.md`) — always present
+2. **Custom prompt** (`workflows.{role}.prompt`) — when configured for the current role
+3. **Role template** (action/planner/reviewer `.md` file)
+
+Each role resolves independently — an action workflow only reads `workflows.action.prompt`, a reviewer only reads `workflows.reviewer.prompt`. Roles without a configured prompt file are unaffected.
+
+The file is read once on the first `render()` call and cached on the `Workflow` instance for the remainder of the session. If the file is missing or unreadable, rendering continues normally — agents are never blocked by a missing custom prompt.
+
+The custom prompt is static text (not processed through Mustache). Tailor each role's prompt to its responsibilities: coding standards for action agents, quality gates for reviewers, methodology for planners.
+
+See the root [README](../../README.md#custom-prompt-extensions) for detailed usage examples and guidelines.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `Cannot construct Workflow directly` | Instantiating `Workflow` without subclassing | Extend the class and define `static role` and `static template` |
+| `Template not found: {path}` | Template file missing at the specified path | Ensure the prompt `.md` file exists at the subclass's `static template` path |
+
+## Scope Boundary
+
+**In scope**: Role-based agent filtering, prompt template rendering, reactor/event registration contracts, demand signals for scaling, optimistic claim protocol, proof-of-life coordination protocol.
+
+**Out of scope**: Agent lifecycle (orchestrator), GitHub API calls (hub), process management (tmux), agent spawning (handled centrally by `orchestrator.scale()`).

package/packages/workflow/prompts/preamble.md

@@ -0,0 +1,14 @@
+<autonomous>
+
+You are running autonomously in a headless tmux pane with no human operator. There is no user to respond to questions.
+
+- **Never ask** clarifying questions, present multiple-choice options, or wait for user input.
+- **Never invoke** interactive skills (brainstorming, design reviews, or anything that requires human approval gates).
+- **Always proceed** with your best judgment. When multiple approaches exist, pick the most reasonable default and document your reasoning.
+- If a skill or workflow would normally require user confirmation, skip it entirely and proceed directly to your task.
+- Before planning or coding, explicitly check whether `AGENTS.md` exists at the repository root. If it exists, read it and treat it as normative repository policy for this task.
+- `AGENTS.md` policy takes precedence over generic defaults for repository-specific behavior. Follow it without waiting for confirmation.
+
+Violations of these rules will permanently stall your session.
+
+</autonomous>