agent-steward 0.0.4 → 0.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +134 -2
- package/CROSS_PLATFORM.md +19 -0
- package/README.md +52 -7
- package/ROADMAP-STRATEGY.md +21 -18
- package/ROADMAP.md +140 -159
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +351 -0
- package/dist/core/execution.d.ts +203 -0
- package/dist/core/execution.d.ts.map +1 -0
- package/dist/core/execution.js +309 -0
- package/dist/core/gate-integrity.d.ts +35 -0
- package/dist/core/gate-integrity.d.ts.map +1 -0
- package/dist/core/gate-integrity.js +132 -0
- package/dist/core/git-trigger.d.ts.map +1 -1
- package/dist/core/git-trigger.js +14 -2
- package/dist/core/guard-run.d.ts +4 -0
- package/dist/core/guard-run.d.ts.map +1 -0
- package/dist/core/guard-run.js +101 -0
- package/dist/core/guard.d.ts +52 -0
- package/dist/core/guard.d.ts.map +1 -0
- package/dist/core/guard.js +362 -0
- package/dist/core/lock.d.ts +41 -0
- package/dist/core/lock.d.ts.map +1 -1
- package/dist/core/lock.js +141 -29
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +75 -15
- package/dist/core/mission.d.ts +83 -0
- package/dist/core/mission.d.ts.map +1 -0
- package/dist/core/mission.js +334 -0
- package/dist/core/pipeline-apply.d.ts +38 -0
- package/dist/core/pipeline-apply.d.ts.map +1 -0
- package/dist/core/pipeline-apply.js +117 -0
- package/dist/core/pipeline-io.d.ts +13 -0
- package/dist/core/pipeline-io.d.ts.map +1 -0
- package/dist/core/pipeline-io.js +64 -0
- package/dist/core/pipeline-map.d.ts +46 -0
- package/dist/core/pipeline-map.d.ts.map +1 -0
- package/dist/core/pipeline-map.js +196 -0
- package/dist/core/pipeline-spec.d.ts +109 -0
- package/dist/core/pipeline-spec.d.ts.map +1 -0
- package/dist/core/pipeline-spec.js +554 -0
- package/dist/core/ps-wrapper.d.ts +19 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +250 -62
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +130 -29
- package/dist/core/router/rules.d.ts.map +1 -1
- package/dist/core/router/rules.js +6 -0
- package/dist/core/scheduler/linux.d.ts +8 -1
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +34 -9
- package/dist/core/scheduler/mac.d.ts +44 -2
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +126 -15
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +15 -12
- package/dist/core/structured-log.d.ts +7 -1
- package/dist/core/structured-log.d.ts.map +1 -1
- package/dist/core/worktree-run.d.ts +4 -0
- package/dist/core/worktree-run.d.ts.map +1 -0
- package/dist/core/worktree-run.js +164 -0
- package/dist/core/worktree.d.ts +115 -0
- package/dist/core/worktree.d.ts.map +1 -0
- package/dist/core/worktree.js +462 -0
- package/dist/core/wrappers/bash.d.ts +17 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +175 -24
- package/dist/db/capability-repo.d.ts +43 -2
- package/dist/db/capability-repo.d.ts.map +1 -1
- package/dist/db/capability-repo.js +96 -11
- package/dist/db/history-repo.d.ts +38 -5
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +88 -25
- package/dist/db/metrics-repo.js +2 -2
- package/dist/db/recovery.d.ts.map +1 -1
- package/dist/db/recovery.js +5 -4
- package/dist/db/run-journal.d.ts +33 -5
- package/dist/db/run-journal.d.ts.map +1 -1
- package/dist/db/run-journal.js +78 -14
- package/dist/db/run-resume.d.ts +5 -0
- package/dist/db/run-resume.d.ts.map +1 -1
- package/dist/db/run-resume.js +9 -2
- package/dist/db/runs-repo.d.ts +19 -2
- package/dist/db/runs-repo.d.ts.map +1 -1
- package/dist/db/runs-repo.js +22 -6
- package/dist/db/schema.d.ts +2 -2
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +63 -2
- package/dist/history.d.ts +1 -1
- package/dist/history.d.ts.map +1 -1
- package/dist/i18n.d.ts +5 -0
- package/dist/i18n.d.ts.map +1 -1
- package/dist/i18n.js +11 -4
- package/dist/index.d.ts +136 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +378 -14
- package/dist/notifications.d.ts +22 -0
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +36 -8
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +25 -4
- package/dist/rpc.d.ts +246 -0
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +117 -0
- package/dist/server.d.ts +15 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +77 -18
- package/dist/settings.d.ts +2 -2
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +3 -3
- package/dist/shared/jobs-view.d.ts +1 -1
- package/dist/shared/jobs-view.d.ts.map +1 -1
- package/dist/shared/jobs-view.js +2 -0
- package/dist/task-transfer.d.ts +16 -0
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +16 -0
- package/docs/ARCHITECTURE.md +281 -65
- package/docs/COMPATIBILITY.md +2 -2
- package/docs/CONCEPT.md +18 -4
- package/docs/CROSS_PLATFORM.ru.md +20 -0
- package/docs/CROSS_PLATFORM.zh.md +18 -0
- package/docs/EXECUTION-LOOP.md +22 -7
- package/docs/FEATURES.md +65 -4
- package/docs/FEATURES.zh.md +52 -4
- package/docs/MIGRATION.md +2 -2
- package/docs/PIPELINE.md +293 -0
- package/docs/README.ru.md +42 -3
- package/docs/README.zh.md +43 -3
- package/docs/SAFETY.md +23 -3
- package/gui-experimental.cjs +9 -8
- package/locales/en.json +17 -1
- package/locales/ru.json +17 -1
- package/locales/zh.json +17 -1
- package/opencode.pipeline.yaml +35 -0
- package/package.json +23 -4
- package/scripts/test-home.mjs +83 -0
- package/src/cli.ts +412 -0
- package/src/core/dry-run.ts +2 -2
- package/src/core/execution.ts +538 -0
- package/src/core/file-watcher.ts +2 -2
- package/src/core/gate-integrity.ts +160 -0
- package/src/core/git-trigger.ts +18 -5
- package/src/core/guard-run.ts +119 -0
- package/src/core/guard.ts +431 -0
- package/src/core/lock.ts +178 -37
- package/src/core/matrix.ts +95 -50
- package/src/core/mission.ts +485 -0
- package/src/core/native-notify.ts +1 -1
- package/src/core/pipeline-apply.ts +158 -0
- package/src/core/pipeline-io.ts +79 -0
- package/src/core/pipeline-map.ts +264 -0
- package/src/core/pipeline-spec.ts +775 -0
- package/src/core/ps-wrapper.ts +263 -63
- package/src/core/record-history.ts +164 -77
- package/src/core/router/rules.ts +6 -0
- package/src/core/schedule-gate.ts +1 -1
- package/src/core/scheduler/at-fallback.ts +1 -1
- package/src/core/scheduler/linux.ts +40 -11
- package/src/core/scheduler/logs.ts +2 -2
- package/src/core/scheduler/mac.ts +174 -14
- package/src/core/scheduler/registry.ts +2 -2
- package/src/core/scheduler/windows.ts +19 -15
- package/src/core/secrets.ts +8 -8
- package/src/core/structured-log.ts +22 -5
- package/src/core/telegram.ts +2 -2
- package/src/core/triage-worker.ts +7 -7
- package/src/core/triage.ts +2 -2
- package/src/core/worktree-run.ts +199 -0
- package/src/core/worktree.ts +600 -0
- package/src/core/wrappers/bash.ts +190 -23
- package/src/db/capability-repo.ts +127 -10
- package/src/db/history-repo.ts +129 -22
- package/src/db/metrics-repo.ts +2 -2
- package/src/db/recovery.ts +5 -4
- package/src/db/run-journal.ts +100 -13
- package/src/db/run-resume.ts +17 -1
- package/src/db/runs-repo.ts +36 -6
- package/src/db/schema.ts +65 -2
- package/src/gui.tsx +177 -13
- package/src/history.ts +1 -1
- package/src/i18n.ts +12 -4
- package/src/index.ts +524 -4
- package/src/notifications.ts +38 -8
- package/src/profiles.ts +26 -4
- package/src/rpc.ts +128 -0
- package/src/server.ts +94 -18
- package/src/settings.ts +5 -5
- package/src/shared/jobs-view.ts +3 -1
- package/src/task-transfer.ts +31 -0
|
@@ -53,6 +53,12 @@ interface SchedulerBackend {
|
|
|
53
53
|
- 包装脚本:`run-task.ps1` 加每个任务专属的 `run-<name>.cmd`,位于 `%APPDATA%\opencode\agent-steward\wrapper`。旧的 `%APPDATA%\opencode\windows-scheduler` 目录会在首次启动时迁移。
|
|
54
54
|
- 日志:`%APPDATA%\opencode\agent-steward\logs\<name>.log`。
|
|
55
55
|
- cron 会转换成 schtasks(`convertCronToSchTasks`)——支持与之前相同的模板集合。
|
|
56
|
+
- 提示词在 `--` 之后传给 `opencode run`,因此以 `-` 开头的提示词不会被当成选项。
|
|
57
|
+
包装脚本会在 `CreateProcess` 之前拒绝超过 30 000 字符的提示词
|
|
58
|
+
(命令行上限为 32 767 字符)。
|
|
59
|
+
- 超时看门狗:通过 `Get-CimInstance` 读取进程树;如果 CIM 失败或为空,则回退到
|
|
60
|
+
`Get-WmiObject`,再检查 `tasklist`/`Get-Process`。如果完全拿不到树数据,则
|
|
61
|
+
故障关闭并执行 `taskkill /F /T /PID <root>`,避免孙进程继续运行。
|
|
56
62
|
|
|
57
63
|
### Linux
|
|
58
64
|
- 任务保存在受管 `crontab` 块中:
|
|
@@ -69,19 +75,31 @@ interface SchedulerBackend {
|
|
|
69
75
|
- 支持完整 cron 语法(与 Windows 不同),因为 crontab 原生支持。
|
|
70
76
|
- 一次性任务(`once`):使用 `at -t`;如果未安装 `at`,插件会退回到分离的 `sleep && 命令` 进程(注册表中为 `pid:<pid>`)。回退方案无法在重启后保留,建议安装 `at` 包。
|
|
71
77
|
- 删除/重建只触及自己的块,`crontab` 的其他行不受影响。
|
|
78
|
+
- 未闭合的插件块(只有开始标记)按 fail-closed 处理:插件报告错误且不重写 crontab,因此标记之后的用户行不会丢失。
|
|
72
79
|
|
|
73
80
|
### macOS
|
|
74
81
|
- 任务是 LaunchAgent plist:`~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`。
|
|
75
82
|
- 调度:`* * * * *` 和 `*/N` 使用 `StartInterval`,`M * * * *`、`M H * * *`、`M H * * D`
|
|
76
83
|
使用 `StartCalendarInterval`。
|
|
77
84
|
- 暂停 = `launchctl unload -w`,恢复 = `launchctl load -w`。
|
|
85
|
+
- 安装已暂停的任务只写入 plist,不调用 `load -w`(它会清除暂停);
|
|
86
|
+
`unload -w` 保证代理在下次登录后仍保持禁用。
|
|
87
|
+
- `launchctl load` 的错误不会被吞掉:安装/恢复失败会带上命令、退出码和
|
|
88
|
+
stderr(例如损坏的 plist 返回 `Invalid property list`)。
|
|
78
89
|
- 包装脚本与 Linux 相同的 `.sh`;配置路径:
|
|
79
90
|
`~/.config/opencode/agent-steward/`(或 `$XDG_CONFIG_HOME`)。
|
|
80
91
|
|
|
81
92
|
### 共享 POSIX 包装脚本(`.sh`)
|
|
82
93
|
- `cd` 到工作目录,用文件中的提示词执行 `opencode run`。
|
|
94
|
+
提示词位于 `--` 之后,因此开头的 `-` 不会被当作选项。
|
|
95
|
+
- argv 保护会在 `PROMPT_BYTES >= 131072` 时拒绝运行:Linux 的 `MAX_ARG_STRLEN`
|
|
96
|
+
包含结尾 NUL,因此最多只有 131 071 字节的有效负载。
|
|
83
97
|
- 日志通过 `>>` 追加,并带时间戳。
|
|
84
98
|
- 通过原子 `mkdir` 加锁——防止并行运行。
|
|
99
|
+
- Node、PS 和 bash 都将锁持有者写为 `<pid>-<iso>`;旧格式 `<iso>|<pid>`(PS)和
|
|
100
|
+
裸 `<pid>` 仍可读取,因此运行中的锁不会被另一种运行时误判为过期。
|
|
101
|
+
- 插件启动时同时读取 `<task>.lock` 与 `<task>.lock.d/pid` 的持有者:只有 PID
|
|
102
|
+
已死亡或缺失时才清理锁目录,年龄仅作为回退条件。
|
|
85
103
|
- 超时:子进程 + 看门狗(先 `TERM`,再 `KILL`)。
|
|
86
104
|
- Quality Gate:`bash -lc "<命令>"`(相当于 Windows 上的 `cmd.exe /c`)。
|
|
87
105
|
- 指标:`node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"`——
|
package/docs/EXECUTION-LOOP.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
- **Роутер не вызывается live.** `routeStep` / `decideCapabilityRoute` отсутствуют в `index.ts` / `record-history.ts`.
|
|
12
12
|
- **Карта не обучается.** `recordCapabilityOutcome` не вызывается из горячего пути.
|
|
13
13
|
- **Эскалация не живая.** `escalateAfterGate` есть, но провал гейта идёт в retry/chain.
|
|
14
|
-
- **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера.
|
|
14
|
+
- **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера. *(Закрыто в AB-8: `run_mission` / CLI `run` / GUI / RPC.)*
|
|
15
15
|
|
|
16
16
|
Не построено вовсе: ledger + provenance; класс риска и компиляция политики;
|
|
17
17
|
бюджет миссии; целостность гейта, flake-aware, отложенные эффекты; context
|
|
@@ -119,12 +119,27 @@ CREATE TABLE gate_outcomes (
|
|
|
119
119
|
|
|
120
120
|
## 4. Целостность гейта (спринт 39)
|
|
121
121
|
|
|
122
|
-
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
122
|
+
**Реализовано (G-1.2):** при создании задачи `src/core/gate-integrity.ts`
|
|
123
|
+
фиксирует snapshot входов гейта — команду/файл хука, prompt и таймаут — с
|
|
124
|
+
SHA-256 в `PLUGIN_DIR/gate-snapshots/`, вне write-scope задачи. Перед запуском
|
|
125
|
+
гейта обе обёртки (Windows и POSIX) вызывают `gate-integrity.js verify`; при
|
|
126
|
+
расхождении хэша, отсутствии или повреждении snapshot гейт не выполняется,
|
|
127
|
+
запуск переходит в `error` с сообщением «snapshot mismatch». Snapshot
|
|
128
|
+
проверяет именно определение гейта, а не исходники репозитория, которые гейт
|
|
129
|
+
тестирует.
|
|
130
|
+
|
|
131
|
+
**Обязательная тест-атака в CI:** `test-execution-hardening.mjs` (Windows) и
|
|
132
|
+
`test-posix-e2e.mjs` (macOS/Linux) подменяют сгенерированный gate-файл/команду
|
|
133
|
+
на `exit 0` после создания snapshot и требуют падения запуска; оба теста уже
|
|
134
|
+
входят в `npm test`/`test:parallel`. Юнит-проверки хэша и CLI — в
|
|
135
|
+
`test-execution-pipeline.mjs`.
|
|
136
|
+
|
|
137
|
+
**Остаётся планом:** отдельный gate-executor, `gate_outcomes` с `gate_hash`,
|
|
138
|
+
`policy_hash`, `prompt_hash` и `prev_hash` в ledger, аудит-инцидент при
|
|
139
|
+
расхождении и перенос gate-файлов под привилегии, отличные от пользовательских.
|
|
140
|
+
Гейт по-прежнему **всегда hard**; shadow/canary — только для маршрутов и
|
|
141
|
+
адаптеров (49). Подмена самих тестов агентом текущей мерой не детектируется —
|
|
142
|
+
защита ограничена целостностью определения гейта.
|
|
128
143
|
|
|
129
144
|
## 5. Отложенные внешние эффекты
|
|
130
145
|
|
package/docs/FEATURES.md
CHANGED
|
@@ -259,6 +259,41 @@ not to hooks, Quality Gates or scripts, which still run with your user privilege
|
|
|
259
259
|
for the exact action mapping and known limitations (project/system config, nested
|
|
260
260
|
subagents).
|
|
261
261
|
|
|
262
|
+
### One-off git worktree (W-1)
|
|
263
|
+
|
|
264
|
+
Set `worktree: true` to run every tick in a fresh `git worktree` of
|
|
265
|
+
`workingDirectory` on its own `agent-steward/...` branch. The wrapper creates the
|
|
266
|
+
worktree after the schedule gate and before `opencode`, passes the path to the agent
|
|
267
|
+
through the prompt preamble and `AGENT_STEWARD_WORKTREE`, and fails the run closed
|
|
268
|
+
if creation fails (for example, the directory is not a git repository). Paths and
|
|
269
|
+
branches are unique per run, so matrix clones and parallel missions can write files
|
|
270
|
+
without touching the main checkout or each other — safe fan-out without Docker.
|
|
271
|
+
|
|
272
|
+
Worktrees live under `PLUGIN_DIR/worktrees` with a `.json` sidecar used by cleanup.
|
|
273
|
+
After the run the wrapper removes the worktree and its `agent-steward/...` branch
|
|
274
|
+
even when the task fails (W-2.1). Leftovers from crashes are swept opportunistically
|
|
275
|
+
on the next run: worktrees older than 24 hours are removed, sidecars without a
|
|
276
|
+
checkout are pruned, and a `.cleanup-lock` serialises concurrent sweeps (W-2.2).
|
|
277
|
+
Cleanup only touches paths under the worktree root that have a sidecar and an
|
|
278
|
+
`agent-steward/` branch, so foreign directories and fresh active runs are never
|
|
279
|
+
deleted. A worktree does not isolate network, API or database access, and Quality
|
|
280
|
+
Gates still run with your user privileges.
|
|
281
|
+
|
|
282
|
+
### Guard conditions (W-3)
|
|
283
|
+
|
|
284
|
+
Set `guards` on a task to require conditions before it runs: an optional shell
|
|
285
|
+
`command` (exit 0 — пройден, non-zero — скип, `timeoutSeconds` 1..3600) and/or
|
|
286
|
+
`semantic` conditions — `filesExist` / `filesMissing` (relative paths, resolved
|
|
287
|
+
inside the worktree or cwd), `branch` (glob), and `changedPaths` (glob, at least
|
|
288
|
+
one path in the diff of `changedSince..HEAD`, default `HEAD~1`). All conditions
|
|
289
|
+
are ANDed: when any check fails or errors, the run is skipped gracefully with a
|
|
290
|
+
visible `skipped` status in history and the GUI (`record-history --skip`, no
|
|
291
|
+
notification and no success/error chain). Guards are evaluated after the
|
|
292
|
+
worktree is created, so they run inside the fresh worktree when combined with
|
|
293
|
+
`worktree: true`; the `guard-run.js` helper lives in `src/core/guard-run.ts` and
|
|
294
|
+
`src/core/guard.ts` provides normalization, evaluation and the exit-code
|
|
295
|
+
convention (4 = skip).
|
|
296
|
+
|
|
262
297
|
## Orchestration
|
|
263
298
|
|
|
264
299
|
### Chains
|
|
@@ -323,6 +358,21 @@ Behavior worth knowing:
|
|
|
323
358
|
- `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
|
|
324
359
|
gone; the same cleanup also runs at plugin startup.
|
|
325
360
|
|
|
361
|
+
### Pipeline as code
|
|
362
|
+
|
|
363
|
+
A whole DAG can be declared in `opencode.pipeline.yaml` and applied as code:
|
|
364
|
+
|
|
365
|
+
- `version: 1`, a pipeline `name`, optional `defaults` and 1..200 `steps`.
|
|
366
|
+
- Each step has a stable `id`, a `prompt` and an optional `needs` list that becomes
|
|
367
|
+
`dependsOn`.
|
|
368
|
+
- `trigger: cron` (default) needs a `schedule`; `trigger: once` needs `runAt`;
|
|
369
|
+
`trigger: dag` runs only after its `needs` succeed.
|
|
370
|
+
- `matrix.workspaces` fans a step out over workspace names or ids.
|
|
371
|
+
- `agent-steward pipeline validate|apply|export` and the `pipeline_validate`,
|
|
372
|
+
`pipeline_apply`, `pipeline_export` tools cover the lifecycle; apply is idempotent,
|
|
373
|
+
skips unchanged steps and never deletes stale tasks.
|
|
374
|
+
- Full format and limits: [PIPELINE.md](PIPELINE.md).
|
|
375
|
+
|
|
326
376
|
## Multi-repository workspaces
|
|
327
377
|
|
|
328
378
|
A workspace is a named directory: id, name, path, optional git remote and color.
|
|
@@ -348,7 +398,9 @@ This is useful for separating projects, clients or environments (e.g. `default`
|
|
|
348
398
|
in the base directory → `default`. Switching profiles writes the marker and requires
|
|
349
399
|
an OpenCode restart because plugin directories are resolved at module load time.
|
|
350
400
|
- Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
|
|
351
|
-
`profile.json` → server default (3782, then 4782/5782 fallback).
|
|
401
|
+
`profile.json` → server default (3782, then 4782/5782 fallback). A new profile is
|
|
402
|
+
allocated the first free port from 3783 up, skipping 3782/4782, ports already
|
|
403
|
+
recorded in other profiles' `profile.json`, and `OPENCODE_SCHEDULER_PORT`.
|
|
352
404
|
- RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
|
|
353
405
|
`set_profile` switches the active profile (restart hint); `create_profile` /
|
|
354
406
|
`delete_profile` manage named profiles (`default` cannot be deleted).
|
|
@@ -474,6 +526,12 @@ agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
|
|
|
474
526
|
`dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
|
|
475
527
|
fan-out and estimated time. Nothing is executed and nothing is created.
|
|
476
528
|
|
|
529
|
+
The ad-hoc mission API (`runMission` / `agent-steward run --dry-run`) has its own
|
|
530
|
+
`dryRun` contract: it builds the step plan and its description, but does not acquire
|
|
531
|
+
the `activeWorkspaces` lock and does not write `runs`/`run_steps` to the ledger.
|
|
532
|
+
This is intentional — several dry runs in the same `cwd` run in parallel and leave
|
|
533
|
+
no trace in history. Only a real mission is locked to one workspace at a time.
|
|
534
|
+
|
|
477
535
|
### Dashboard
|
|
478
536
|
|
|
479
537
|
A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
|
|
@@ -610,14 +668,15 @@ the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
|
|
|
610
668
|
|
|
611
669
|
## Agent interface
|
|
612
670
|
|
|
613
|
-
Twenty-
|
|
671
|
+
Twenty-nine tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
|
|
614
672
|
`run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
|
|
615
673
|
`manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
|
|
616
674
|
`get_analytics`, `self_analysis` (health score, anomalies, trends), `manage_settings`,
|
|
617
675
|
`manage_local_ai`, `manage_templates`, `manage_profiles`,
|
|
618
676
|
`transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
|
|
619
677
|
`manage_secrets`, `get_audit_log`,
|
|
620
|
-
`emit_event
|
|
678
|
+
`emit_event`,
|
|
679
|
+
`pipeline_validate`, `pipeline_apply`, `pipeline_export`.
|
|
621
680
|
|
|
622
681
|
A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
|
|
623
682
|
least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
|
|
@@ -654,7 +713,9 @@ It never changes run status, retries, Quality Gates, DAG dependencies or history
|
|
|
654
713
|
messages are converted to normalized bag-of-words vectors stored in SQLite,
|
|
655
714
|
compared by cosine similarity against the window, and suppressed above
|
|
656
715
|
`threshold` (0.85 default). Important statuses are never suppressed. No new
|
|
657
|
-
dependencies and no external embedding model are required.
|
|
716
|
+
dependencies and no external embedding model are required. CJK text (Chinese,
|
|
717
|
+
Japanese, Korean) is tokenized into overlapping bigrams, so messages without
|
|
718
|
+
spaces produce non-zero vectors and participate in dedup too.
|
|
658
719
|
- `notifications.summary` renders at most three short lines for Telegram and
|
|
659
720
|
toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
|
|
660
721
|
back to deterministic truncation (status, error, runtime/tokens/cost), and
|
package/docs/FEATURES.zh.md
CHANGED
|
@@ -221,6 +221,36 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
221
221
|
嵌套子代理)见
|
|
222
222
|
[ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)。
|
|
223
223
|
|
|
224
|
+
### 一次性 git worktree(W-1)
|
|
225
|
+
|
|
226
|
+
设置 `worktree: true` 后,每次运行都会在 `workingDirectory` 的全新 `git worktree`
|
|
227
|
+
中执行,并使用独立的 `agent-steward/...` 分支。包装脚本在调度门禁之后、启动
|
|
228
|
+
`opencode` 之前创建 worktree,通过提示词前导和 `AGENT_STEWARD_WORKTREE` 把路径传给
|
|
229
|
+
Agent;创建失败时(例如目录不是 git 仓库)运行会 fail-closed 终止。每次运行的路径和
|
|
230
|
+
分支都唯一,因此矩阵克隆和并行任务可以各自写文件,互不影响主工作区和彼此——无需
|
|
231
|
+
Docker 即可安全扇出。
|
|
232
|
+
|
|
233
|
+
Worktree 位于 `PLUGIN_DIR/worktrees`,旁边的 `.json` sidecar 用于清理。运行结束后,
|
|
234
|
+
包装脚本会删除 worktree 及其 `agent-steward/...` 分支,任务失败时也会删除(W-2.1)。
|
|
235
|
+
崩溃留下的残留会在下一次运行时顺带清扫:超过 24 小时的 worktree 被删除,没有工作
|
|
236
|
+
副本的 sidecar 被清理,`.cleanup-lock` 串行化并发清扫(W-2.2)。清理只处理 worktree
|
|
237
|
+
根目录下带 sidecar 且分支为 `agent-steward/` 的路径,因此不会删除外来目录和正在
|
|
238
|
+
运行的 worktree。worktree 不隔离网络、API 或数据库访问,Quality Gate 仍以你的
|
|
239
|
+
用户权限运行。
|
|
240
|
+
|
|
241
|
+
### Guard 条件(W-3)
|
|
242
|
+
|
|
243
|
+
可以为任务设置 `guards` — 运行前必须满足的条件:可选的 shell `command`
|
|
244
|
+
(exit 0 表示通过,非 0 表示跳过,`timeoutSeconds` 1..3600)和/或 `semantic`
|
|
245
|
+
条件 — `filesExist` / `filesMissing`(相对路径,在 worktree 或 cwd 内解析)、
|
|
246
|
+
`branch`(glob)和 `changedPaths`(glob;`changedSince..HEAD` 的 diff 中至少
|
|
247
|
+
匹配一个路径,默认 `HEAD~1`)。所有条件按「与」组合:任一检查失败或出错时,
|
|
248
|
+
运行会被优雅跳过,并在历史记录和 GUI 中显示为可见的 `skipped` 状态
|
|
249
|
+
(`record-history --skip`;不发送通知、不触发成功/错误链)。检查在创建
|
|
250
|
+
worktree 之后执行,因此与 `worktree: true` 组合时它们在新 worktree 内运行;
|
|
251
|
+
`guard-run.js` 帮助程序位于 `src/core/guard-run.ts`,`src/core/guard.ts`
|
|
252
|
+
提供规范化、求值和退出码约定(4 = 跳过)。
|
|
253
|
+
|
|
224
254
|
## 编排
|
|
225
255
|
|
|
226
256
|
### 链式调度
|
|
@@ -283,6 +313,20 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
283
313
|
- `matrix_control` 的 `action: "cleanup"` 会移除父任务已不存在的孤立
|
|
284
314
|
克隆;同样的清理也会在插件启动时运行。
|
|
285
315
|
|
|
316
|
+
### 流水线即代码
|
|
317
|
+
|
|
318
|
+
整个 DAG 可以声明在 `opencode.pipeline.yaml` 中并按代码应用:
|
|
319
|
+
|
|
320
|
+
- `version: 1`、流水线 `name`、可选的 `defaults` 和 1..200 个 `steps`。
|
|
321
|
+
- 每个步骤有稳定的 `id`、`prompt` 和可选的 `needs`(转换为 `dependsOn`)。
|
|
322
|
+
- `trigger: cron`(默认)需要 `schedule`;`trigger: once` 需要 `runAt`;
|
|
323
|
+
`trigger: dag` 只在其 `needs` 成功后运行。
|
|
324
|
+
- `matrix.workspaces` 按 workspace 名称或 id 将步骤扇出。
|
|
325
|
+
- `agent-steward pipeline validate|apply|export` 与 `pipeline_validate`、
|
|
326
|
+
`pipeline_apply`、`pipeline_export` 工具覆盖整个生命周期;apply 幂等、
|
|
327
|
+
跳过未变化的步骤,且从不删除 stale 任务。
|
|
328
|
+
- 完整格式与限制:[PIPELINE.md](PIPELINE.md)。
|
|
329
|
+
|
|
286
330
|
## 多仓库工作区
|
|
287
331
|
|
|
288
332
|
工作区是一个命名目录:id、name、path、可选的 git 远程仓库和颜色。
|
|
@@ -308,7 +352,9 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
308
352
|
`active-profile` 文件 → `default`。切换配置档案会写入标记文件,并且需要
|
|
309
353
|
重启 OpenCode,因为插件目录在模块加载时解析。
|
|
310
354
|
- 每个配置档案的仪表板端口:`OPENCODE_SCHEDULER_PORT` 环境变量 → 来自
|
|
311
|
-
`profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782
|
|
355
|
+
`profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。新配置档案
|
|
356
|
+
会分配 3783 起的第一个空闲端口,跳过 3782/4782、其他配置档案 `profile.json`
|
|
357
|
+
中已记录的端口以及 `OPENCODE_SCHEDULER_PORT`。
|
|
312
358
|
- RPC:`get_profiles` 列出配置档案及其目录、端口和活动标志;
|
|
313
359
|
`set_profile` 切换活动配置档案(会提示重启);`create_profile` /
|
|
314
360
|
`delete_profile` 管理命名配置档案(`default` 不能被删除)。
|
|
@@ -566,14 +612,14 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
566
612
|
|
|
567
613
|
## Agent 接口
|
|
568
614
|
|
|
569
|
-
|
|
615
|
+
二十九个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
|
|
570
616
|
`run_task_now`、`pause_task`、`resume_task`、`get_history`、`get_task_logs`、`dry_run`、
|
|
571
617
|
`manage_workspaces`、`matrix_control`(results/cancel/cleanup/preview)、`get_metrics`、
|
|
572
618
|
`get_analytics`、`self_analysis`(健康评分、异常、趋势)、`manage_settings`、
|
|
573
619
|
`manage_local_ai`、`manage_templates`、`manage_profiles`、
|
|
574
620
|
`transfer_tasks`、`send_notification`、`get_dashboard_info`、`cleanup_history`、
|
|
575
621
|
`manage_secrets`、`get_audit_log`、
|
|
576
|
-
`emit_event`。
|
|
622
|
+
`emit_event`、`pipeline_validate`、`pipeline_apply`、`pipeline_export`。
|
|
577
623
|
|
|
578
624
|
捆绑的 skill `scheduled-job-best-practices` 教会 agent 安全的默认做法:
|
|
579
625
|
最小权限、Quality Gate、超时、矩阵并发、DAG 规则以及
|
|
@@ -611,7 +657,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
611
657
|
在窗口内按余弦相似度比较,超过
|
|
612
658
|
`threshold`(默认 0.85)时被抑制。重要状态
|
|
613
659
|
永远不会被抑制。不需要新依赖,也不需要外部
|
|
614
|
-
嵌入模型。
|
|
660
|
+
嵌入模型。CJK 文本(中文、日文、韩文)按重叠的
|
|
661
|
+
二元组切分,因此没有空格的消息也会得到非零向量
|
|
662
|
+
并参与去重。
|
|
615
663
|
- `notifications.summary` 为 Telegram 和
|
|
616
664
|
toast 最多渲染三行短文本。模型返回严格的 JSON
|
|
617
665
|
`{"lines": [...]}`;任何失败都会回退到确定性截断(状态、
|
package/docs/MIGRATION.md
CHANGED
|
@@ -27,8 +27,8 @@ timers, launchd, Windows Task Scheduler, or another scheduler plugin.
|
|
|
27
27
|
automatically; on V1 restart it). If OpenCode's built-in
|
|
28
28
|
schedules are enabled, disable them so two schedulers do not run the same work.
|
|
29
29
|
|
|
30
|
-
2. **Check Node.** `node --version` must be
|
|
31
|
-
|
|
30
|
+
2. **Check Node.** `node --version` must be 22.22+ (the built-in SQLite driver and
|
|
31
|
+
chokidar 6 require 22.22+; Node 24 recommended).
|
|
32
32
|
|
|
33
33
|
3. **Inventory the old jobs.** For each job write down: name, schedule, command,
|
|
34
34
|
working directory, environment variables, timeout, and what "success" means. The
|
package/docs/PIPELINE.md
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
# Pipeline as code
|
|
2
|
+
|
|
3
|
+
`opencode.pipeline.yaml` describes a whole workflow — triggers, DAG dependencies,
|
|
4
|
+
defaults and matrix fan-out — as one reviewable file. The scheduler validates it,
|
|
5
|
+
turns every step into a task, and applies it idempotently.
|
|
6
|
+
|
|
7
|
+
- [File format](#file-format)
|
|
8
|
+
- [Steps and dependencies](#steps-and-dependencies)
|
|
9
|
+
- [Triggers](#triggers)
|
|
10
|
+
- [Defaults](#defaults)
|
|
11
|
+
- [Matrix fan-out](#matrix-fan-out)
|
|
12
|
+
- [Validate, apply, export](#validate-apply-export)
|
|
13
|
+
- [Apply semantics](#apply-semantics)
|
|
14
|
+
- [Agent tools](#agent-tools)
|
|
15
|
+
- [Validation rules](#validation-rules)
|
|
16
|
+
- [Limitations](#limitations)
|
|
17
|
+
|
|
18
|
+
A ready-to-run example lives in [`opencode.pipeline.yaml`](../opencode.pipeline.yaml).
|
|
19
|
+
|
|
20
|
+
## File format
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
version: 1
|
|
24
|
+
name: nightly-release
|
|
25
|
+
description: Lint, test and build the repository every night.
|
|
26
|
+
|
|
27
|
+
defaults:
|
|
28
|
+
timeoutSeconds: 1800
|
|
29
|
+
retryCount: 1
|
|
30
|
+
retryDelay: 120
|
|
31
|
+
|
|
32
|
+
steps:
|
|
33
|
+
- id: lint
|
|
34
|
+
schedule: "0 2 * * *"
|
|
35
|
+
prompt: Run the linter and fix what it reports.
|
|
36
|
+
qualityGate: npm run lint
|
|
37
|
+
|
|
38
|
+
- id: test
|
|
39
|
+
needs: [lint]
|
|
40
|
+
trigger: dag
|
|
41
|
+
prompt: Run the tests and fix failures.
|
|
42
|
+
qualityGate: npm test
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| Field | Required | Meaning |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| `version` | yes | Format version. Must be `1`. |
|
|
48
|
+
| `name` | yes | Pipeline name, 1–120 characters: letters, digits, space, `.`, `_`, `-`. |
|
|
49
|
+
| `description` | no | Free-form text for humans. |
|
|
50
|
+
| `defaults` | no | Values inherited by every step (see [Defaults](#defaults)). |
|
|
51
|
+
| `steps` | yes | 1–200 steps. |
|
|
52
|
+
|
|
53
|
+
Every step becomes a scheduler task. Unless the step sets `name`, the task is named
|
|
54
|
+
`<pipeline> <step id>` — for example `nightly-release test`. The name must pass the
|
|
55
|
+
normal task-name rules (letters, digits, space, `.`, `_`, `-`), so keep pipeline names
|
|
56
|
+
and step ids reasonably short.
|
|
57
|
+
|
|
58
|
+
## Steps and dependencies
|
|
59
|
+
|
|
60
|
+
| Field | Type | Meaning |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `id` | string | Stable step identifier, 1–64 characters. Unique within the pipeline, case-insensitive. |
|
|
63
|
+
| `name` | string | Task name override. Default: `<pipeline> <id>`. |
|
|
64
|
+
| `prompt` | string | Agent prompt. Required and non-empty. |
|
|
65
|
+
| `needs` | string[] | Step ids that must finish successfully first. Becomes `dependsOn`. |
|
|
66
|
+
| `schedule` | string | Cron expression for `trigger: cron`. |
|
|
67
|
+
| `trigger` | enum | `cron` (default), `once`, `dag`, `file`, `git`, `mcp-event`. |
|
|
68
|
+
| `runAt` | string | ISO-8601 start time for `trigger: once`. |
|
|
69
|
+
| `qualityGate` | string | Command that decides whether the run is successful. |
|
|
70
|
+
| `beforeScript` / `afterScript` | string | Hooks around the agent run. |
|
|
71
|
+
| `model` | string | `provider/model` (optionally `provider/model#variant`). |
|
|
72
|
+
| `priority` | integer | 0–10, higher runs first. |
|
|
73
|
+
| `timeoutSeconds` | integer | Hard timeout, at least 1. |
|
|
74
|
+
| `retryCount` / `retryDelay` | integer | Retries (≥ 0) and delay between them. |
|
|
75
|
+
| `workingDirectory` | string | Run directory for the step. |
|
|
76
|
+
| `workspaceId` | string | Run inside a workspace. Cannot be combined with `matrix`. |
|
|
77
|
+
| `allowedTools` / `deniedTools` | string[] | Per-step tool policy. A non-empty `allowedTools` is an allowlist. |
|
|
78
|
+
| `matrix` | object | Fan the step out over workspaces (see [Matrix fan-out](#matrix-fan-out)). |
|
|
79
|
+
| `timezone` | string | IANA timezone, e.g. `Europe/Moscow`. |
|
|
80
|
+
| `notBefore` / `notAfter` | string | Launch window as `HH:MM`; `notAfter` may be earlier (crosses midnight). |
|
|
81
|
+
| `activeDays` | integer[] | Allowed weekdays, `0` = Sunday. |
|
|
82
|
+
| `windowPolicy` | enum | `skip`, `postpone` (default) or `run` outside the window. |
|
|
83
|
+
|
|
84
|
+
Dependencies are declarative: a step listed in `needs` starts only after every
|
|
85
|
+
dependency's latest run succeeded. Cycles, unknown ids and self-references are rejected
|
|
86
|
+
before anything is created.
|
|
87
|
+
|
|
88
|
+
A step that has no trigger of its own uses `trigger: dag`:
|
|
89
|
+
|
|
90
|
+
```yaml
|
|
91
|
+
steps:
|
|
92
|
+
- id: lint
|
|
93
|
+
schedule: "0 2 * * *"
|
|
94
|
+
prompt: Lint the repository.
|
|
95
|
+
|
|
96
|
+
- id: test
|
|
97
|
+
needs: [lint]
|
|
98
|
+
trigger: dag
|
|
99
|
+
prompt: Run the tests.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`dag` steps are stored as dependency-only tasks (`triggerType: "file"` with an empty
|
|
103
|
+
schedule), just like matrix parents: the DAG engine starts them, not the OS scheduler.
|
|
104
|
+
They must have a non-empty `needs`; otherwise they would never run.
|
|
105
|
+
|
|
106
|
+
## Triggers
|
|
107
|
+
|
|
108
|
+
| `trigger` | Requires | Behaviour |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| `cron` (default) | `schedule` in the step or defaults | Registered with the native OS scheduler. |
|
|
111
|
+
| `once` | `runAt` (ISO-8601) | Runs once at the given moment; `schedule` is ignored. |
|
|
112
|
+
| `dag` | non-empty `needs` | Started by the DAG engine after dependencies succeed; `schedule` is ignored. |
|
|
113
|
+
| `file`, `git`, `mcp-event` | — | Accepted by the validator, but see [Limitations](#limitations). |
|
|
114
|
+
|
|
115
|
+
Cron expressions use the same parser as regular tasks: five fields, lists, ranges,
|
|
116
|
+
steps, month and weekday names, `@every 15m`, `L` and `FRI#3`. The validator calls that
|
|
117
|
+
parser, so an invalid expression is reported before apply.
|
|
118
|
+
|
|
119
|
+
A one-shot pipeline step:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
steps:
|
|
123
|
+
- id: deploy
|
|
124
|
+
trigger: once
|
|
125
|
+
runAt: "2026-11-20T22:40:00+03:00"
|
|
126
|
+
prompt: Deploy the current main branch.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Defaults
|
|
130
|
+
|
|
131
|
+
`defaults` is inherited by every step that does not set the field itself. Supported
|
|
132
|
+
keys: `schedule`, `trigger`, `model`, `priority`, `timeoutSeconds`, `workingDirectory`,
|
|
133
|
+
`retryCount`, `retryDelay`, `allowedTools`, `deniedTools`, `timezone`.
|
|
134
|
+
|
|
135
|
+
Defaults do not include `matrix`, quality gates, hooks, launch windows or
|
|
136
|
+
`workspaceId` — set those per step. Unknown keys under `defaults` produce warnings so
|
|
137
|
+
typos are visible.
|
|
138
|
+
|
|
139
|
+
## Matrix fan-out
|
|
140
|
+
|
|
141
|
+
A step with `matrix` becomes a matrix parent: one clone per workspace, with the same
|
|
142
|
+
strategy, failure mode, concurrency and aggregation as a regular matrix task.
|
|
143
|
+
|
|
144
|
+
```yaml
|
|
145
|
+
steps:
|
|
146
|
+
- id: deploy
|
|
147
|
+
schedule: "0 3 * * *"
|
|
148
|
+
prompt: Build, test and deploy this repository.
|
|
149
|
+
matrix:
|
|
150
|
+
workspaces: [frontend, backend]
|
|
151
|
+
strategy: parallel
|
|
152
|
+
failureMode: continue
|
|
153
|
+
concurrency: 2
|
|
154
|
+
aggregation: summary
|
|
155
|
+
createAggregator: true
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
| `matrix` field | Default | Meaning |
|
|
159
|
+
| --- | --- | --- |
|
|
160
|
+
| `workspaces` | required | Workspace names or ids; non-empty and unique. |
|
|
161
|
+
| `strategy` | `parallel` | `sequential` starts the next clone after the previous one. |
|
|
162
|
+
| `failureMode` | `continue` | `stop` cancels the remaining clones after the first failure. |
|
|
163
|
+
| `concurrency` | unlimited | Maximum clones running at once. |
|
|
164
|
+
| `aggregation` | `summary` | `summary` writes one aggregate record for the parent. |
|
|
165
|
+
| `createAggregator` | `false` | Also create `<parent>-matrix-complete`. |
|
|
166
|
+
|
|
167
|
+
Workspace names are resolved when the file is applied. An unknown name produces a
|
|
168
|
+
warning and the step is rejected at apply time, so create workspaces first (or use
|
|
169
|
+
their ids). `matrix` cannot be combined with `workspaceId` on the same step.
|
|
170
|
+
|
|
171
|
+
## Validate, apply, export
|
|
172
|
+
|
|
173
|
+
The CLI ships with the package (`agent-steward` binary):
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
agent-steward pipeline validate opencode.pipeline.yaml
|
|
177
|
+
agent-steward pipeline apply opencode.pipeline.yaml --dry-run
|
|
178
|
+
agent-steward pipeline apply opencode.pipeline.yaml
|
|
179
|
+
agent-steward pipeline export --pipeline nightly-release
|
|
180
|
+
agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
| Command | Flags | Result |
|
|
184
|
+
| --- | --- | --- |
|
|
185
|
+
| `pipeline validate <file>` | `--json` | Parses and validates; never changes tasks. |
|
|
186
|
+
| `pipeline apply <file>` | `--dry-run`, `--json` | Creates and updates tasks; `--dry-run` only prints the plan. |
|
|
187
|
+
| `pipeline export` | `--pipeline <name>`, `--out <file>` | Rebuilds YAML from tasks; stdout unless `--out` is given. |
|
|
188
|
+
|
|
189
|
+
Exit codes: `0` success, `1` validation/apply errors (or an unknown pipeline on export),
|
|
190
|
+
`2` bad arguments. Human-readable output is in Russian; add `--json` for stable machine
|
|
191
|
+
output.
|
|
192
|
+
|
|
193
|
+
`validate --json` returns:
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{ "ok": true, "errors": [], "warnings": [], "steps": 3 }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`apply --json` returns the plan summary:
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"pipeline": "nightly-release",
|
|
204
|
+
"dryRun": false,
|
|
205
|
+
"creates": ["nightly-release build"],
|
|
206
|
+
"updates": ["nightly-release test"],
|
|
207
|
+
"unchanged": ["nightly-release lint"],
|
|
208
|
+
"stale": []
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Apply semantics
|
|
213
|
+
|
|
214
|
+
Apply is a three-way diff, not a blind rewrite:
|
|
215
|
+
|
|
216
|
+
1. Tasks of this pipeline are matched by the `pipelineName` + `pipelineStepId` markers
|
|
217
|
+
stored in their definition. Matching is case-insensitive.
|
|
218
|
+
2. A step with no matching task is **created**.
|
|
219
|
+
3. A step whose significant fields changed is **updated**; the comparison covers the
|
|
220
|
+
schedule, prompt, trigger, DAG dependencies, model, matrix, gates, hooks, tool
|
|
221
|
+
policy, launch window and pipeline markers.
|
|
222
|
+
4. A step with an identical definition is **unchanged** and untouched.
|
|
223
|
+
5. A task of the same pipeline that is no longer in the file is reported as **stale**.
|
|
224
|
+
It is never deleted automatically — delete it manually or return the step to the
|
|
225
|
+
file.
|
|
226
|
+
|
|
227
|
+
Tasks that do not carry pipeline markers are never read, updated or deleted by apply.
|
|
228
|
+
Running `apply` twice in a row is safe: the second run reports `unchanged` for every
|
|
229
|
+
step.
|
|
230
|
+
|
|
231
|
+
Renaming `name` starts a new pipeline identity. The old tasks keep their old marker, so
|
|
232
|
+
they are not matched, not reported as stale and must be removed by hand.
|
|
233
|
+
|
|
234
|
+
`export` reverses the mapping: it restores `needs` from `dependsOn`,
|
|
235
|
+
`matrix.workspaces` from `matrix.workspaceIds`, and the trigger from `triggerType`.
|
|
236
|
+
A `file` task with no schedule, no watch path and non-empty `dependsOn` is exported as
|
|
237
|
+
`trigger: dag`. Dependencies that point outside the pipeline are dropped with a
|
|
238
|
+
warning, and the default `<pipeline> <step>` name is omitted.
|
|
239
|
+
|
|
240
|
+
## Agent tools
|
|
241
|
+
|
|
242
|
+
| Tool | Arguments | What it does |
|
|
243
|
+
| --- | --- | --- |
|
|
244
|
+
| `pipeline_validate` | `path?`, `source?` | Validates a file or inline YAML. Returns pipeline name, step count, errors and warnings. |
|
|
245
|
+
| `pipeline_apply` | `path?`, `source?`, `dryRun?` | Idempotent create/update. `dryRun: true` only reports the diff. |
|
|
246
|
+
| `pipeline_export` | `pipeline` | Returns the pipeline as YAML plus warnings. |
|
|
247
|
+
|
|
248
|
+
`pipeline_apply` writes an audit record with action `pipeline.apply`. Pass either
|
|
249
|
+
`path` or `source`; with neither, the tool returns an explicit error.
|
|
250
|
+
|
|
251
|
+
## Validation rules
|
|
252
|
+
|
|
253
|
+
Validation never throws: it returns `{ ok, errors, warnings }`, where every issue has a
|
|
254
|
+
`path` such as `steps[2].schedule` and a human-readable message. Errors block apply;
|
|
255
|
+
warnings do not.
|
|
256
|
+
|
|
257
|
+
| Area | Rule |
|
|
258
|
+
| --- | --- |
|
|
259
|
+
| Format | YAML up to 1 MiB, duplicate keys rejected, aliases limited to 100. |
|
|
260
|
+
| `version` | Exactly `1`. |
|
|
261
|
+
| `name` | Non-empty, ≤ 120 characters, no control characters, limited alphabet. |
|
|
262
|
+
| `steps` | 1–200 entries. |
|
|
263
|
+
| Step `id` | Non-empty, ≤ 64 characters, must start with a letter or digit, then letters, digits, `.`, `_`, `-`; unique case-insensitively. |
|
|
264
|
+
| `prompt` | Non-empty. |
|
|
265
|
+
| Task name | Explicit `name` must pass task-name validation; generated names must not collide case-insensitively. |
|
|
266
|
+
| `needs` | No duplicates, no self-reference, every id must exist, no cycles. |
|
|
267
|
+
| Cron | A cron step needs `schedule`; the expression must parse with the shared cron parser. |
|
|
268
|
+
| `once` | `runAt` must be valid ISO-8601. |
|
|
269
|
+
| `dag` | `needs` must be non-empty; `schedule` is ignored with a warning. |
|
|
270
|
+
| Other triggers | `schedule` on `file`, `git` or `mcp-event` is ignored with a warning. |
|
|
271
|
+
| Numbers | `priority` 0–10; `timeoutSeconds` ≥ 1; `retryCount` and `retryDelay` are non-negative integers; `concurrency` ≥ 1. |
|
|
272
|
+
| Tools | `allowedTools` must be a non-empty array of non-empty strings; `deniedTools` must be an array of strings. |
|
|
273
|
+
| Matrix | `workspaces` non-empty and unique; valid enum values; no `workspaceId` on the same step. |
|
|
274
|
+
| Timezone | Valid IANA zone name. |
|
|
275
|
+
| Window | `notBefore`/`notAfter` valid `HH:MM`; `activeDays` integers 0–6; `windowPolicy` one of the enum values. |
|
|
276
|
+
| Unknown keys | Reported as warnings at the root, in `defaults`, in a step and in `matrix`. |
|
|
277
|
+
|
|
278
|
+
## Limitations
|
|
279
|
+
|
|
280
|
+
- **File, git and MCP-event triggers are not fully expressible yet.** The validator
|
|
281
|
+
accepts the trigger names, but the format has no fields for `watchPath`, globs, git
|
|
282
|
+
filters or an MCP event name. Use `schedule_task` / `update_task` for those tasks in
|
|
283
|
+
v1.
|
|
284
|
+
- **No automatic deletion.** Removed steps stay as stale tasks on purpose, so a bad
|
|
285
|
+
edit cannot destroy a working schedule. Clean them up by hand.
|
|
286
|
+
- **Not in the format yet:** session continuity (`session` / `sessionMaxRuns`), `env`
|
|
287
|
+
and secrets, chains (`nextTaskOnSuccess` / `nextTaskOnError`), incoming webhooks,
|
|
288
|
+
`runWhenLoggedOff`, `paused`, and per-workspace matrix `overrides`. Use
|
|
289
|
+
`schedule_task` for those, or manage them after apply.
|
|
290
|
+
- **One profile at a time.** Apply and export work against the active profile's
|
|
291
|
+
database.
|
|
292
|
+
- **A pipeline is identified by `name`.** Treat the name as an immutable key; renaming
|
|
293
|
+
it leaves the old task family behind.
|