agent-lyceum 0.17.1 → 0.17.3

package/README.md

@@ -4,13 +4,25 @@
 
 **English** | [繁體中文](README.zh-TW.md)
 
-Run a **team of agents** (Claude Code and/or Codex) on your repo. They talk through file mailboxes, and each has its own persona (`AGENT.md`) and long-term memory. An agent can only write its own memory and outbox, never other agents' context or its own persona.
+Give a task to a **team of agents** (Claude Code and/or Codex) instead of one overloaded session. A lead splits the work, specialists such as a frontend dev, a reviewer or a PM do their part in your repo, and the run ends when the lead says it is done.
+
+## Why
+
+- **Roles that stay in role.** Each agent has its own persona (`AGENT.md`) and long-term memory, so a reviewer keeps reviewing instead of drifting into writing code.
+- **Agents can't rewrite the rules.** An agent can only write its own memory and outbox. It can't touch other agents' context or its own persona, and this is enforced by the OS sandbox where possible, not just by a prompt. See [Write scope](docs/write-scope.md).
+- **Mix runtimes.** Claude Code and Codex agents work in the same team, and each can be limited to the paths it owns.
+- **Nothing hidden.** Agents talk through plain-file mailboxes, so every message, decision and memory is a file you can read, grep and diff. The dispatcher never merges for you.
+
+**Not a fit** for small, one-shot edits: a single Claude Code or Codex session is faster and cheaper. Use a team when the task is big enough to split, review or run in parallel.
 
 ## Quick start
 
 Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (logged in). macOS and Linux (Linux needs `bwrap` for OS sandboxing); Windows only gets warnings.
 
 ```bash
+npx agent-lyceum demo                       # 3 agents fix a failing test in a throwaway sandbox (real calls)
+
+# on your own repo:
 npx agent-lyceum init                       # create the home + global agent library
 npx agent-lyceum project add web --dir ~/code/web-app
 npx agent-lyceum doctor --project web       # check config, show enforcement levels
@@ -41,6 +53,7 @@ Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyce
 | `resume` | Continue an interrupted run, or reopen a finished one with a follow-up. [details](docs/commands.md#resume) |
 | `clear` | Delete a run, or remove a stale lock. [details](docs/commands.md#clear) |
 | `call <agent>` | Ask one global agent on its own, outside any project. [details](docs/commands.md#call) |
+| `demo` | Try a 3-agent team on a throwaway sample repo. [details](docs/commands.md#demo) |
 | `tidy` | Have agents tidy their own memory (archives, never deletes). [details](docs/commands.md#tidy) |
 
 `agent-lyceum <command> --help` prints the full options. Ctrl-C cancels cleanly; [exit codes](docs/commands.md#exit-codes) tell scripts how a run ended.

package/README.zh-TW.md

@@ -4,13 +4,25 @@
 
 [English](README.md) | **繁體中文**
 
-在你的 repo 上執行一個由多個 **agent**（Claude Code 和／或 Codex）組成的團隊。agent 之間透過檔案信箱溝通，各自有人設（`AGENT.md`）與長期記憶。agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設。
+把任務交給一個 **agent 團隊**（Claude Code 和／或 Codex），而不是塞給單一個負荷過重的 session。lead 拆分工作，前端、reviewer、PM 等專長角色在你的 repo 裡各做各的，lead 回報 done 即結束。
+
+## 為什麼用它
+
+- **角色不會跑掉。** 每個 agent 有自己的人設（`AGENT.md`）與長期記憶，reviewer 會一直做 review，不會漸漸變成在寫程式。
+- **agent 改不了規則。** agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設；能做到的地方由 OS 沙箱強制，而不只靠 prompt。見 [Write scope](docs/write-scope.zh-TW.md)。
+- **混用 runtime。** Claude Code 與 Codex agent 可在同一個團隊，並各自限制可寫的路徑。
+- **沒有黑箱。** agent 透過純檔案信箱溝通，每則訊息、決策與記憶都是你能讀、能 grep、能 diff 的檔案；dispatcher 不會替你 merge。
+
+**不適合**小而單次的修改：單一 Claude Code 或 Codex session 更快更省。任務大到值得拆分、review 或平行執行時，再用團隊。
 
 ## 快速開始
 
 需求：Node 20+，以及 `PATH` 中有 `claude` 和／或 `codex`（已登入）。支援 macOS 與 Linux（Linux 需要 `bwrap` 才有 OS 沙箱）；Windows 只會顯示警告。
 
 ```bash
