loreli 0.0.0 → 2.0.0

package/packages/workflow/src/proof-of-life.js

@@ -0,0 +1,74 @@
+/**
+ * Proof-of-life reactor handler factory.
+ *
+ * Creates a handler that scans open issues and PRs for proof-of-life
+ * requests targeting agents in the local agents map, runs health
+ * checks, and posts themed responses.
+ *
+ * Registered once at start and runs on every reactor tick.
+ *
+ * @module loreli/workflow/proof-of-life
+ */
+import { has, parse, mark } from 'loreli/marker';
+import { logger } from 'loreli/log';
+
+const log = logger('proof-of-life');
+
+/**
+ * Create the proof-of-life reactor handler.
+ *
+ * @param {object} orchestrator - Orchestrator with agents map and health().
+ * @param {object} hub - GitHub hub for reading/posting comments.
+ * @returns {function(string): Promise<void>} Reactor handler receiving repo.
+ */
+export function responder(orchestrator, hub) {
+  return async function proofOfLife(repo) {
+    const [issues, prs] = await Promise.all([
+      hub.issues(repo, { state: 'open', labels: ['loreli'] }).catch(function noop() { return []; }),
+      hub.pulls(repo, { state: 'open' }).catch(function noop() { return []; })
+    ]);
+
+    const items = [
+      ...issues.map(function toItem(i) { return { number: i.number }; }),
+      ...prs.map(function toItem(p) { return { number: p.number }; })
+    ];
+
+    for (const item of items) {
+      const comments = await hub.comments(repo, item.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) continue;
+
+        const agent = orchestrator.agents.get(data.agent);
+        if (!agent) continue;
+
+        const responded = comments.some(function alreadyAlive(r) {
+          if (!has(r.body, 'alive')) return false;
+          const alive = parse(r.body, 'alive');
+          return alive?.agent === data.agent && Number(alive.ts) > Number(data.ts);
+        });
+        if (responded) continue;
+
+        const verdict = await orchestrator.health(data.agent);
+        const aliveMarker = mark('alive', {
+          agent: agent.identity.name,
+          ts: String(Date.now()),
+          status: verdict.status
+        });
+        const visible = `**${agent.identity.name}** is **${verdict.status}** — ${verdict.details}`;
+        const body = `${visible}\n\n${aliveMarker}`;
+
+        try {
+          const scoped = hub.as(agent.identity, agent.role);
+          await scoped.comment(repo, item.number, body);
+          log.info(`proof-of-life: responded for ${data.agent} on #${item.number} — ${verdict.status}`);
+        } catch (err) {
+          log.warn(`proof-of-life: failed to respond for ${data.agent} on #${item.number}: ${err.message}`);
+        }
+      }
+    }
+  };
+}

package/packages/workspace/README.md

