@konglx/rotom 2.21.0

package/dist/cli/rotom.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * rotom — Mesh CLI for digital employees.
+ *
+ * Every invocation acts as a specific agent. Selection priority:
+ *   1. ROTOM_AGENT env
+ *   2. --as <name>
+ *   3. ~/.rotom/config.json#defaultAgent
+ * If none of those resolve, rotom refuses to run (so you never accidentally
+ * use the wrong agent's token on a multi-agent box).
+ *
+ * The agent's master URL + mesh token come from one of:
+ *   - "openclaw":  channels['a2a-gateway'].{master,token,name}  in openclaw.json
+ *   - "executor":  matching `workers[].name` in executor.config.json
+ *   - Auto-discovery: ~/.rotom/executor.config.json (shared with `executor`
+ *     worker process). No explicit `rotom config add-executor` needed.
+ *   - Env fallback: ROTOM_MASTER + ROTOM_TOKEN (set by worker child spawns).
+ *
+ * Output is JSON by default. `--pretty` switches to a human table where it
+ * makes sense; everywhere else it pretty-prints the same JSON.
+ */
+import { ensureRotomSkillMd } from "../shared/skill-md.js";
+import { parseArgs, setPretty, resolveAgent, flagStr, fail, } from "./common.js";
+import { cmdConfig } from "./config.js";
+import { cmdWhoami } from "./identity.js";
+import { cmdStatus } from "./identity.js";
+import { cmdDirectory } from "./directory.js";
+import { cmdGroup } from "./group.js";
+import { cmdIssue } from "./issue.js";
+import { cmdNote } from "./note.js";
+import { cmdMemory } from "./memory.js";
+import { cmdSkill } from "./skill.js";
+import { cmdSchedule } from "./schedule.js";
+import { cmdAsk } from "./ask.js";
+import { cmdMaster, colonExpand } from "./master.js";
+import { cmdExecutor } from "./executor.js";
+import { cmdInit } from "./init.js";
+import { cmdJoin } from "./join.js";
+import { cmdRepo } from "./repo.js";
+import { cmdRun } from "./run.js";
+import { cmdTeam } from "./team.js";
+import { cmdLink } from "./link.js";
+import { cmdFed } from "./fed.js";
+const HELP = `rotom — Mesh CLI
+
+Usage: rotom [--as <agent>] [--pretty] <command> [args]
+
+Agent selection:
+  --as <name>           override which registered agent to act as
+  ROTOM_AGENT env       same, via env (takes priority over --as)
+  defaultAgent (config) fallback
+  Auto-discovery: workers in ~/.rotom/executor.config.json resolve
+  by name without needing 'rotom config add-executor' first.
+
+Config:
+  config show
+  config init
+  config use <name>                            set default agent
+  config add-openclaw <name> <openclaw.json>   register an OpenClaw-hosted agent
+  config add-executor <name> <executor.json>   register an executor worker
+  config remove <name>
+
+Bootstrap (first-time setup):
+  init                                         detect claude/codex/hermes, ask for
+                                               names + master IP, register agents,
+                                               and write ~/.rotom/executor.config.json
+    Flags:
+      --master <ip:port>     skip prompt (default: 127.0.0.1:28800)
+      --domain <name>        skip prompt (default: pick from master's existing
+                             domains; falls back to "默认部门" or "default")
+      --name-prefix <p>      default name = <p>-<tool>  (default: $USER)
+      --tools <a,b,c>        limit detection to a subset of claude,codex,hermes
+      --yes / -y             accept all defaults, do not overwrite without confirm
+      --force                overwrite existing executor.config.json without prompt
+
+  join <masterHost:port> --name <n> --domain <d> --cli-tool <claude|codex|hermes|openclaw>
+                                               [--working-dir PATH] [--profile-position P]
+                                               [--profile-bio B] [--force]
+                                               首次申请 token 落盘到 ~/.rotom/(本地
+                                               交互式 CLI 作为 mesh host 用,不起
+                                               executor daemon)。一个机器一个 CLI 一个
+                                               agent:每次换 CLI 用不同 --name + --cli-tool。
+                                               --cli-tool 缺省时按 PATH 自动探测。落盘结构
+                                               对齐 executor.config.json workers[](含
+                                               cliTool/workingDir/profile),master 侧不存
+                                               cliTool(REST-only,不维持 WS)。
+
+Identity:
+  whoami
+  status                                        master health check (no agent needed)
+
+Read:
+  directory [--online] [--domain D]
+  group create <title> --agents <a,b[,c...]> [--message M] [--note D|--note-file F] [--cwd PATH] [--no-template] [--a2a-direct]
+                                               一键建群+拉人。默认加载"群内讨论方案设计"
+                                               guidance 模板(可 --no-template 跳过)。
+                                               预检 --agents 名字都已注册,未注册 → fail 不建群。
+                                               --a2a-direct  建单播群(unicast):≥2 成员,
+                                                            消息只入库、不广播,worker 不被
+                                                            自动唤醒;只在 CLI --need-reply
+                                                            显式点名时叫醒对方回话,每轮
+                                                            A 发 → B 回 → 停。
+  group list
+  group members <groupId>
+  group history <groupId> [--limit N]
+  group new-messages <groupId> --since <ISO>     只看某个时间点之后的新消息(轮询用)
+  group archive <groupId>
+  group unarchive <groupId>
+  issue list <groupId> [--status S] [--type task]
+  issue show <issueId>
+  issue events <issueId>
+  issue messages <issueId>
+  issue comment <issueId> --message M [--reply-to <eventId>]
+
+Send:
+  group send <groupId> <target> <message...> [--no-dispatch] [--need-reply]
+    --no-dispatch  只入库+广播,不 trigger target 的 worker(同步信息用)
+    --need-reply   自动补 @target,master 硬剥回复里的 @asker 防回触发(一问一答)
+
+Issue:
+  issue create <groupId> --description D [--title T] [--priority low|medium|high|critical]
+                         [--assignee <agent>] [--approval-policy r_allow|rw_allow] [--run]
+    description 是主输入;title 可选,未传时由后端从前 40 字符自动截断生成。
+    description 以已注册的 slash command 开头时（如 "/plan ..."）将以对应模式执行。
+    /plan：Claude 走 --permission-mode plan；Codex 注入 developerInstructions。
+    --assignee 创建后立即把 issue 指派给指定 agent（不会自动起跑）。
+    --approval-policy rw_allow（默认,读写都默认通过) / r_allow（读默认通过,写需人工审批)。
+    --run 创建+指派后立即派发执行；必须同时给 --assignee，且 agent 必须在线。
+          --run 的 prompt 直接用 --description;若只传 --title 则 fallback 到 title。
+  issue update <issueId> [--title T] [--description D] [--priority low|medium|high|critical]
+                         [--assignee <agent> | --unassign] [--approval-policy r_allow|rw_allow]
+                         [--status open|in_progress|completed|failed|cancelled]
+    局部更新 issue 字段。至少给一个 flag。
+    只传 --description 不传 --title 时,后端会重新截断 title 并重解析 slash command。
+    --assignee / --unassign 互斥。
+    --status 低层 setter,可任意切换(含 reopen cancelled→open),无状态机限制。
+  issue cancel <issueId>
+  issue delete <issueId>
+
+Note (极简文字记录,纯 CRUD):
+  note list <groupId>
+  note show <noteId>
+  note create <groupId> --title T [--description D]
+  note update <noteId> [--title T] [--description D]
+  note delete <noteId>
+
+Memory (记忆体系:note=纯人看 agent_visible=0;memory=agent 可见 agent_visible=1):
+  memory search <keyword> <groupId> [--scope group|global] [--category <c>]
+  memory list <groupId> [--scope group|global] [--type note|memory|all] [--category <c>] [--tags t1,t2]
+  memory get <memoryId>
+  memory add <groupId> --key K --value V --category C [--scope global] [--summary S] [--tags t1,t2]
+                 [--visibility group|global|private] [--no-agent-visible] [--expires 7d]
+  memory update <id> [--value V] [--category C] [--visibility V] [--agent-visible|--no-agent-visible]
+  memory remove <id>
+  memory promote <id> --visibility global
+  memory pending <groupId> [--scope global]
+  memory approve <id>
+  memory reject <id>
+  memory stats <groupId> [--scope global]
+
+Schedule (群内定时任务,master 端 30s tick 调度):
+  schedule list                              [--group <id>] [--pretty]
+  schedule show <id>
+  schedule add   --group <id> --mode <agent|message> [--agent A] --prompt P
+                 ( --every <dur> | --in <dur> | --at <iso> )
+                 [--name N] [--repeat N|0|∞] [--enabled true|false]
+  schedule update <id> [--every D] [--in D] [--at ISO] [--prompt T] [--name N]
+                      [--mode agent|message] [--agent A]
+                      [--repeat N|0|∞] [--enabled true|false]
+  schedule remove <id>                       (alias: delete)
+  schedule enable <id> | disable <id>
+  schedule trigger <id>
+    --every <dur>   例 30s / 5m / 2h / 1d       interval 模式,>= 30s
+    --in    <dur>   例 3m                        one-shot,相对当前时间
+    --at    <iso>   例 2026-06-22T09:00          one-shot,绝对时间
+    --repeat N      最多跑 N 次后自动 disable;传 0 或 ∞ 表示不限次数
+
+Ask (Agent A 提问 B + 5min 超时兜底 bridge,详见 docs/AGENT_ASK_REPLY_TIMER.md):
+  ask <groupId> <target> <question...>   [--timeout 5m] [--escalate-to <真人>]
+    发问 + 建 bridge。系统自动 5min 超时:
+      - B @ A → master 正常 dispatch 给 A,timer 自动 cancel
+      - B 不 @ 回复 → 5min 后系统建 Issue 给 A,描述里复述回复
+      - 完全无回复 → 5min 后系统建 Issue 指示 A @ 真人求救
+    target 离线 → 不建 bridge,exit 2(提示 A 自己 @ 真人)
+  ask list --group <id> [--status pending|answered|timed_out|cancelled] [--pretty]
+  ask show <bridgeId>
+  ask cancel <bridgeId>                    A 主动 cancel(收到非@回复,自己判断是回复了)
+
+Process lifecycle (local daemon control — do not require an agent):
+  run <opc|federation> [opts]     一站式启动 master + executor(等价 bin/rotom-up.sh start)
+    opc           OPC 模式(默认,本机 master + 自动 spawn executor)
+    federation    协调 master(注入 ROTOM_MASTER_ROLE=coordination),作为 federation 中心节点
+    通用选项: --port N | --host A | --data D | --no-build | --dev
+  master <start|stop|restart|status> [--daemon] [--port N] [--host A] [--data D] [--dev]
+  master:start | master:stop | master:status | master:restart   (alias)
+  executor [--config <path>]      start executor workers (reads ~/.rotom/executor.config.json by default)
+
+Repo cache (内置 git worktree 缓存,migration 051;本机 FS 操作,不需要 agent):
+  repo list                       列出 ~/.rotom/repos/ 下所有 bare clone + worktree 数 + 磁盘占用
+  repo prune [--remove-orphans]   清理孤儿 worktree 元数据,可选删除无引用且 30 天未 fetch 的 bare clone
+  repo fetch <repo-id>            显式 git fetch --prune 某 bare clone
+  repo remove <repo-id>           删除 bare clone(要求无活跃 worktree)
+
+Federation (跨 master 协作,不依赖 dashboard):
+  team join <coordEndpoint> [--team-name N]   本机 master 运行时加入远端协调 master 形成团队
+                                              coordEndpoint 形如 ws://192.168.1.5:28800
+  team leave                                  离开当前团队,切回 standalone
+  team list                                   已加入的团队列表(本机视角)
+  team members [--team-id <id>]               团队内可见 agent 列表(--team-id 缺省读 ~/.rotom/team.json)
+
+  link join <coordEndpoint> [--hostname N]    一次性:生成 masterId + 写 ~/.rotom/link.json(轻量客户端模式)
+  link start [--port N]                       启动 rotom-link daemon(默认端口 28900),不起完整 master
+  link stop | restart | status | logs         daemon 生命周期
+  (随后可 rotom fed members / rotom fed ask <ref> "...")
+
+  fed members                                 列出协调 master 同步来的可见 agent
+  fed ask <ref> "<question>" [--timeout 5m]   阻塞等回复(ref 形如 alice@hostB 或 alice)
+
+Global flags:
+  --pretty   format output for humans (tables / indented JSON)
+`;
+async function main() {
+    ensureRotomSkillMd();
+    const { positional, flags } = parseArgs(process.argv.slice(2));
+    setPretty(flags.pretty === true);
+    if (positional.length === 0 || flags.help === true || positional[0] === "help") {
+        process.stdout.write(HELP);
+        return;
+    }
+    const cmd = positional[0];
+    const rest = positional.slice(1);
+    const asFlag = flagStr(flags, "as");
+    // Commands that don't need an agent
+    if (cmd === "config")
+        return cmdConfig(rest, flags);
+    if (cmd === "init")
+        return cmdInit(rest, flags);
+    if (cmd === "join")
+        return cmdJoin(rest, flags);
+    if (cmd === "team")
+        return cmdTeam(rest, flags);
+    if (cmd === "link")
+        return cmdLink(rest, flags);
+    if (cmd === "fed")
+        return cmdFed(rest, flags);
+    // Master / executor / status — no agent required
+    if (cmd === "master" || cmd === "master:start" || cmd === "master:stop" ||
+        cmd === "master:status" || cmd === "master:restart") {
+        return cmdMaster(colonExpand(cmd, rest), flags);
+    }
+    if (cmd === "executor") {
+        return cmdExecutor(rest, flags);
+    }
+    if (cmd === "repo") {
+        return cmdRepo(rest, flags);
+    }
+    if (cmd === "run") {
+        return cmdRun(rest);
+    }
+    if (cmd === "status") {
+        return cmdStatus(rest, flags);
+    }
+    const agent = resolveAgent(asFlag);
+    switch (cmd) {
+        case "whoami": return cmdWhoami(agent);
+        case "directory": return cmdDirectory(agent, flags);
+        case "group": return cmdGroup(agent, rest, flags);
+        case "issue": return cmdIssue(agent, rest, flags);
+        case "note": return cmdNote(agent, rest, flags);
+        case "memory": return cmdMemory(agent, rest, flags);
+        case "skill": return cmdSkill(agent, rest, flags);
+        case "schedule": return cmdSchedule(agent, rest, flags);
+        case "ask": return cmdAsk(agent, rest, flags);
+        default: fail(`unknown command: ${cmd}\nRun 'rotom help' for usage.`);
+    }
+}
+main().catch((e) => fail(e.message));

package/dist/cli/routes.js

@@ -0,0 +1,118 @@
+/**
+ * CLI route / query-string / usage / fetch helpers.
+ *
+ * Replaces the hand-rolled `${encodeURIComponent(gid)}` template strings,
+ * `URLSearchParams` + `?${qs.toString() ? \`?${qs}\` : ""}` boilerplate,
+ * `fail("usage: rotom <cmd> ...")` lines, and bootstrap fetches in
+ * `cli/init.ts` / `cli/join.ts` that bypassed `common.ts:api()` because they
+ * have no `ResolvedAgent` yet.
+ *
+ * Existing `common.ts` exports (`api`, `fail`, `masterHttpUrl`, ...) are the
+ * foundation — `routes.ts` builds on top, not around them.
+ */
+import { fail, masterHttpUrl } from "./common.js";
+// ── Route builder ─────────────────────────────────────────────────────────
+/**
+ * Substitute `:name` placeholders in `template` with URL-encoded segments.
+ *
+ *   route("/groups/:groupId/issues/:issueId", gid, iid)
+ *   → "/groups/<encoded gid>/issues/<encoded iid>"
+ *
+ * The placeholder names are documentation only — segments are positional and
+ * substituted in order. Throws if the segment count doesn't match the
+ * placeholder count, so typos in the template surface at the call site.
+ */
+export function route(template, ...segs) {
+    const placeholders = template.match(/:[A-Za-z_][A-Za-z0-9_]*/g) ?? [];
+    if (placeholders.length !== segs.length) {
+        throw new Error(`route(${template}): expected ${placeholders.length} segment(s), got ${segs.length}`);
+    }
+    let out = template;
+    for (let i = 0; i < segs.length; i++) {
+        out = out.replace(placeholders[i], encodeURIComponent(segs[i]));
+    }
+    return out;
+}
+// ── Query-string builder ──────────────────────────────────────────────────
+/**
+ * Build a query string from a params map. Returns either `""` (no params) or
+ * `"?k=v&k2=v2"`. Skips `undefined` / empty-string values, coerces numbers to
+ * string, URL-encodes both keys and values.
+ *
+ *   qs({ status: "open", limit: 50, type: undefined })
+ *   → "?status=open&limit=50"
+ */
+export function qs(params) {
+    const pairs = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        pairs.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    return pairs.length === 0 ? "" : `?${pairs.join("&")}`;
+}
+// ── Usage helpers ─────────────────────────────────────────────────────────
+/**
+ * Print `usage: rotom <cmd> <hint>` to stderr and exit 1. `hint` is the
+ * literal post-`rotom ` text — e.g. `usage("ask list", "rotom ask list --group <id>")`
+ * emits `usage: rotom ask list --group <id>` (matching the existing
+ * `fail("usage: rotom ...")` strings, so output stays byte-identical).
+ */
+export function usage(cmd, hint) {
+    const hintStr = hint ? ` ${hint}` : "";
+    fail(`usage: rotom ${cmd}${hintStr}`);
+}
+/**
+ * Print `unknown <cmd> subcommand: <sub | "(none)">` to stderr and exit 1.
+ * Used at the tail of every CLI command's subcommand dispatch.
+ */
+export function unknownSubcommand(cmd, sub) {
+    fail(`unknown ${cmd} subcommand: ${sub || "(none)"}`);
+}
+// ── Master URL helpers ─────────────────────────────────────────────────────
+/**
+ * Build a `ws://` (or `wss://`) URL from a master spec that may be either
+ * `http://host:port` or `ws://host:port`. The inverse of `masterHttpUrl`.
+ * Strips trailing slashes for consistency.
+ */
+export function masterWsUrl(masterHttpOrWs) {
+    return masterHttpOrWs
+        .replace(/^http:\/\//, "ws://")
+        .replace(/^https:\/\//, "wss://")
+        .replace(/\/+$/, "");
+}
+/** Build `http://host:port` from raw `host` + `port`. */
+export function masterHttpBase(host, port) {
+    return `http://${host}:${port}`;
+}
+/** Build `ws://host:port` from raw `host` + `port`. */
+export function masterWsBase(host, port) {
+    return `ws://${host}:${port}`;
+}
+/**
+ * Fetch a master URL without an auth token — for bootstrap paths (init, join)
+ * that don't yet have a `ResolvedAgent`. Always sets `Content-Type:
+ * application/json` and parses the response as JSON (falling back to the raw
+ * text if the body isn't valid JSON). Does NOT retry — callers decide how to
+ * handle non-2xx and network errors.
+ */
+export async function masterFetch(url, init) {
+    const merged = {
+        ...init,
+        headers: {
+            "Content-Type": "application/json",
+            ...(init?.headers ?? {}),
+        },
+    };
+    const resp = await fetch(url, merged);
+    const text = await resp.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        data = text;
+    }
+    return { status: resp.status, data };
+}
+export { masterHttpUrl };

package/dist/cli/run.js

@@ -0,0 +1,45 @@
+/**
+ * rotom run — 一站式启动入口(等价 bin/rotom-up.sh start,可选 federation 角色)。
+ *
+ *   rotom run opc          启动 master + 自动 spawn executor(OPC 模式,默认)
+ *   rotom run federation   启动协调 master + 自动 spawn executor(federation 中心节点)
+ *
+ * 与 `pnpm start` 的区别:走 CLI 统一入口,且 federation 子命令会自动注入
+ * ROTOM_MASTER_ROLE=coordination,免去手写环境变量。
+ */
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { fail, installRoot } from "./common.js";
+function runRotomUp(args, env) {
+    const scriptPath = path.join(installRoot(), "bin/rotom-up.sh");
+    if (!fs.existsSync(scriptPath)) {
+        fail(`shell script not found: ${scriptPath}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn("bash", [scriptPath, ...args], {
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+export async function cmdRun(rest) {
+    const sub = rest[0];
+    const passthrough = rest.slice(1);
+    let env = {};
+    switch (sub) {
+        case "opc":
+            break;
+        case "federation":
+            env.ROTOM_MASTER_ROLE = "coordination";
+            break;
+        default:
+            fail("usage: rotom run <opc|federation> [--port N] [--host A] [--data D] [--no-build] [--dev]\n" +
+                "       opc          启动 master + executor(OPC 模式,默认)\n" +
+                "       federation   启动协调 master + executor(ROTOM_MASTER_ROLE=coordination)");
+    }
+    const code = await runRotomUp(passthrough, env);
+    process.exit(code);
+}

package/dist/cli/schedule.js

@@ -0,0 +1,237 @@
+import { toBeijing } from "../shared/time.js";
+/**
+ * rotom schedule — schedule list/show/add/update/remove/enable/disable/trigger.
+ */
+import { api, printJson, printTable, fail, flagStr, requireFlag, pretty, } from "./common.js";
+import { route, qs, usage } from "./routes.js";
+function parseDuration(input) {
+    const s = String(input).trim();
+    const m = s.match(/^(\d+)\s*(s|sec|m|min|h|hr|d|day)?$/i);
+    if (!m) {
+        const n = Number(s);
+        return Number.isFinite(n) && n >= 0 ? n : null;
+    }
+    const n = parseInt(m[1], 10);
+    const unit = (m[2] || "s").toLowerCase();
+    switch (unit) {
+        case "s":
+        case "sec": return n;
+        case "m":
+        case "min": return n * 60;
+        case "h":
+        case "hr": return n * 3600;
+        case "d":
+        case "day": return n * 86400;
+        default: return null;
+    }
+}
+function formatNextRun(ms) {
+    if (!ms)
+        return "-";
+    try {
+        return toBeijing(ms);
+    }
+    catch {
+        return String(ms);
+    }
+}
+export async function cmdSchedule(agent, rest, flags) {
+    const sub = rest[0];
+    if (sub === "list") {
+        const gid = flagStr(flags, "group");
+        const routePath = `${route("/schedules")}${qs({ group_id: gid })}`;
+        const data = await api(agent, "GET", routePath);
+        if (pretty) {
+            printTable(data.map((t) => ({
+                id: t.id,
+                name: t.name,
+                group: t.group_id.slice(0, 8),
+                mode: t.mode,
+                kind: t.schedule_kind,
+                every: t.interval_sec ? `${t.interval_sec}s` : "-",
+                enabled: t.enabled ? "yes" : "no",
+                repeat: t.repeat_times ?? "\u221E",
+                ran: t.repeat_count,
+                last_status: t.last_status ?? "-",
+                next_run_at: formatNextRun(t.next_run_at),
+            })), ["id", "name", "group", "mode", "kind", "every", "enabled", "repeat", "ran", "last_status", "next_run_at"]);
+        }
+        else {
+            printJson(data);
+        }
+        return;
+    }
+    if (sub === "show") {
+        const id = rest[1];
+        if (!id)
+            usage("schedule show", "<id>");
+        const data = await api(agent, "GET", route("/schedules/:id", id));
+        printJson(data);
+        return;
+    }
+    if (sub === "add") {
+        const groupId = requireFlag(flags, "group");
+        const modeRaw = flagStr(flags, "mode") || "agent";
+        if (modeRaw !== "agent" && modeRaw !== "message") {
+            fail(`--mode must be "agent" or "message" (got: ${modeRaw})`);
+        }
+        const mode = modeRaw;
+        const agentName = flagStr(flags, "agent");
+        if (mode === "agent" && !agentName) {
+            fail("--agent is required when --mode agent");
+        }
+        const prompt = requireFlag(flags, "prompt");
+        const name = flagStr(flags, "name") || `schedule-${Date.now()}`;
+        const repeatRaw = flagStr(flags, "repeat");
+        const enabledRaw = flagStr(flags, "enabled");
+        const everyRaw = flagStr(flags, "every");
+        const inRaw = flagStr(flags, "in");
+        const atRaw = flagStr(flags, "at");
+        const presentSchedule = [everyRaw, inRaw, atRaw].filter(Boolean).length;
+        if (presentSchedule !== 1) {
+            fail("exactly one of --every / --in / --at is required\n" +
+                "  --every <dur>      e.g. 30s, 5m, 2h, 1d   (interval schedule)\n" +
+                "  --in <dur>         e.g. 3m                  (one-shot, relative)\n" +
+                "  --at <iso-time>    e.g. 2026-06-22T09:00    (one-shot, absolute)");
+        }
+        const body = { name, group_id: groupId, mode, prompt };
+        if (mode === "agent" && agentName)
+            body.agent_name = agentName;
+        if (enabledRaw !== undefined)
+            body.enabled = enabledRaw !== "false" && enabledRaw !== "0";
+        if (everyRaw !== undefined) {
+            const sec = parseDuration(everyRaw);
+            if (sec === null || sec < 30)
+                fail(`--every must parse to >= 30s (got: ${everyRaw})`);
+            body.schedule_kind = "interval";
+            body.interval_sec = sec;
+        }
+        else if (inRaw !== undefined) {
+            const sec = parseDuration(inRaw);
+            if (sec === null || sec <= 0)
+                fail(`--in must parse to a positive duration (got: ${inRaw})`);
+            body.schedule_kind = "once";
+            body.run_at = Date.now() + sec * 1000;
+        }
+        else if (atRaw !== undefined) {
+            const ms = Date.parse(atRaw);
+            if (!Number.isFinite(ms) || ms <= Date.now()) {
+                fail(`--at must be a valid ISO datetime in the future (got: ${atRaw})`);
+            }
+            body.schedule_kind = "once";
+            body.run_at = ms;
+        }
+        if (repeatRaw !== undefined) {
+            if (repeatRaw === "0" || repeatRaw === "\u221E" || repeatRaw.toLowerCase() === "infinite") {
+                body.repeat_times = null;
+            }
+            else {
+                const n = parseInt(repeatRaw, 10);
+                if (!Number.isFinite(n) || n <= 0)
+                    fail(`--repeat must be a positive integer, 0, or \u221E (got: ${repeatRaw})`);
+                body.repeat_times = n;
+            }
+        }
+        const created = await api(agent, "POST", "/schedules", body);
+        printJson(created);
+        return;
+    }
+    if (sub === "update") {
+        const id = rest[1];
+        if (!id)
+            usage("schedule update", "<id> [--every D] [--in D] [--at ISO] [--prompt T] [--name N] [--mode agent|message] [--agent A] [--repeat N] [--enabled true|false]");
+        const body = {};
+        const name = flagStr(flags, "name");
+        if (name !== undefined)
+            body.name = name;
+        const prompt = flagStr(flags, "prompt");
+        if (prompt !== undefined)
+            body.prompt = prompt;
+        const modeRaw = flagStr(flags, "mode");
+        if (modeRaw !== undefined) {
+            if (modeRaw !== "agent" && modeRaw !== "message")
+                fail(`--mode must be "agent" or "message"`);
+            body.mode = modeRaw;
+        }
+        const agentName = flagStr(flags, "agent");
+        if (agentName !== undefined)
+            body.agent_name = agentName;
+        const repeatRaw = flagStr(flags, "repeat");
+        if (repeatRaw !== undefined) {
+            if (repeatRaw === "0" || repeatRaw === "\u221E" || repeatRaw.toLowerCase() === "infinite") {
+                body.repeat_times = null;
+            }
+            else {
+                const n = parseInt(repeatRaw, 10);
+                if (!Number.isFinite(n) || n <= 0)
+                    fail("--repeat must be a positive integer, 0, or \u221E");
+                body.repeat_times = n;
+            }
+        }
+        const enabledRaw = flagStr(flags, "enabled");
+        if (enabledRaw !== undefined)
+            body.enabled = enabledRaw !== "false" && enabledRaw !== "0";
+        const everyRaw = flagStr(flags, "every");
+        const inRaw = flagStr(flags, "in");
+        const atRaw = flagStr(flags, "at");
+        if (everyRaw !== undefined) {
+            const sec = parseDuration(everyRaw);
+            if (sec === null || sec < 30)
+                fail("--every must parse to >= 30s");
+            body.schedule_kind = "interval";
+            body.interval_sec = sec;
+        }
+        else if (inRaw !== undefined) {
+            const sec = parseDuration(inRaw);
+            if (sec === null || sec <= 0)
+                fail("--in must parse to a positive duration");
+            body.schedule_kind = "once";
+            body.run_at = Date.now() + sec * 1000;
+        }
+        else if (atRaw !== undefined) {
+            const ms = Date.parse(atRaw);
+            if (!Number.isFinite(ms) || ms <= Date.now())
+                fail("--at must be a valid ISO datetime in the future");
+            body.schedule_kind = "once";
+            body.run_at = ms;
+        }
+        if (Object.keys(body).length === 0) {
+            fail("no fields to update — pass at least one of --every / --in / --at / --prompt / --name / --mode / --agent / --repeat / --enabled");
+        }
+        const data = await api(agent, "PATCH", route("/schedules/:id", id), body);
+        printJson(data);
+        return;
+    }
+    if (sub === "remove" || sub === "delete") {
+        const id = rest[1];
+        if (!id)
+            usage("schedule remove", "<id>");
+        const data = await api(agent, "DELETE", route("/schedules/:id", id));
+        printJson(data);
+        return;
+    }
+    if (sub === "enable" || sub === "disable") {
+        const id = rest[1];
+        if (!id)
+            usage(`schedule ${sub}`, "<id>");
+        const data = await api(agent, "PATCH", route("/schedules/:id", id), { enabled: sub === "enable" });
+        printJson(data);
+        return;
+    }
+    if (sub === "trigger") {
+        const id = rest[1];
+        if (!id)
+            usage("schedule trigger", "<id>");
+        const data = await api(agent, "POST", route("/schedules/:id/trigger", id));
+        printJson(data);
+        return;
+    }
+    usage("schedule", "<list|show|add|update|remove|enable|disable|trigger> [...]\n" +
+        "  list                       [--group <id>] [--pretty]\n" +
+        "  show <id>\n" +
+        "  add    --group <id> --mode <agent|message> [--agent A] --prompt P\n" +
+        "         ( --every <dur> | --in <dur> | --at <iso> ) [--name N] [--repeat N] [--enabled true|false]\n" +
+        "  update <id> [--every D] [--in D] [--at ISO] [--prompt T] [--name N] [--mode M] [--agent A]\n" +
+        "                   [--repeat N] [--enabled true|false]\n" +
+        "  remove <id> | enable <id> | disable <id> | trigger <id>");
+}