+npx agent-lyceum demo                       # 3 個 agent 在拋棄式沙箱裡修好一個失敗的測試（真實呼叫）
+
+# 用在你自己的 repo：
 npx agent-lyceum init                       # 建立 home 與全域 agent 庫
 npx agent-lyceum project add web --dir ~/code/web-app
 npx agent-lyceum doctor --project web       # 檢查設定並顯示各項防護等級
@@ -41,6 +53,7 @@ npx agent-lyceum status
 | `resume` | 繼續中斷的 run，或用追加需求重開已完成的 run。 [詳細](docs/commands.zh-TW.md#resume) |
 | `clear` | 刪除 run，或移除殘留的鎖。 [詳細](docs/commands.zh-TW.md#clear) |
 | `call <agent>` | 在任何專案之外單獨呼叫一個全域 agent。 [詳細](docs/commands.zh-TW.md#call) |
+| `demo` | 在拋棄式範例 repo 上試跑 3 個 agent 的團隊。 [詳細](docs/commands.zh-TW.md#demo) |
 | `tidy` | 讓 agent 整理自己的記憶（只封存，不刪除）。 [詳細](docs/commands.zh-TW.md#tidy) |
 
 `agent-lyceum <指令> --help` 會印出完整選項。Ctrl-C 可乾淨取消；腳本可依[結束碼](docs/commands.zh-TW.md#退出碼)判斷 run 的結果。

package/dist/cli.js

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
+import { spawnSync } from "node:child_process";
 import { Command } from "commander";
 import { ConfigError, findProjectForCwd, flattenResolved, listProjects, loadGlobal, resolveProject, resolveProjectWithSources } from "./config.js";
 import { openInEditor, prepareAnswers } from "./ask-answer.js";
@@ -12,7 +13,7 @@ import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
 import { acquireProjectLock, forceUnlock, inspectRunLock, listRunLocks, listUnreadableRunLocks, LOCK_FILE, lockHolderAlive } from "./project-lock.js";
 import { loadRunState, newRunId, outcomeOf, resolveRun, roundLimit, roundsLabel, runLabel, slugify, uniqueName } from "./run-store.js";
 import { failureGuide } from "./run-outcome.js";
-import { exitCodeForOutcome } from "./schema.js";
+import { exitCodeForOutcome, RUNTIMES } from "./schema.js";
 import { absPath, assertName, NAME_RE, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
 import { buildStatusReport, buildTaskListReport, formatMonitor, formatRunDetail, formatStatusWithLog, formatTaskList, latestUnfinishedRun, listRuns, reopenCandidates, runIsAlive } from "./status.js";
@@ -21,6 +22,7 @@ import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
 import { onlyAgent, soloProject } from "./solo.js";
+import { DEMO_PROJECT, DEMO_TASK, defaultDemoDir, detectRuntime, prepareDemo } from "./demo.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -772,11 +774,63 @@ program
         fail(e instanceof ConfigError ? e.message : e.message);
     }
 });
+program
+    .command("demo")
+    .summary("Try a 3-agent team on a tiny sample repo (real agents, a few minutes)")
+    .description("Build a throwaway sandbox (a tiny git repo with one failing test, plus its own agent-lyceum home), then run a lead, a frontend member and a QA member on it until `npm test` passes.\n\nIt uses real `claude` / `codex` calls, so it spends a little of your quota. Nothing outside the sandbox directory is touched; your own home and repos are not used.")
+    .option("--dir <path>", "the sandbox directory, must be empty or new (default: a new folder in the system temp dir)")
+    .option("--runtime <runtime>", `${RUNTIMES.join(" | ")} (default: whichever CLI is on your PATH)`)
+    .option("--setup-only", "build the sandbox and print the commands, but run no agents")
+    .option("-y, --yes", "do not ask before running real agents")
+    .action(async (opts) => {
+    try {
+        let runtime = opts.runtime;
+        if (runtime && !RUNTIMES.includes(runtime))
+            fail(`Unknown runtime "${runtime}". Use one of: ${RUNTIMES.join(", ")}.`);
+        runtime ??= detectRuntime();
+        if (!runtime) {
+            if (!opts.setupOnly)
+                fail("Neither `claude` nor `codex` was found on your PATH (and logged in). Install one, or use --setup-only to just look at the sandbox.");
+            runtime = "claude-code";
+        }
+        if (!opts.setupOnly && !opts.yes && interactive()) {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const ans = (await rl.question(`This runs a 3-agent team with real ${runtime} calls on a sample repo (a few minutes, a small amount of quota). Continue? [Y/n] `)).trim().toLowerCase();
+            rl.close();
+            if (ans === "n" || ans === "no")
+                fail("Aborted.");
+        }
+        const demo = prepareDemo(opts.dir ?? defaultDemoDir(), runtime);
+        const h = demo.home;
+        console.log(`Sandbox: ${demo.dir}  (runtime: ${runtime})\nRepo with one failing test: ${demo.repo}\n`);
+        const next = [
+            `agent-lyceum --home ${h} status -p ${DEMO_PROJECT}              # agents, mail, runs`,
+            `git -C ${demo.repo} log --oneline --stat                        # what the team changed`,
+            `rm -rf ${demo.dir}                                              # clean up when done`,
+        ];
+        if (opts.setupOnly) {
+            fs.writeFileSync(path.join(demo.dir, "task.md"), `${DEMO_TASK}\n`);
+            console.log(`Run the team yourself:\n  agent-lyceum --home ${h} run -p ${DEMO_PROJECT} --task-file ${path.join(demo.dir, "task.md")}\n\nThen:\n${next.map((l) => `  ${l}`).join("\n")}`);
+            return;
+        }
+        console.log(`Task for the lead:\n${DEMO_TASK.split("\n").map((l) => `  | ${l}`).join("\n")}\n`);
+        // The real `run`, in a child: the demo shows exactly what a normal run does (progress, Ctrl-C, exit codes).
+        const r = spawnSync(process.execPath, [...process.execArgv, process.argv[1], "--home", h, "run", DEMO_TASK, "-p", DEMO_PROJECT, "--name", "demo-slugify"], { stdio: "inherit", cwd: demo.repo });
+        const code = r.status ?? 1;
+        console.log(code === 0 ? "\nDone. See what happened:" : `\nThe run ended with exit code ${code} (see docs/commands.md#exit-codes). Look around:`);
+        console.log(next.map((l) => `  ${l}`).join("\n"));
+        process.exit(code);
+    }
+    catch (e) {
+        fail(e.message);
+    }
+});
 // `--help` lists the commands in three layers.
 const HELP_LAYERS = {
     "Project:": ["init", "project"],
     "Diagnose:": ["doctor", "status"],
     "Run:": ["run", "resume", "clear", "call", "tidy"],
+    "Try it:": ["demo"],
 };
 for (const [heading, names] of Object.entries(HELP_LAYERS))
     for (const c of program.commands)

package/dist/demo.d.ts

@@ -0,0 +1,13 @@
+import type { Runtime } from "./schema.js";
+export declare const DEMO_PROJECT = "demo";
+export declare const DEMO_TASK = "The sample repo has a failing test: `npm test` fails because slugify() in src/slug.js is not implemented.\n\nImplement slugify(text) so that it lowercases the text, turns every run of non-alphanumeric characters into a single \"-\", and trims leading and trailing \"-\". Do not edit the tests.\n\nPlan: the lead hands the implementation to fe-member, then asks qa-member to run `npm test` and review the change. Finish with `done` only after qa-member's verdict is pass.";
+/** Which runtime CLI is on the PATH and answers `--version`; claude-code wins when both are. */
+export declare function detectRuntime(): Runtime | undefined;
+export interface DemoSetup {
+    dir: string;
+    home: string;
+    repo: string;
+}
+/** A throwaway sandbox: a tiny git repo with one failing test, plus its own agent-lyceum home with a registered project. Touches nothing outside `dir`. */
+export declare function prepareDemo(dir: string, runtime: Runtime): DemoSetup;
+export declare function defaultDemoDir(): string;

package/dist/demo.js

@@ -0,0 +1,91 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { projectPaths } from "./paths.js";
+import { addProject, initHome } from "./scaffold.js";
+export const DEMO_PROJECT = "demo";
+export const DEMO_TASK = `The sample repo has a failing test: \`npm test\` fails because slugify() in src/slug.js is not implemented.
+
+Implement slugify(text) so that it lowercases the text, turns every run of non-alphanumeric characters into a single "-", and trims leading and trailing "-". Do not edit the tests.
+
+Plan: the lead hands the implementation to fe-member, then asks qa-member to run \`npm test\` and review the change. Finish with \`done\` only after qa-member's verdict is pass.`;
+const FILES = {
+    "package.json": `{
+  "name": "lyceum-demo",
+  "private": true,
+  "type": "module",
+  "scripts": { "test": "node --test" }
+}
+`,
+    "src/slug.js": `// Turn a title into a URL slug: "Hello, World!" -> "hello-world".
+export function slugify(text) {
+  throw new Error("not implemented");
+}
+`,
+    "test/slug.test.js": `import assert from "node:assert/strict";
+import { test } from "node:test";
+import { slugify } from "../src/slug.js";
+
+test("lowercases and joins words with a dash", () => {
+  assert.equal(slugify("Hello World"), "hello-world");
+});
+
+test("collapses punctuation and repeated separators", () => {
+  assert.equal(slugify("Hello,   World!!"), "hello-world");
+});
+
+test("trims leading and trailing separators", () => {
+  assert.equal(slugify("  --Agent Lyceum--  "), "agent-lyceum");
+});
+
+test("keeps digits", () => {
+  assert.equal(slugify("Top 10 tips"), "top-10-tips");
+});
+`,
+};
+/** Which runtime CLI is on the PATH and answers `--version`; claude-code wins when both are. */
+export function detectRuntime() {
+    for (const [runtime, bin] of [["claude-code", "claude"], ["codex", "codex"]]) {
+        const r = spawnSync(bin, ["--version"], { stdio: "ignore" });
+        if (r.status === 0)
+            return runtime;
+    }
+    return undefined;
+}
+/** A throwaway sandbox: a tiny git repo with one failing test, plus its own agent-lyceum home with a registered project. Touches nothing outside `dir`. */
+export function prepareDemo(dir, runtime) {
+    const root = path.resolve(dir);
+    if (fs.existsSync(root) && fs.readdirSync(root).length)
+        throw new Error(`${root} is not empty. Choose another --dir (or remove it).`);
+    const home = path.join(root, "home");
+    const repo = path.join(root, "repo");
+    fs.mkdirSync(repo, { recursive: true });
+    for (const [file, text] of Object.entries(FILES)) {
+        fs.mkdirSync(path.dirname(path.join(repo, file)), { recursive: true });
+        fs.writeFileSync(path.join(repo, file), text);
+    }
+    const git = (...args) => execFileSync("git", ["-C", repo, "-c", "user.name=agent-lyceum demo", "-c", "user.email=demo@example.com", ...args], { stdio: "ignore" });
+    try {
+        git("init", "-q", "-b", "main");
+        git("add", "-A");
+        git("commit", "-q", "-m", "demo: slugify is not implemented yet");
+    }
+    catch {
+        throw new Error("The demo needs `git` on your PATH.");
+    }
+    initHome(home);
+    addProject(home, DEMO_PROJECT, repo);
+    const cfg = projectPaths(home, DEMO_PROJECT).config;
+    let yaml = fs.readFileSync(cfg, "utf8");
+    yaml = yaml.replace("max_rounds: 0 ", "max_rounds: 20");
+    // One runtime for the whole team, and the roles scoped to the sample repo.
+    for (const agent of ["lead", "fe-member", "qa-member"])
+        yaml = yaml.replace(`  ${agent}:\n`, `  ${agent}:\n    runtime: ${runtime}\n`);
+    yaml = yaml.replace('# owns: ["src/web/**"]', 'owns: ["src/**"]').replace('# owns: ["tests/**"]', 'owns: ["test/**"]');
+    fs.writeFileSync(cfg, yaml);
+    return { dir: root, home, repo };
+}
+export function defaultDemoDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "agent-lyceum-demo-"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",