@@ -0,0 +1,143 @@
+# loreli/workspace
+
+Local workspace lifecycle for Loreli agents.
+
+This package prepares agent directories, scaffolds local MCP configs and safety hooks, manages clone-based workspaces, and provides git helpers used by action/review/context flows.
+
+## API Reference
+
+### Constants
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ENTRY` | `{ command: string, args: string[] }` | Loreli MCP entry used in JSON-based configs. |
+| `MCP_JSON` | `string` | Default JSON config body for `.mcp.json` and `.cursor/mcp.json`. |
+| `CODEX_TOML` | `string` | Default TOML config body for `.codex/config.toml`. |
+
+### Config Generators
+
+#### `codexToml(context?)` → `string`
+
+Generate Codex TOML config content with `env_vars = ["GITHUB_TOKEN"]` forwarding and optional agent context env keys.
+
+#### `mcpJson(context?, opts?)` → `string`
+
+Generate JSON MCP config content with optional agent context, token reference (`tokenRef`), and env file path (`envFile`). Cursor scaffolding keeps both interpolation and envFile fallback for token propagation.
+
+### Security/Hook Generators
+
+#### `denyScript(denied)` → `string`
+
+Generate the shared deny hook script used by Claude/Cursor shell hooks.
+
+#### `protectScript()` → `string`
+
+Generate the file-write protection hook script for protected paths.
+
+#### `claudeHooks()` → `string`
+
+Generate `.claude/settings.local.json` hook config content.
+
+#### `cursorMatcher(denied)` → `string`
+
+Build Cursor `beforeShellExecution` matcher regex from denied commands.
+
+#### `cursorHooks(denied)` → `string`
+
+Generate `.cursor/hooks.json` hook config content.
+
+### Workspace Lifecycle
+
+#### `pathFor(name, root?)` → `string`
+
+Resolve deterministic workspace path: `<root>/loreli-<name>`.
+
+- Default `root`: `~/.loreli/workspaces` (or `LORELI_HOME/workspaces`).
+
+#### `prepare(cwd, context?, descriptors?)` → `Promise<void>`
+
+Prepare a workspace directory by writing MCP configs, safety files, deny/protect scripts, and merged hook entries.
+
+When `context` is provided, session/agent/repo env values are embedded into generated configs. When `descriptors` are provided (from backend scaffolding), descriptor-driven config/hook/file generation is used.
+
+This example demonstrates preparing a workspace with context and denied commands. This matters because agents must boot with MCP connectivity and command guardrails. Expected result: config files and hook scripts are created/updated in place.
+
+```js
+import { prepare } from 'loreli/workspace';
+
+await prepare('/tmp/loreli-optimus-0', {
+  session: 's1',
+  agent: 'optimus-0',
+  repo: 'owner/repo',
+  denied: ['gh', 'curl']
+});
+```
+
+#### `mirror(url, opts?)` → `Promise<string>`
+
+Ensure a local bare mirror exists under `<home>/repos`. Fetches if mirror exists, clones if not.
+
+#### `create(repo, branch, name, root?, context?, descriptors?)` → `Promise<string>`
+
+Create or reuse an agent workspace. Current behavior is clone-based workspace creation (not git worktree-based execution) with branch initialization, optional remote auth setup, and preparation/scaffolding.
+
+This example demonstrates provisioning an agent workspace for branch work. This matters because action agents need an isolated git directory with local `.git` state. Expected result: returned `cwd` contains a prepared clone with agent branch checked out.
+
+```js
+import { create } from 'loreli/workspace';
+
+const cwd = await create('/path/to/bare-or-local-repo', 'main', 'optimus-0');
+```
+
+#### `clean(name, root?)` → `Promise<void>`
+
+Delete an agent workspace directory (best effort). Attempts worktree remove first, then force-removes directory.
+
+#### `prune(sessionId, root?)` → `Promise<string[]>`
+
+Remove stale `loreli-*` workspaces not owned by `sessionId`.
+
+#### `reset(cwd, name, issue?, base?, opts?)` → `Promise<void>`
+
+Reset workspace to a clean issue branch from remote `base` (default `main`).
+
+When `opts.context` and `opts.descriptors` are provided, `reset()` re-applies
+workspace scaffolding after the branch switch so MCP CLI config files remain
+available for shell-based Loreli tool commands.
+
+#### `checkout(cwd, branch, base?, opts?)` → `Promise<void>`
+
+Fetch and check out a remote branch in an existing workspace, also syncing local base ref.
+
+When `opts.context` and `opts.descriptors` are provided, `checkout()` re-applies
+workspace scaffolding after branch switch for the same reason as `reset()`.
+
+#### `hasChanges(cwd)` → `Promise<boolean>`
+
+Return whether workspace has uncommitted/untracked changes (`git status --porcelain`).
+
+#### `commitAndPush(cwd, message)` → `Promise<{ pushed: boolean, sha: string }>`
+
+Stage, commit, and attempt push. Returns commit SHA and whether push succeeded.
+
+### Git Context Helpers
+
+#### `blame(cwd, file, line)` → `Promise<{ sha: string, author: string, date: string, summary: string }>`
+
+Run porcelain git blame for a single line and return parsed metadata.
+
+#### `gitlog(cwd, file, opts?)` → `Promise<Array<{ sha: string, date: string, message: string }>>`
+
+Run git log for a file and return parsed commit entries.
+
+## Scope Boundary
+
+In scope:
+- local workspace preparation and cleanup
+- local MCP config/hook generation
+- clone/branch/reset/checkout helper operations
+- git context lookup helpers
+
+Out of scope:
+- remote GitHub scaffolding and repository writes (`loreli/hub`)
+- agent process lifecycle (`loreli/agent`, `loreli/orchestrator`)