agent-lyceum 0.5.0 → 0.7.0

package/README.md

@@ -28,15 +28,30 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 | `project add <name> --dir <repo>` | Register a project. [details](docs/commands.md#project-add) |
 | `project list` / `project remove <name> [--purge]` | List or unregister projects. [details](docs/commands.md#project-list-and-remove) |
 | `validate [-p name] [--task-file f]` | Validate the merged config and show each agent's enforcement level. [details](docs/commands.md#validate) |
-| `run ["task"] [--task-file f] [-p name]` | Give the task to the lead and run until done. [details](docs/commands.md#run) |
+| `run ["task"] [--task-file f] [--agent a] [-p name]` | Give the task to the lead and run until done; with `--agent`, to one member alone. [details](docs/commands.md#run) |
+| `call <agent> ["task"] [--task-file f] [--dir d]` | Call one global agent on its own, outside any project; prints its answer. [details](docs/commands.md#call) |
 | `resume [run-id] [-p name]` | Continue an interrupted or failed run. [details](docs/commands.md#resume) |
+| `answer <run-id> [--no-edit] [-p name]` | Answer the questions a waiting run asked, then continue it. [details](docs/commands.md#answer) |
 | `status [-p name] [--monitor]` | Show agents, mail, the current wake-up and past runs (`--json`, `--monitor`). [details](docs/commands.md#status) |
 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | Delete a run with its task memory and worktrees. [details](docs/commands.md#clear) |
 | `config show --resolved [-p name] [--json]` | Print every effective setting and where it came from. [details](docs/commands.md#config-show) |
 | `doctor [-p name] [--json]` | Check config, git, the lock and runtime CLIs without running agents. [details](docs/commands.md#doctor) |
+| `memory tidy [-p name] [--agent a] [--layer project\|global] [--dry-run]` | Have agents tidy their own memory (manual only; archives, never deletes). [details](docs/commands.md#memory-tidy) |
+| `memory restore <timestamp> -p name --agent a` | Undo a tidy: move its archived files back. [details](docs/commands.md#memory-restore) |
 | `unlock [-p name] --force` | Remove the project lock a crashed run left behind. [details](docs/commands.md#unlock) |
 
-Ctrl-C cancels a run cleanly and it can be continued with `resume` ([Stopping a run](docs/commands.md#stopping-a-run)). `run` and `resume` exit `0` only when the lead reported `completed`, `2` for partial or blocked, `1` for failed, `130` for cancelled ([Exit codes](docs/commands.md#exit-codes)). Without `-p`, the project is inferred from the current directory ([Choosing the project](docs/commands.md#choosing-the-project)).
+Ctrl-C cancels a run cleanly and it can be continued with `resume` ([Stopping a run](docs/commands.md#stopping-a-run)). `run` and `resume` exit `0` only when the lead reported `completed`, `2` for partial or blocked, `1` for failed, `3` while waiting for your answers, `130` for cancelled ([Exit codes](docs/commands.md#exit-codes)). Without `-p`, the project is inferred from the current directory ([Choosing the project](docs/commands.md#choosing-the-project)).
+
+## Running one agent on its own
+
+Two ways to give a task to a single agent instead of the whole team. The agent works alone: it cannot mail teammates, ask you questions or edit any `AGENT.md`.
+
+```bash
+npx agent-lyceum run "tidy the form" --agent fe-member -p web   # a member of the project, as an ordinary run
+npx agent-lyceum call pm "is this ready to build?" --dir ~/code/web-app   # a global agent, outside any project
+```
+
+`run --agent` has a run id and the project lock, shows in `status`, and can be resumed; the agent ends the run with its own `done` mail. `call` needs no project at all: the agent comes from `team.yaml`, works in `--dir` (default: the current directory, which must not be inside or above the agent-lyceum home), prints only its final answer on stdout, and keeps `task.md`, `log/` and `result.md` in `<home>/calls/<call-id>/`. Details: [run](docs/commands.md#run) and [call](docs/commands.md#call).
 
 ## Monitor mod (Claude Code)
 
@@ -53,7 +68,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 **Use it.**
 - **Status line:** always on once loaded (`team 讀取中…` until the first poll, `team 無法取得狀態：…` when the CLI cannot run); shows the run state, round `n/max`, output tokens, the current step and unread mail. With several projects it shows one overview line (`team 1/3 running · a ... | b ...`).
 - **Toasts:** a message pops up when a run finishes, is interrupted, or an agent's wake fails (prefixed `[project]` when several are watched). Nothing to do.
-- **`/status-monitor`:** type it to open (or, if already open, close) the pane. It is off at session start unless `autoOpen` is set. In the **fullscreen layout** (`"tui": "fullscreen"` in `~/.claude/settings.json`, restart the session to apply; `/tui fullscreen` does the same) from 110 terminal columns it docks on the right at half the terminal width, and tabs and **關閉** (Close) can be clicked. Otherwise it shows above the prompt; the layout is fixed when the session starts, so a session started on the main screen stays that way. Keyboard (works in both): `x` closes, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It shows, per project: the run id and state, task, progress and checklist, the agents working now and the queued mail, blocked integrations, notes and result summary, output tokens per runtime, per-agent wake statistics, the last 8 wakes. Each task (a project's current run and its last 3 past runs) is a tab. It refreshes with the polling interval while open.
+- **`/status-monitor`:** type it to open (or, if already open, close) the pane. It is off at session start unless `autoOpen` is set. In the **fullscreen layout** (`"tui": "fullscreen"` in `~/.claude/settings.json`, restart the session to apply; `/tui fullscreen` does the same) from 110 terminal columns it docks on the right at half the terminal width, and tabs and **關閉** (Close) can be clicked. Otherwise it shows above the prompt; the layout is fixed when the session starts, so a session started on the main screen stays that way. Keyboard (works in both): `x` closes, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It shows, per project: the run id and state, task, progress and checklist, the agents working now and the queued mail, blocked integrations, notes and result summary, output tokens per runtime, per-agent wake statistics, the last 8 wakes. Each running task is a tab, newest first; finished and interrupted runs are not listed. It refreshes with the polling interval while open.
 
 **Configure it.** In `~/.claude/settings.json` under `pluginConfigs."status-monitor@inline"` (`options`):
 
@@ -72,6 +87,7 @@ Changes take effect on the next session start. If the pane shows `無法取得
 ~/agent-lyceum-config/
 ├── team.yaml                         # global agent library
 ├── agents/<agent>/{AGENT.md, memory/}  # global persona + cross-project memory
+├── calls/<call-id>/{task.md, log/, result.md}   # one folder per `call` (outside any project), plus .lock-<agent>
 └── projects/<project>/
     ├── project.yaml                  # team, repo dir, overrides
     ├── agents/<agent>/{AGENT.md?, memory/}   # project-level persona (optional) + project memory
@@ -93,7 +109,7 @@ agents:
   qa-member: { can_message: [lead], owns: ["tests/**"] }
 ```
 
-Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `owns` (repo globs).
+Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `can_ask_user` (may send `type: ask` mail to you and pause the run for an answer; default only the lead), `owns` (repo globs).
 
 Rules checked by `validate`: ≥ 2 agents (the lead and one member; the template has three), the lead is a listed agent, every agent has a runtime (explicit or inferred from `model`) and an existing `AGENT.md`, `effort` is valid for the agent's runtime (warning if `runtime` contradicts a recognizable `model`), `can_message` targets exist, memory dirs don't overlap, and with `max_parallel > 1` every non-lead agent needs non-overlapping `owns` and the repo must be a git repository.
 

package/README.zh-TW.md

@@ -28,15 +28,30 @@ npx agent-lyceum status
 | `project add <name> --dir <repo>` | 註冊專案。 [詳細](docs/commands.zh-TW.md#project-add) |
 | `project list` / `project remove <name> [--purge]` | 列出或取消註冊專案。 [詳細](docs/commands.zh-TW.md#project-list-and-remove) |
 | `validate [-p name] [--task-file f]` | 驗證設定並顯示每個 agent 的防護等級。 [詳細](docs/commands.zh-TW.md#validate) |
-| `run ["task"] [--task-file f] [-p name]` | 把任務交給 lead 並執行到結束。 [詳細](docs/commands.zh-TW.md#run) |
+| `run ["task"] [--task-file f] [--agent a] [-p name]` | 把任務交給 lead 並執行到結束；加 `--agent` 則只交給某個成員單獨做。 [詳細](docs/commands.zh-TW.md#run) |
+| `call <agent> ["task"] [--task-file f] [--dir d]` | 單獨呼叫一個 global agent（不需專案），印出它的回答。 [詳細](docs/commands.zh-TW.md#call) |
 | `resume [run-id] [-p name]` | 接續被中斷或失敗的 run。 [詳細](docs/commands.zh-TW.md#resume) |
+| `answer <run-id> [--no-edit] [-p name]` | 回答等待中的 run 提出的問題，並接續執行。 [詳細](docs/commands.zh-TW.md#answer) |
 | `status [-p name] [--monitor]` | 顯示 agent、信件、目前執行與歷次 run（支援 `--json`、`--monitor`）。 [詳細](docs/commands.zh-TW.md#status) |
 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | 刪除 run 與其任務記憶、worktree。 [詳細](docs/commands.zh-TW.md#clear) |
 | `config show --resolved [-p name] [--json]` | 印出每項生效設定與其來源。 [詳細](docs/commands.zh-TW.md#config-show) |
 | `doctor [-p name] [--json]` | 不執行 agent，檢查設定、git、鎖與 runtime CLI。 [詳細](docs/commands.zh-TW.md#doctor) |
+| `memory tidy [-p name] [--agent a] [--layer project\|global] [--dry-run]` | 讓 agent 整理自己的記憶（只能手動觸發；封存而非刪除）。 [詳細](docs/commands.zh-TW.md#memory-tidy) |
+| `memory restore <時間戳> -p name --agent a` | 還原一次整理：把封存的檔案搬回。 [詳細](docs/commands.zh-TW.md#memory-restore) |
 | `unlock [-p name] --force` | 移除當機 run 留下的專案鎖。 [詳細](docs/commands.zh-TW.md#unlock) |
 
-Ctrl-C 會乾淨地取消 run，之後可用 `resume` 接續（[中止 run](docs/commands.zh-TW.md#中止-run)）。`run`／`resume` 只有在 lead 回報 `completed` 時才 exit `0`；`partial`／`blocked` 為 `2`，`failed` 為 `1`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
+Ctrl-C 會乾淨地取消 run，之後可用 `resume` 接續（[中止 run](docs/commands.zh-TW.md#中止-run)）。`run`／`resume` 只有在 lead 回報 `completed` 時才 exit `0`；`partial`／`blocked` 為 `2`，`failed` 為 `1`，等待你回答時為 `3`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
+
+## 單獨呼叫一個 agent
+
+有兩種方式把任務只交給單一 agent，而不是整個團隊。該 agent 獨自工作：不能寄信給隊友、不能向你提問、不能修改任何 `AGENT.md`。
+
+```bash
+npx agent-lyceum run "整理表單" --agent fe-member -p web   # 專案裡的一個成員，當作一般 run
+npx agent-lyceum call pm "這個需求可以開工了嗎？" --dir ~/code/web-app   # global agent，不屬於任何專案
+```
+
+`run --agent` 有 run id 與專案鎖、會出現在 `status`、可以 `resume`；agent 用自己寄出的 `done` 結束 run。`call` 完全不需要專案：agent 取自 `team.yaml`，在 `--dir`（預設是目前目錄，且不可位於 agent-lyceum home 之內或之上）工作，stdout 只印它的最終回答，並在 `<home>/calls/<call-id>/` 留下 `task.md`、`log/` 與 `result.md`。細節見 [run](docs/commands.zh-TW.md#run) 與 [call](docs/commands.zh-TW.md#call)。
 
 ## 監控 mod（Claude Code）
 
@@ -53,7 +68,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 **操作。**
 - **狀態列：** 載入後常駐（第一次輪詢前顯示 `team 讀取中…`，CLI 跑不起來時顯示 `team 無法取得狀態：…`），顯示執行狀態、輪數 `n/max`、output tokens、目前步驟與未讀信件。監看多個專案時顯示一行總覽（`team 1/3 執行中 · a ... | b ...`）。
 - **通知：** 執行完成、被中斷或某個 agent 喚醒失敗時會跳出訊息（監看多個專案時前面加 `[專案名]`），不需要任何操作。
-- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。每個專案顯示：執行 id 與狀態、任務、進度與清單、正在工作的 agent 與排隊中的信件、受阻的整合、備註與結果摘要、各 runtime 的 output tokens、各 agent 的喚醒統計、最近 8 次喚醒。每個任務（專案目前的執行與最近 3 次過往執行）是一個分頁。面板開著時會依輪詢間隔自動更新。
+- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。每個專案顯示：執行 id 與狀態、任務、進度與清單、正在工作的 agent 與排隊中的信件、受阻的整合、備註與結果摘要、各 runtime 的 output tokens、各 agent 的喚醒統計、最近 8 次喚醒。每個執行中的任務是一個分頁，最新的排最前面；已結束或已中斷的不列出。面板開著時會依輪詢間隔自動更新。
 
 **設定。** 在 `~/.claude/settings.json` 的 `pluginConfigs."status-monitor@inline"`（`options`）：
 
@@ -72,6 +87,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 ~/agent-lyceum-config/
 ├── team.yaml                         # 全域 agent 庫
 ├── agents/<agent>/{AGENT.md, memory/}  # 全域人設 + 跨專案記憶
+├── calls/<call-id>/{task.md, log/, result.md}   # 每次 `call`（不屬於任何專案）一個資料夾，另有 .lock-<agent>
 └── projects/<project>/
     ├── project.yaml                  # 團隊、repo 路徑、覆寫設定
     ├── agents/<agent>/{AGENT.md?, memory/}   # 專案層人設（選用）+ 專案記憶
@@ -94,7 +110,7 @@ agents:
   qa-member: { can_message: [lead], owns: ["tests/**"] }
 ```
 
-Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`owns`（repo glob）。
+Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`can_ask_user`（可用 `type: ask` 信件向你提問並暫停 run 等待回答；預設只有 lead）、`owns`（repo glob）。
 
 `validate` 檢查的規則：至少 2 個 agent（lead 加一位成員；範本預設是三位）、lead 在 agent 清單內、每個 agent 都有 runtime（明設或由 `model` 推斷）且 `AGENT.md` 存在、`effort` 對該 runtime 合法（若 `runtime` 與可辨識的 `model` 矛盾則警告）、`can_message` 的目標存在、記憶資料夾互不重疊，且當 `max_parallel > 1` 時，每個非 lead 的 agent 都必須有互不重疊的 `owns`，repo 也必須是 git repository。
 

package/dist/adapters/claude.js

@@ -35,6 +35,8 @@ export function buildClaudeSettings(project, agent) {
         allow.push(rule("Edit", f));
     const deny = pol.deny.flatMap(denyRules);
     return {
+        // The user's own and plugin hooks (e.g. a hook that asks the user a question) would block every tool call of a headless wake-up.
+        disableAllHooks: true,
         permissions: { allow, deny },
         sandbox: {
             enabled: true,

package/dist/ask-answer.d.ts

@@ -0,0 +1,10 @@
+export interface PrepareResult {
+    complete: boolean;
+    problems: string[];
+    path: string;
+}
+/** Read the ask-reply file of a waiting run. With `assumeDefaults`, unanswered questions that have a suggestion take it (and the file is saved). */
+export declare function prepareAnswers(runDir: string, opts: {
+    assumeDefaults?: boolean;
+}): PrepareResult;
+export declare function openInEditor(file: string, env?: NodeJS.ProcessEnv): void;

package/dist/ask-answer.js

@@ -0,0 +1,21 @@
+import { spawnSync } from "node:child_process";
+import { applyDefaults, askReplyPath, checkAnswers, describeCheck, isComplete, readAskReply, writeAskReply } from "./ask-reply.js";
+/** Read the ask-reply file of a waiting run. With `assumeDefaults`, unanswered questions that have a suggestion take it (and the file is saved). */
+export function prepareAnswers(runDir, opts) {
+    const file = askReplyPath(runDir);
+    let reply = readAskReply(runDir);
+    if (!reply)
+        return { complete: false, problems: ["ask-reply.md does not exist"], path: file };
+    if (opts.assumeDefaults) {
+        reply = applyDefaults(reply);
+        writeAskReply(runDir, reply);
+    }
+    const check = checkAnswers(reply);
+    return { complete: isComplete(check), problems: describeCheck(check), path: file };
+}
+export function openInEditor(file, env = process.env) {
+    const editor = env.VISUAL || env.EDITOR || "vi";
+    const r = spawnSync(`${editor} ${JSON.stringify(file)}`, { shell: true, stdio: "inherit", env });
+    if (r.error || (r.status ?? 0) !== 0)
+        throw new Error(`The editor "${editor}" failed${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}.`);
+}

package/dist/ask-reply.d.ts

@@ -0,0 +1,65 @@
+export declare const MAX_QUESTIONS_PER_ASK = 10;
+export declare const ASK_REPLY_FILE = "ask-reply.md";
+export type AnswerSource = "user" | "default";
+export interface AskQuestion {
+    id: string;
+    text: string;
+    options?: string[];
+    suggested?: {
+        value: string;
+        reason?: string;
+    };
+    /** The agent that asked; the answer goes back to it. */
+    asker: string;
+    answer?: {
+        value: string;
+        by: AnswerSource;
+    };
+    /** The answer was already sent to the asker. */
+    delivered?: boolean;
+}
+export interface AskReply {
+    status: "pending" | "answered";
+    /** Who asked the latest batch. */
+    askedBy: string;
+    /** The round of the latest batch. */
+    round: number;
+    questions: AskQuestion[];
+}
+export type NewQuestion = Omit<AskQuestion, "asker" | "answer" | "delivered">;
+export declare const askReplyPath: (runDir: string) => string;
+export declare function parseAskBody(body: string): {
+    ok: true;
+    questions: NewQuestion[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseAskReply(text: string): AskReply;
+export declare function renderAskReply(r: AskReply): string;
+export declare function readAskReply(runDir: string): AskReply | undefined;
+export declare function writeAskReply(runDir: string, r: AskReply): void;
+/** Add a batch of questions, keeping everything already in the file. The same id with the same text is skipped (a re-routed ask after a crash). */
+export declare function addBatch(existing: AskReply | undefined, asker: string, round: number, qs: NewQuestion[]): {
+    ok: true;
+    reply: AskReply;
+} | {
+    ok: false;
+    error: string;
+};
+export interface AnswerCheck {
+    missing: string[];
+    invalid: {
+        id: string;
+        reason: string;
+    }[];
+}
+export declare const isComplete: (c: AnswerCheck) => boolean;
+/** Only questions whose answer was not sent yet count. */
+export declare function checkAnswers(r: AskReply): AnswerCheck;
+export declare function describeCheck(c: AnswerCheck): string[];
+export declare function applyDefaults(r: AskReply): AskReply;
+export declare function askersWithAnswers(r: AskReply): string[];
+/** The body of the `reply` mail that carries the answers back to `asker`. */
+export declare function renderAnswers(r: AskReply, asker: string): string;
+export declare function markDelivered(r: AskReply): AskReply;

package/dist/ask-reply.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+export const MAX_QUESTIONS_PER_ASK = 10;
+export const ASK_REPLY_FILE = "ask-reply.md";
+export const askReplyPath = (runDir) => path.join(runDir, "mail", ASK_REPLY_FILE);
+// ---- a tiny reader for the few tags used here (no XML dependency) ----
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const unesc = (s) => s.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+function tags(xml, name) {
+    const re = new RegExp(`<${name}((?:\\s+[\\w-]+="[^"]*")*)\\s*(?:/>|>([\\s\\S]*?)</${name}>)`, "g");
+    return [...xml.matchAll(re)].map((m) => {
+        const attrs = {};
+        for (const a of (m[1] ?? "").matchAll(/([\w-]+)="([^"]*)"/g))
+            attrs[a[1]] = unesc(a[2]);
+        return { attrs, inner: m[2] ?? "" };
+    });
+}
+const first = (xml, name) => tags(xml, name)[0];
+const textOf = (t) => unesc((t?.inner ?? "").trim());
+// ---- the body of an `ask` mail ----
+export function parseAskBody(body) {
+    const block = first(body, "ask");
+    if (!block)
+        return { ok: false, error: "the body has no <ask>…</ask> block" };
+    const found = tags(block.inner, "question");
+    if (found.length === 0)
+        return { ok: false, error: "the <ask> block needs at least one <question>" };
+    if (found.length > MAX_QUESTIONS_PER_ASK)
+        return { ok: false, error: `at most ${MAX_QUESTIONS_PER_ASK} questions per ask (got ${found.length}); ask the most important ones first` };
+    const seen = new Set();
+    const questions = [];
+    for (const [i, q] of found.entries()) {
+        const id = q.attrs.id?.trim();
+        if (!id || !/^[\w.-]+$/.test(id))
+            return { ok: false, error: `question ${i + 1} needs an id attribute made of letters, digits, "_", "-" or "."` };
+        if (seen.has(id))
+            return { ok: false, error: `duplicate question id "${id}"` };
+        seen.add(id);
+        const text = textOf(first(q.inner, "text"));
+        if (!text)
+            return { ok: false, error: `question "${id}" needs a non-empty <text>` };
+        const options = tags(first(q.inner, "options")?.inner ?? "", "option").map((o) => textOf(o)).filter(Boolean);
+        const sug = first(q.inner, "suggested");
+        const suggested = sug && textOf(sug) ? { value: textOf(sug), ...(sug.attrs.reason ? { reason: sug.attrs.reason } : {}) } : undefined;
+        if (suggested && options.length && !options.includes(suggested.value))
+            return { ok: false, error: `the suggested value of question "${id}" must be one of its options` };
+        questions.push({ id, text, ...(options.length ? { options } : {}), ...(suggested ? { suggested } : {}) });
+    }
+    return { ok: true, questions };
+}
+// ---- the ask-reply file ----
+export function parseAskReply(text) {
+    const root = first(text, "ask-reply");
+    if (!root)
+        throw new Error("ask-reply.md has no <ask-reply> root tag");
+    const askedBy = root.attrs.asked_by ?? "";
+    const questions = tags(root.inner, "question").map((q) => {
+        const ans = first(q.inner, "answer");
+        const value = textOf(ans);
+        const options = tags(first(q.inner, "options")?.inner ?? "", "option").map((o) => textOf(o));
+        const sug = first(q.inner, "suggested");
+        return {
+            id: q.attrs.id ?? "",
+            text: textOf(first(q.inner, "text")),
+            ...(options.length ? { options } : {}),
+            ...(sug && textOf(sug) ? { suggested: { value: textOf(sug), ...(sug.attrs.reason ? { reason: sug.attrs.reason } : {}) } } : {}),
+            asker: q.attrs.asker ?? askedBy,
+            ...(value ? { answer: { value, by: ans?.attrs.by === "default" ? "default" : "user" } } : {}),
+            ...(q.attrs.delivered === "true" ? { delivered: true } : {}),
+        };
+    });
+    return { status: root.attrs.status === "answered" ? "answered" : "pending", askedBy, round: Number(root.attrs.round) || 0, questions };
+}
+export function renderAskReply(r) {
+    const out = [`<ask-reply status="${r.status}" asked_by="${esc(r.askedBy)}" round="${r.round}">`];
+    for (const q of r.questions) {
+        out.push(`  <question id="${esc(q.id)}" asker="${esc(q.asker)}"${q.delivered ? ` delivered="true"` : ""}>`);
+        out.push(`    <text>${esc(q.text)}</text>`);
+        if (q.options?.length)
+            out.push(`    <options>`, ...q.options.map((o) => `      <option>${esc(o)}</option>`), `    </options>`);
+        if (q.suggested)
+            out.push(`    <suggested${q.suggested.reason ? ` reason="${esc(q.suggested.reason)}"` : ""}>${esc(q.suggested.value)}</suggested>`);
+        out.push(q.answer ? `    <answer by="${q.answer.by}">${esc(q.answer.value)}</answer>` : `    <answer></answer>`);
+        out.push(`  </question>`);
+    }
+    out.push(`</ask-reply>`);
+    return out.join("\n") + "\n";
+}
+export function readAskReply(runDir) {
+    const file = askReplyPath(runDir);
+    if (!fs.existsSync(file))
+        return undefined;
+    return parseAskReply(fs.readFileSync(file, "utf8"));
+}
+export function writeAskReply(runDir, r) {
+    atomicWrite(askReplyPath(runDir), renderAskReply(r));
+}
+// ---- batches, answers ----
+/** Add a batch of questions, keeping everything already in the file. The same id with the same text is skipped (a re-routed ask after a crash). */
+export function addBatch(existing, asker, round, qs) {
+    const base = existing ?? { status: "pending", askedBy: asker, round, questions: [] };
+    const added = [];
+    for (const q of qs) {
+        const old = base.questions.find((x) => x.id === q.id);
+        if (old) {
+            if (old.text === q.text)
+                continue;
+            return { ok: false, error: `question id "${q.id}" is already used in this run for a different question; use a new id` };
+        }
+        added.push({ ...q, asker });
+    }
+    if (added.length === 0)
+        return { ok: true, reply: base };
+    return { ok: true, reply: { status: "pending", askedBy: asker, round, questions: [...base.questions, ...added] } };
+}
+export const isComplete = (c) => c.missing.length === 0 && c.invalid.length === 0;
+function problem(q) {
+    const v = q.answer?.value.trim();
+    if (!v)
+        return undefined;
+    if (q.options?.length && !q.options.includes(v) && !/^other:\s*\S/.test(v))
+        return `must be one of: ${q.options.join(", ")} — or start with "other:" and write your own`;
+    return undefined;
+}
+/** Only questions whose answer was not sent yet count. */
+export function checkAnswers(r) {
+    const c = { missing: [], invalid: [] };
+    for (const q of r.questions) {
+        if (q.delivered)
+            continue;
+        if (!q.answer?.value.trim())
+            c.missing.push(q.id);
+        else {
+            const reason = problem(q);
+            if (reason)
+                c.invalid.push({ id: q.id, reason });
+        }
+    }
+    return c;
+}
+export function describeCheck(c) {
+    return [...c.missing.map((id) => `${id}: no answer yet`), ...c.invalid.map((i) => `${i.id}: ${i.reason}`)];
+}
+export function applyDefaults(r) {
+    return {
+        ...r,
+        questions: r.questions.map((q) => (!q.delivered && !q.answer?.value.trim() && q.suggested ? { ...q, answer: { value: q.suggested.value, by: "default" } } : q)),
+    };
+}
+export function askersWithAnswers(r) {
+    return [...new Set(r.questions.filter((q) => !q.delivered && q.answer?.value.trim()).map((q) => q.asker))];
+}
+/** The body of the `reply` mail that carries the answers back to `asker`. */
+export function renderAnswers(r, asker) {
+    const out = [`<answers>`];
+    for (const q of r.questions.filter((x) => !x.delivered && x.asker === asker && x.answer?.value.trim())) {
+        out.push(`  <question id="${esc(q.id)}">`, `    <text>${esc(q.text)}</text>`, `    <answer by="${q.answer?.by}">${esc(q.answer?.value ?? "")}</answer>`, `  </question>`);
+    }
+    out.push(`</answers>`);
+    return out.join("\n");
+}
+export function markDelivered(r) {
+    return { ...r, status: "answered", questions: r.questions.map((q) => (q.answer?.value.trim() ? { ...q, delivered: true } : q)) };
+}

package/dist/call.d.ts

@@ -0,0 +1,35 @@
+import { type Invoker } from "./adapters/index.js";
+import { type ResolvedAgent, type ResolvedProject } from "./config.js";
+export declare const CALL_PROJECT = "(call)";
+export declare const callsDir: (home: string) => string;
+export interface CallOptions {
+    home: string;
+    agent: string;
+    task: string;
+    /** Working directory; must exist. */
+    dir: string;
+    invoker?: Invoker;
+    signal?: AbortSignal;
+    say?: (line: string) => void;
+}
+export interface CallResult {
+    callId: string;
+    callDir: string;
+    ok: boolean;
+    cancelled: boolean;
+    /** The agent's final reply (empty when the call failed). */
+    text: string;
+    error?: string;
+    /** Protected files the agent changed and agent-lyceum put back. */
+    reverted: string[];
+}
+/** A global agent (from team.yaml) as a `call` uses it: global persona and memory, nobody to mail, nothing to ask, nothing to edit. */
+export declare function resolveCallAgent(home: string, name: string): ResolvedAgent;
+/** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
+export declare function callProject(home: string, agent: ResolvedAgent, dir: string, callDir: string): ResolvedProject;
+/** One call per agent at a time (two would write the same global memory). A lock whose process is gone, or that cannot be read, is taken over. */
+export declare function lockAgent(home: string, agent: string, callId: string): {
+    release(): void;
+};
+/** Wake one global agent once, alone, in `dir`. Leaves task.md, log/ and result.md in `<home>/calls/<call-id>/`. */
+export declare function callAgent(o: CallOptions): Promise<CallResult>;

package/dist/call.js

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { realInvoker } from "./adapters/index.js";
+import { must } from "./assert.js";
+import { ConfigError, loadGlobal, resolveProjectFrom } from "./config.js";
+import { atomicWrite } from "./fs-util.js";
+import { ProtectedGuard } from "./guard.js";
+import { assertName, homePaths, isInside } from "./paths.js";
+import { memoryDirs } from "./policy.js";
+import { lockHolderAlive } from "./project-lock.js";
+import { buildCallUserPrompt, buildSoloSystemPrompt } from "./prompt.js";
+import { newRunId } from "./run-store.js";
+import { DISPATCHER_DEFAULTS } from "./schema.js";
+export const CALL_PROJECT = "(call)";
+export const callsDir = (home) => path.join(home, "calls");
+/** A global agent (from team.yaml) as a `call` uses it: global persona and memory, nobody to mail, nothing to ask, nothing to edit. */
+export function resolveCallAgent(home, name) {
+    assertName("agent", name);
+    const g = loadGlobal(home);
+    if (!g.agents[name]) {
+        throw new ConfigError(`"${name}" is not an agent of the global library (${homePaths(home).globalConfig}). Global agents: ${Object.keys(g.agents).join(", ") || "(none)"}.`);
+    }
+    const p = resolveProjectFrom(home, CALL_PROJECT, g, { dir: home, team: { lead: name }, dispatcher: {}, agents: { [name]: {} } });
+    const a = must(p.agents[name], "the resolved agent");
+    if (!a.runtime)
+        throw new ConfigError(`Agent "${name}" has no runtime: set runtime (or a model) for it in team.yaml.`);
+    if (!fs.existsSync(a.agentMd))
+        throw new ConfigError(`AGENT.md of "${name}" not found: ${a.agentMd}`);
+    return {
+        ...a,
+        memory: { global: a.memory.global ?? path.join(homePaths(home).globalAgentsDir, name, "memory") },
+        resume: false,
+        canMessage: [],
+        canAskUser: false,
+        canEditAgentMd: false,
+        owns: [],
+    };
+}
+/** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
+export function callProject(home, agent, dir, callDir) {
+    const paths = {
+        root: callDir,
+        config: path.join(callDir, "call.yaml"),
+        agentsDir: path.join(callDir, "agents"),
+        shared: path.join(callDir, "shared"),
+        common: path.join(callDir, "shared", "COMMON.md"),
+        inboxRoot: path.join(callDir, "mail", "inbox"),
+        outboxRoot: path.join(callDir, "mail", "outbox"),
+        runs: path.join(callDir, "runs"),
+        taskMemory: path.join(callDir, "task-memory"),
+    };
+    return {
+        home,
+        name: CALL_PROJECT,
+        dir,
+        lead: agent.name,
+        dispatcher: { ...DISPATCHER_DEFAULTS, max_parallel: 1, workspace_mode: "shared" },
+        agents: { [agent.name]: agent },
+        paths,
+        solo: "call",
+    };
+}
+function readHolder(file) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, "utf8"));
+        return typeof j?.pid === "number" && typeof j?.call_id === "string" ? j : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One call per agent at a time (two would write the same global memory). A lock whose process is gone, or that cannot be read, is taken over. */
+export function lockAgent(home, agent, callId) {
+    const dir = callsDir(home);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `.lock-${agent}`);
+    const mine = JSON.stringify({ pid: process.pid, call_id: callId });
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.writeFileSync(file, mine, { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const cur = readHolder(file);
+            if (cur && lockHolderAlive({ pid: cur.pid }))
+                throw new Error(`${agent} is already being called (call ${cur.call_id}, pid ${cur.pid}). Wait for it to finish.`);
+            if (attempt >= 1)
+                throw new Error(`Could not take ${file}; try again.`);
+            fs.rmSync(file, { force: true });
+        }
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.off("exit", release);
+        if (readHolder(file)?.call_id === callId)
+            fs.rmSync(file, { force: true });
+    };
+    process.on("exit", release);
+    return { release };
+}
+/** Wake one global agent once, alone, in `dir`. Leaves task.md, log/ and result.md in `<home>/calls/<call-id>/`. */
+export async function callAgent(o) {
+    const say = o.say ?? ((s) => console.error(s));
+    const agent = resolveCallAgent(o.home, o.agent);
+    const dir = path.resolve(o.dir);
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        throw new Error(`Working directory not found: ${dir}`);
+    const real = (p) => {
+        try {
+            return fs.realpathSync(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    const realDir = real(dir);
+    const realHome = real(o.home);
+    // The called agent is the only one listed, so only its files are protected: nothing may run where the rest of the home is writable.
+    if (isInside(realHome, realDir) || isInside(realDir, realHome)) {
+        throw new Error(`Working directory ${dir} overlaps the agent-lyceum home ${o.home}: a call could change other agents' files there. Pass a --dir that is neither inside nor above the agent-lyceum home.`);
+    }
+    if (!o.task.trim())
+        throw new Error("No task given: pass it as text or with --task-file.");
+    const callId = newRunId();
+    const callDir = path.join(callsDir(o.home), callId);
+    const lease = lockAgent(o.home, agent.name, callId);
+    try {
+        fs.mkdirSync(path.join(callDir, "log"), { recursive: true });
+        fs.writeFileSync(path.join(callDir, "task.md"), o.task);
+        for (const d of memoryDirs(agent))
+            fs.mkdirSync(d, { recursive: true });
+        const project = callProject(o.home, agent, dir, callDir);
+        const guard = new ProtectedGuard(project);
+        say(`Calling ${agent.name} in ${dir} (call ${callId})`);
+        const invoke = o.invoker ?? realInvoker;
+        const result = await invoke({
+            project,
+            agent,
+            workDir: callDir,
+            systemPrompt: buildSoloSystemPrompt(project, agent),
+            userPrompt: buildCallUserPrompt(agent, o.task),
+            timeoutSec: project.dispatcher.wake_timeout_sec,
+            signal: o.signal,
+            logDir: path.join(callDir, "log"),
+        }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message }));
+        const reverted = guard.check([agent]).map((v) => v.file);
+        for (const f of reverted)
+            say(`warn   ${agent.name} changed ${f}; it was put back.`);
+        const cancelled = !!result.cancelled;
+        const error = result.ok ? undefined : cancelled ? "cancelled" : (result.error ?? (result.timedOut ? "timed out" : "failed"));
+        atomicWrite(path.join(callDir, "result.md"), result.ok ? `${result.text.trimEnd()}\n` : `# Call ${cancelled ? "cancelled" : "failed"}\n\n${error}\n`);
+        return { callId, callDir, ok: result.ok, cancelled, text: result.ok ? result.text : "", error, reverted };
+    }
+    finally {
+        lease.release();
+    }
+}