agent-steward 0.0.4 → 0.0.6
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 +309 -2
- package/CROSS_PLATFORM.md +19 -0
- package/README.md +55 -8
- package/ROADMAP-STRATEGY.md +22 -19
- package/ROADMAP.md +230 -159
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +356 -0
- package/dist/core/analytics.d.ts +6 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +20 -3
- package/dist/core/audit.d.ts +6 -0
- package/dist/core/audit.d.ts.map +1 -1
- package/dist/core/audit.js +24 -0
- package/dist/core/budget.d.ts +118 -0
- package/dist/core/budget.d.ts.map +1 -0
- package/dist/core/budget.js +206 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -1
- package/dist/core/cron-to-schtasks.js +38 -0
- package/dist/core/dry-run.d.ts +26 -1
- package/dist/core/dry-run.d.ts.map +1 -1
- package/dist/core/dry-run.js +199 -8
- 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/feedback.d.ts +192 -0
- package/dist/core/feedback.d.ts.map +1 -0
- package/dist/core/feedback.js +426 -0
- package/dist/core/gate-integrity.d.ts +71 -0
- package/dist/core/gate-integrity.d.ts.map +1 -0
- package/dist/core/gate-integrity.js +275 -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/local-ai.d.ts.map +1 -1
- package/dist/core/local-ai.js +7 -3
- 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 +8 -0
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +132 -17
- package/dist/core/mission.d.ts +103 -0
- package/dist/core/mission.d.ts.map +1 -0
- package/dist/core/mission.js +374 -0
- package/dist/core/opencode-models.d.ts +2 -2
- package/dist/core/opencode-models.d.ts.map +1 -1
- package/dist/core/opencode-models.js +28 -21
- package/dist/core/opencode-usage.d.ts +35 -0
- package/dist/core/opencode-usage.d.ts.map +1 -0
- package/dist/core/opencode-usage.js +132 -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 +78 -0
- package/dist/core/pipeline-map.d.ts +52 -0
- package/dist/core/pipeline-map.d.ts.map +1 -0
- package/dist/core/pipeline-map.js +208 -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 +27 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +424 -65
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +206 -33
- package/dist/core/router/rules.d.ts.map +1 -1
- package/dist/core/router/rules.js +6 -0
- package/dist/core/run-mode.d.ts +12 -0
- package/dist/core/run-mode.d.ts.map +1 -0
- package/dist/core/run-mode.js +17 -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/logs.d.ts +4 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -1
- package/dist/core/scheduler/logs.js +25 -1
- 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/secrets.d.ts.map +1 -1
- package/dist/core/secrets.js +18 -8
- package/dist/core/self-analysis.d.ts +32 -2
- package/dist/core/self-analysis.d.ts.map +1 -1
- package/dist/core/self-analysis.js +38 -27
- package/dist/core/shutdown.d.ts +33 -2
- package/dist/core/shutdown.d.ts.map +1 -1
- package/dist/core/shutdown.js +58 -2
- package/dist/core/structured-log.d.ts +37 -1
- package/dist/core/structured-log.d.ts.map +1 -1
- package/dist/core/structured-log.js +37 -0
- package/dist/core/usage-surface.d.ts +25 -0
- package/dist/core/usage-surface.d.ts.map +1 -0
- package/dist/core/usage-surface.js +41 -0
- 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 +19 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +230 -27
- 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 +70 -5
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +170 -29
- package/dist/db/metrics-repo.d.ts +20 -2
- package/dist/db/metrics-repo.d.ts.map +1 -1
- package/dist/db/metrics-repo.js +35 -13
- package/dist/db/migrate.d.ts.map +1 -1
- package/dist/db/migrate.js +37 -17
- package/dist/db/recovery.d.ts +3 -1
- package/dist/db/recovery.d.ts.map +1 -1
- package/dist/db/recovery.js +11 -5
- 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 +91 -60
- package/dist/db/schema.d.ts +2 -2
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +132 -2
- package/dist/db/templates-repo.d.ts +2 -2
- package/dist/db/templates-repo.d.ts.map +1 -1
- package/dist/db/templates-repo.js +5 -3
- package/dist/history.d.ts +7 -2
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +4 -2
- package/dist/hook-output.d.ts +2 -0
- package/dist/hook-output.d.ts.map +1 -0
- package/dist/hook-output.js +31 -0
- 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 +375 -47
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1344 -192
- package/dist/notifications.d.ts +53 -2
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +168 -21
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +82 -10
- package/dist/rpc.d.ts +354 -0
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +145 -0
- package/dist/server.d.ts +32 -2
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +154 -30
- package/dist/settings.d.ts +44 -2
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +85 -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 +21 -0
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +64 -3
- package/dist/templates.d.ts +2 -2
- package/dist/templates.d.ts.map +1 -1
- package/dist/templates.js +3 -3
- package/dist/types.d.ts +22 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +34 -11
- package/docs/ARCHITECTURE.md +319 -66
- 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 +28 -10
- package/docs/FEATURES.md +129 -7
- package/docs/FEATURES.zh.md +97 -6
- package/docs/MIGRATION.md +2 -2
- package/docs/PIPELINE.md +293 -0
- package/docs/QA-A2-GUI-TUI.md +205 -0
- package/docs/README.ru.md +43 -4
- package/docs/README.zh.md +44 -4
- package/docs/SAFETY.md +23 -3
- package/gui-experimental.cjs +9 -8
- package/locales/en.json +58 -3
- package/locales/ru.json +58 -3
- package/locales/zh.json +58 -3
- package/opencode.pipeline.yaml +35 -0
- package/package.json +36 -4
- package/scripts/check-eslint-baseline.mjs +139 -0
- package/scripts/gen-test-plan-counters.mjs +117 -0
- package/scripts/github-ci-fetch.ps1 +37 -0
- package/scripts/pl-commit.ps1 +112 -0
- package/scripts/qa-a2-commit.ps1 +104 -0
- package/scripts/test-home.mjs +107 -0
- package/skills/scheduled-job-best-practices/SKILL.md +95 -1
- package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
- package/src/cli.ts +417 -0
- package/src/core/analytics.ts +27 -4
- package/src/core/audit.ts +25 -0
- package/src/core/budget.ts +340 -0
- package/src/core/cron-to-schtasks.ts +42 -0
- package/src/core/dry-run.ts +235 -12
- package/src/core/execution.ts +538 -0
- package/src/core/feedback.ts +582 -0
- package/src/core/file-watcher.ts +2 -2
- package/src/core/gate-integrity.ts +330 -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/local-ai.ts +7 -3
- package/src/core/lock.ts +178 -37
- package/src/core/matrix.ts +158 -52
- package/src/core/mission.ts +531 -0
- package/src/core/native-notify.ts +1 -1
- package/src/core/opencode-models.ts +30 -21
- package/src/core/opencode-usage.ts +182 -0
- package/src/core/pipeline-apply.ts +158 -0
- package/src/core/pipeline-io.ts +96 -0
- package/src/core/pipeline-map.ts +283 -0
- package/src/core/pipeline-spec.ts +775 -0
- package/src/core/ps-wrapper.ts +435 -66
- package/src/core/record-history.ts +258 -81
- package/src/core/router/rules.ts +6 -0
- package/src/core/run-mode.ts +19 -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 +34 -3
- 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 +26 -19
- package/src/core/self-analysis.ts +75 -29
- package/src/core/shutdown.ts +90 -4
- package/src/core/structured-log.ts +89 -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/usage-surface.ts +70 -0
- package/src/core/worktree-run.ts +199 -0
- package/src/core/worktree.ts +600 -0
- package/src/core/wrappers/bash.ts +248 -26
- package/src/db/capability-repo.ts +127 -10
- package/src/db/history-repo.ts +281 -40
- package/src/db/metrics-repo.ts +40 -13
- package/src/db/migrate.ts +57 -32
- package/src/db/recovery.ts +12 -5
- package/src/db/run-journal.ts +100 -13
- package/src/db/run-resume.ts +17 -1
- package/src/db/runs-repo.ts +147 -65
- package/src/db/schema.ts +134 -2
- package/src/db/templates-repo.ts +5 -3
- package/src/gui.tsx +438 -18
- package/src/history.ts +11 -4
- package/src/hook-output.ts +39 -0
- package/src/i18n.ts +12 -4
- package/src/index.ts +1902 -320
- package/src/notifications.ts +227 -47
- package/src/profiles.ts +88 -10
- package/src/rpc.ts +158 -0
- package/src/server.ts +201 -41
- package/src/settings.ts +125 -5
- package/src/shared/jobs-view.ts +3 -1
- package/src/task-transfer.ts +90 -6
- package/src/templates.ts +3 -3
- package/src/types.ts +23 -2
- package/src/workspaces.ts +37 -14
|
@@ -54,6 +54,13 @@ interface SchedulerBackend {
|
|
|
54
54
|
- Обёртка: `run-task.ps1` + персональный `run-<name>.cmd` в `%APPDATA%\opencode\agent-steward\wrapper`. Legacy-каталог `%APPDATA%\opencode\windows-scheduler` переносится при первом запуске.
|
|
55
55
|
- Логи: `%APPDATA%\opencode\agent-steward\logs\<name>.log`.
|
|
56
56
|
- cron конвертируется в schtasks (`convertCronToSchTasks`) — поддерживается тот же набор шаблонов.
|
|
57
|
+
- Промпт передаётся в `opencode run` после `--`, поэтому промпт, начинающийся с `-`,
|
|
58
|
+
не может быть принят за флаг. Обёртка отклоняет промпты длиннее 30 000 символов
|
|
59
|
+
до `CreateProcess` (лимит командной строки — 32 767 символов).
|
|
60
|
+
- Сторож таймаута: дерево процессов читается через `Get-CimInstance`; при сбое CIM
|
|
61
|
+
или пустом результате обёртка переходит на `Get-WmiObject`, затем проверяет
|
|
62
|
+
`tasklist`/`Get-Process`. Если данных о дереве нет, срабатывает fail-closed:
|
|
63
|
+
`taskkill /F /T /PID <root>`, чтобы внуки не остались работать.
|
|
57
64
|
|
|
58
65
|
### Linux
|
|
59
66
|
- Задачи живут в управляемом блоке `crontab`:
|
|
@@ -70,19 +77,32 @@ interface SchedulerBackend {
|
|
|
70
77
|
- Полный cron-синтаксис (в отличие от Windows), т.к. crontab понимает его нативно.
|
|
71
78
|
- Разовый запуск (`once`): `at -t`; если `at` не установлен, плагин ставит отвязанный процесс `sleep && команда` (`pid:<pid>` в реестре). Fallback не переживает перезагрузку — для надёжности установите пакет `at`.
|
|
72
79
|
- Удаление/пересборка — только своего блока, остальные строки `crontab` не трогаются.
|
|
80
|
+
- Незакрытый блок плагина (маркер начала без конца) — fail-closed: плагин сообщает об ошибке и не перезаписывает crontab, поэтому строки пользователя после маркера не теряются.
|
|
73
81
|
|
|
74
82
|
### macOS
|
|
75
83
|
- Задачи — LaunchAgent-плисты `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
|
|
76
84
|
- Расписание: `StartInterval` для `* * * * *` и `*/N`, `StartCalendarInterval` для `M * * * *`,
|
|
77
85
|
`M H * * *`, `M H * * D`.
|
|
78
86
|
- Пауза = `launchctl unload -w`, возобновление = `launchctl load -w`.
|
|
87
|
+
- Установка приостановленной задачи пишет plist, но не вызывает `load -w`
|
|
88
|
+
(он снял бы паузу); `unload -w` оставляет агент выключенным и после входа.
|
|
89
|
+
- Ошибки `launchctl load` не глотаются: ошибка установки/возобновления содержит
|
|
90
|
+
команду, exit code и stderr (например, `Invalid property list` у битого plist).
|
|
79
91
|
- Обёртка — тот же `.sh`, что и на Linux; пути конфигов:
|
|
80
92
|
`~/.config/opencode/agent-steward/` (или `$XDG_CONFIG_HOME`).
|
|
81
93
|
|
|
82
94
|
### Общая POSIX-обёртка (`.sh`)
|
|
83
95
|
- `cd` в рабочую директорию, `opencode run` с промптом из файла.
|
|
96
|
+
Промпт идёт после `--`, поэтому ведущий `-` не считается опцией.
|
|
97
|
+
- Backstop argv отклоняет `PROMPT_BYTES >= 131072`: `MAX_ARG_STRLEN` в Linux
|
|
98
|
+
включает завершающий NUL, поэтому полезных данных помещается максимум 131 071 байт.
|
|
84
99
|
- Логи пишутся в файл через `>>` и дублируются метками времени.
|
|
85
100
|
- Блокировка через атомарный `mkdir` — защита от параллельных запусков.
|
|
101
|
+
- Node, PS и bash пишут владельца lock как `<pid>-<iso>`; старые форматы
|
|
102
|
+
`<iso>|<pid>` (PS) и голый `<pid>` тоже читаются, поэтому живой lock не
|
|
103
|
+
вытесняется другой средой исполнения.
|
|
104
|
+
- При старте плагин читает владельца и из `<task>.lock`, и из `<task>.lock.d/pid`:
|
|
105
|
+
каталог lock вытесняется только если PID мёртв или отсутствует; возраст — fallback.
|
|
86
106
|
- Таймаут: дочерний процесс + watchdog (`TERM`, затем `KILL`).
|
|
87
107
|
- Quality Gate: `bash -lc "<команда>"` (аналог `cmd.exe /c` на Windows).
|
|
88
108
|
- Метрики: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
|
|
@@ -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,12 +11,15 @@
|
|
|
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
|
+
|
|
16
|
+
Частично построено: контекст запуска (`src/db/run-context.ts`), per-task/per-window
|
|
17
|
+
бюджеты (`src/core/budget.ts`), целостность гейта (`src/core/gate-integrity.ts`),
|
|
18
|
+
worktree-изоляция (`src/core/worktree.ts`, `src/core/worktree-run.ts`).
|
|
15
19
|
|
|
16
20
|
Не построено вовсе: ledger + provenance; класс риска и компиляция политики;
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
approvals-очередь.
|
|
21
|
+
flake-aware повторы и отложенные эффекты; полноценная context compilation
|
|
22
|
+
(repo-map + инъекция scaffolding); egress-контроль и approvals-очередь.
|
|
20
23
|
|
|
21
24
|
Подтверждение:
|
|
22
25
|
|
|
@@ -119,12 +122,27 @@ CREATE TABLE gate_outcomes (
|
|
|
119
122
|
|
|
120
123
|
## 4. Целостность гейта (спринт 39)
|
|
121
124
|
|
|
122
|
-
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
125
|
+
**Реализовано (G-1.2):** при создании задачи `src/core/gate-integrity.ts`
|
|
126
|
+
фиксирует snapshot входов гейта — команду/файл хука, prompt и таймаут — с
|
|
127
|
+
SHA-256 в `PLUGIN_DIR/gate-snapshots/`, вне write-scope задачи. Перед запуском
|
|
128
|
+
гейта обе обёртки (Windows и POSIX) вызывают `gate-integrity.js verify`; при
|
|
129
|
+
расхождении хэша, отсутствии или повреждении snapshot гейт не выполняется,
|
|
130
|
+
запуск переходит в `error` с сообщением «snapshot mismatch». Snapshot
|
|
131
|
+
проверяет именно определение гейта, а не исходники репозитория, которые гейт
|
|
132
|
+
тестирует.
|
|
133
|
+
|
|
134
|
+
**Обязательная тест-атака в CI:** `test-execution-hardening.mjs` (Windows) и
|
|
135
|
+
`test-posix-e2e.mjs` (macOS/Linux) подменяют сгенерированный gate-файл/команду
|
|
136
|
+
на `exit 0` после создания snapshot и требуют падения запуска; оба теста уже
|
|
137
|
+
входят в `npm test`/`test:parallel`. Юнит-проверки хэша и CLI — в
|
|
138
|
+
`test-execution-pipeline.mjs`.
|
|
139
|
+
|
|
140
|
+
**Остаётся планом:** отдельный gate-executor, `gate_outcomes` с `gate_hash`,
|
|
141
|
+
`policy_hash`, `prompt_hash` и `prev_hash` в ledger, аудит-инцидент при
|
|
142
|
+
расхождении и перенос gate-файлов под привилегии, отличные от пользовательских.
|
|
143
|
+
Гейт по-прежнему **всегда hard**; shadow/canary — только для маршрутов и
|
|
144
|
+
адаптеров (49). Подмена самих тестов агентом текущей мерой не детектируется —
|
|
145
|
+
защита ограничена целостностью определения гейта.
|
|
128
146
|
|
|
129
147
|
## 5. Отложенные внешние эффекты
|
|
130
148
|
|
package/docs/FEATURES.md
CHANGED
|
@@ -247,6 +247,16 @@ read/edit/glob/grep/subagent/skill/webfetch/websearch and denies `shell` and `qu
|
|
|
247
247
|
allowed everything. Task-level `legacyShell: true` re-enables `shell` under `hybrid` for
|
|
248
248
|
jobs migrated from older versions; `legacy` is the blunt alternative.
|
|
249
249
|
|
|
250
|
+
> **Autonomous tasks and `tool.blocked`:** with the default `hybrid` policy the agent
|
|
251
|
+
> is denied `shell` and `question`, so an unattended task that tries to run `git status`
|
|
252
|
+
> (or ask a clarifying question) will log `tool.blocked` and cannot complete that step.
|
|
253
|
+
> This is intentional — do **not** switch `defaultPolicy` to `legacy` globally just to
|
|
254
|
+
> silence it. Grant the capability to the specific task instead: add `shell`
|
|
255
|
+
> (and/or `question`, if truly needed) to that task's `allowedTools`, use
|
|
256
|
+
> `legacyShell: true` for migrated jobs, or move the command into `beforeScript` /
|
|
257
|
+
> `qualityGate` / `afterScript`, which run with your user privileges and are not subject
|
|
258
|
+
> to agent tool restrictions. `shell` commands inside scripts are the recommended path.
|
|
259
|
+
|
|
250
260
|
`allowedTools` and `deniedTools` are enforced for the `opencode run` process that the
|
|
251
261
|
task wrapper starts. The wrapper passes the generated `permissions` rules to the
|
|
252
262
|
process through `OPENCODE_CONFIG_CONTENT`; no file is written to the task workdir, so a
|
|
@@ -259,6 +269,41 @@ not to hooks, Quality Gates or scripts, which still run with your user privilege
|
|
|
259
269
|
for the exact action mapping and known limitations (project/system config, nested
|
|
260
270
|
subagents).
|
|
261
271
|
|
|
272
|
+
### One-off git worktree (W-1)
|
|
273
|
+
|
|
274
|
+
Set `worktree: true` to run every tick in a fresh `git worktree` of
|
|
275
|
+
`workingDirectory` on its own `agent-steward/...` branch. The wrapper creates the
|
|
276
|
+
worktree after the schedule gate and before `opencode`, passes the path to the agent
|
|
277
|
+
through the prompt preamble and `AGENT_STEWARD_WORKTREE`, and fails the run closed
|
|
278
|
+
if creation fails (for example, the directory is not a git repository). Paths and
|
|
279
|
+
branches are unique per run, so matrix clones and parallel missions can write files
|
|
280
|
+
without touching the main checkout or each other — safe fan-out without Docker.
|
|
281
|
+
|
|
282
|
+
Worktrees live under `PLUGIN_DIR/worktrees` with a `.json` sidecar used by cleanup.
|
|
283
|
+
After the run the wrapper removes the worktree and its `agent-steward/...` branch
|
|
284
|
+
even when the task fails (W-2.1). Leftovers from crashes are swept opportunistically
|
|
285
|
+
on the next run: worktrees older than 24 hours are removed, sidecars without a
|
|
286
|
+
checkout are pruned, and a `.cleanup-lock` serialises concurrent sweeps (W-2.2).
|
|
287
|
+
Cleanup only touches paths under the worktree root that have a sidecar and an
|
|
288
|
+
`agent-steward/` branch, so foreign directories and fresh active runs are never
|
|
289
|
+
deleted. A worktree does not isolate network, API or database access, and Quality
|
|
290
|
+
Gates still run with your user privileges.
|
|
291
|
+
|
|
292
|
+
### Guard conditions (W-3)
|
|
293
|
+
|
|
294
|
+
Set `guards` on a task to require conditions before it runs: an optional shell
|
|
295
|
+
`command` (exit 0 — пройден, non-zero — скип, `timeoutSeconds` 1..3600) and/or
|
|
296
|
+
`semantic` conditions — `filesExist` / `filesMissing` (relative paths, resolved
|
|
297
|
+
inside the worktree or cwd), `branch` (glob), and `changedPaths` (glob, at least
|
|
298
|
+
one path in the diff of `changedSince..HEAD`, default `HEAD~1`). All conditions
|
|
299
|
+
are ANDed: when any check fails or errors, the run is skipped gracefully with a
|
|
300
|
+
visible `skipped` status in history and the GUI (`record-history --skip`, no
|
|
301
|
+
notification and no success/error chain). Guards are evaluated after the
|
|
302
|
+
worktree is created, so they run inside the fresh worktree when combined with
|
|
303
|
+
`worktree: true`; the `guard-run.js` helper lives in `src/core/guard-run.ts` and
|
|
304
|
+
`src/core/guard.ts` provides normalization, evaluation and the exit-code
|
|
305
|
+
convention (4 = skip).
|
|
306
|
+
|
|
262
307
|
## Orchestration
|
|
263
308
|
|
|
264
309
|
### Chains
|
|
@@ -323,6 +368,21 @@ Behavior worth knowing:
|
|
|
323
368
|
- `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
|
|
324
369
|
gone; the same cleanup also runs at plugin startup.
|
|
325
370
|
|
|
371
|
+
### Pipeline as code
|
|
372
|
+
|
|
373
|
+
A whole DAG can be declared in `opencode.pipeline.yaml` and applied as code:
|
|
374
|
+
|
|
375
|
+
- `version: 1`, a pipeline `name`, optional `defaults` and 1..200 `steps`.
|
|
376
|
+
- Each step has a stable `id`, a `prompt` and an optional `needs` list that becomes
|
|
377
|
+
`dependsOn`.
|
|
378
|
+
- `trigger: cron` (default) needs a `schedule`; `trigger: once` needs `runAt`;
|
|
379
|
+
`trigger: dag` runs only after its `needs` succeed.
|
|
380
|
+
- `matrix.workspaces` fans a step out over workspace names or ids.
|
|
381
|
+
- `agent-steward pipeline validate|apply|export` and the `pipeline_validate`,
|
|
382
|
+
`pipeline_apply`, `pipeline_export` tools cover the lifecycle; apply is idempotent,
|
|
383
|
+
skips unchanged steps and never deletes stale tasks.
|
|
384
|
+
- Full format and limits: [PIPELINE.md](PIPELINE.md).
|
|
385
|
+
|
|
326
386
|
## Multi-repository workspaces
|
|
327
387
|
|
|
328
388
|
A workspace is a named directory: id, name, path, optional git remote and color.
|
|
@@ -348,7 +408,9 @@ This is useful for separating projects, clients or environments (e.g. `default`
|
|
|
348
408
|
in the base directory → `default`. Switching profiles writes the marker and requires
|
|
349
409
|
an OpenCode restart because plugin directories are resolved at module load time.
|
|
350
410
|
- Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
|
|
351
|
-
`profile.json` → server default (3782, then 4782/5782 fallback).
|
|
411
|
+
`profile.json` → server default (3782, then 4782/5782 fallback). A new profile is
|
|
412
|
+
allocated the first free port from 3783 up, skipping 3782/4782, ports already
|
|
413
|
+
recorded in other profiles' `profile.json`, and `OPENCODE_SCHEDULER_PORT`.
|
|
352
414
|
- RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
|
|
353
415
|
`set_profile` switches the active profile (restart hint); `create_profile` /
|
|
354
416
|
`delete_profile` manage named profiles (`default` cannot be deleted).
|
|
@@ -403,6 +465,22 @@ rate of $0.01 / 1k tokens. The KPI is labelled as an estimate and links to
|
|
|
403
465
|
[docs/SAVINGS.md](SAVINGS.md) with the full methodology; `report.savings` exposes
|
|
404
466
|
`savedUsd`, `runs`, `tokens` and a per-task breakdown.
|
|
405
467
|
|
|
468
|
+
Daily and weekly **budgets** (Economy v2) are configured through `manage_settings`
|
|
469
|
+
(`budgets: { enabled, dailyUsd, weeklyUsd }`, USD; `0` means no limit) or the
|
|
470
|
+
`get_settings`/`save_settings` RPC methods. Spending is accounted from finished
|
|
471
|
+
history rows in the current UTC day / UTC week (Monday start) using the same
|
|
472
|
+
cost rule as analytics; unfinished runs are ignored. `get_analytics` (and
|
|
473
|
+
`GET /api/analytics`) expose `report.budgets` with `day`/`week` usage
|
|
474
|
+
(`spentUsd`, `runs`, `limitUsd`, `remainingUsd`, `ratio`, `exceeded`, `disabled`)
|
|
475
|
+
and a combined `exceeded` flag. When a limit is enabled and reached, new runs
|
|
476
|
+
are paused automatically: `run_task`, `run_mission`, `run_task_now` and the
|
|
477
|
+
RPC/GUI, file-trigger and MCP entry points all refuse to start until the next
|
|
478
|
+
period, with a human-readable reason. An alert is sent to the configured
|
|
479
|
+
notification channels (webhook/Telegram/native) when a run is blocked; repeated
|
|
480
|
+
alerts with the same reason are suppressed for 24 hours. Budgets are fail-open:
|
|
481
|
+
disabled groups and zero limits never block a run, and accounting stays visible
|
|
482
|
+
regardless.
|
|
483
|
+
|
|
406
484
|
### Prometheus
|
|
407
485
|
|
|
408
486
|
`GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
|
|
@@ -474,6 +552,12 @@ agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
|
|
|
474
552
|
`dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
|
|
475
553
|
fan-out and estimated time. Nothing is executed and nothing is created.
|
|
476
554
|
|
|
555
|
+
The ad-hoc mission API (`runMission` / `agent-steward run --dry-run`) has its own
|
|
556
|
+
`dryRun` contract: it builds the step plan and its description, but does not acquire
|
|
557
|
+
the `activeWorkspaces` lock and does not write `runs`/`run_steps` to the ledger.
|
|
558
|
+
This is intentional — several dry runs in the same `cwd` run in parallel and leave
|
|
559
|
+
no trace in history. Only a real mission is locked to one workspace at a time.
|
|
560
|
+
|
|
477
561
|
### Dashboard
|
|
478
562
|
|
|
479
563
|
A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
|
|
@@ -610,14 +694,15 @@ the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
|
|
|
610
694
|
|
|
611
695
|
## Agent interface
|
|
612
696
|
|
|
613
|
-
|
|
697
|
+
Thirty tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
|
|
614
698
|
`run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
|
|
615
699
|
`manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
|
|
616
700
|
`get_analytics`, `self_analysis` (health score, anomalies, trends), `manage_settings`,
|
|
617
701
|
`manage_local_ai`, `manage_templates`, `manage_profiles`,
|
|
618
|
-
`transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
|
|
702
|
+
`transfer_tasks`, `send_notification`, `report_bug`, `get_dashboard_info`, `cleanup_history`,
|
|
619
703
|
`manage_secrets`, `get_audit_log`,
|
|
620
|
-
`emit_event
|
|
704
|
+
`emit_event`,
|
|
705
|
+
`pipeline_validate`, `pipeline_apply`, `pipeline_export`.
|
|
621
706
|
|
|
622
707
|
A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
|
|
623
708
|
least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
|
|
@@ -627,6 +712,39 @@ plugin, no installation step required.
|
|
|
627
712
|
The `manage_local_ai` tool reads, updates and tests the local triage settings
|
|
628
713
|
(`action: "get" | "update" | "test"`); see [LOCAL-AI.md](LOCAL-AI.md).
|
|
629
714
|
|
|
715
|
+
## Author feedback (bug reports)
|
|
716
|
+
|
|
717
|
+
`report_bug` sends a structured report to the plugin author through a **write-only**
|
|
718
|
+
receiver (a Cloudflare Worker that creates a GitHub Issue in `DeadSno/agent-steward`).
|
|
719
|
+
The npm package contains **no tokens**: the fine-grained PAT (`issues: write` only)
|
|
720
|
+
lives in the receiver secrets. See [infra/feedback-worker/README.md](../infra/feedback-worker/README.md)
|
|
721
|
+
for deployment.
|
|
722
|
+
|
|
723
|
+
Arguments: `description` (required), `destination: "author" | "local" | "both"`
|
|
724
|
+
(default `author`), `dryRun` (preview only, no network), `includeLogs` (default
|
|
725
|
+
**false**), `includeAnalytics` (default true), `contactEmail`, `taskName`, `channel`.
|
|
726
|
+
|
|
727
|
+
What is sent in the payload (`schemaVersion: 1`): plugin/OS/Node versions,
|
|
728
|
+
locale, active profile, optional task name, the description, and — only when
|
|
729
|
+
explicitly allowed — redacted logs and aggregate metrics. What is **not** sent by
|
|
730
|
+
default: logs, emails, raw environment variables. Client-side redaction removes
|
|
731
|
+
`sk-`/`ghp_`/`xox*`/bot tokens, all values stored via `manage_secrets`, the home
|
|
732
|
+
directory (replaced with `~`) and email addresses (replaced with `[EMAIL]`).
|
|
733
|
+
`contactEmail` is included only if the user provided it explicitly.
|
|
734
|
+
|
|
735
|
+
Privacy controls: `feedback.enabled` defaults to **false**; `includeLogs` defaults
|
|
736
|
+
to **false**; the endpoint must be HTTPS (HTTP only for localhost) and is validated
|
|
737
|
+
on save. Use `report_bug` with `dryRun: true` to inspect the exact payload before
|
|
738
|
+
sending — the plugin displays `schemaVersion`, `reportId`, OS, locale, profile,
|
|
739
|
+
description, contact email, logs and metrics (F-3.1). The GUI has a dedicated
|
|
740
|
+
**Author feedback** settings section. Messages are localized to ru/en/zh.
|
|
741
|
+
|
|
742
|
+
Delivery is fail-open (F-1.6): if the receiver is unavailable, the report is saved
|
|
743
|
+
to the local `feedback_outbox` table and retried on plugin start (max 5 attempts);
|
|
744
|
+
it never blocks task execution. A hash of the description, a 5-minute window and
|
|
745
|
+
an hourly limit (default 6) prevent spam; only hashes, never report text, are stored
|
|
746
|
+
in `feedback_spam`.
|
|
747
|
+
|
|
630
748
|
## Local assistant (triage)
|
|
631
749
|
|
|
632
750
|
An optional offline model classifies failed and partial runs (category, severity,
|
|
@@ -654,7 +772,9 @@ It never changes run status, retries, Quality Gates, DAG dependencies or history
|
|
|
654
772
|
messages are converted to normalized bag-of-words vectors stored in SQLite,
|
|
655
773
|
compared by cosine similarity against the window, and suppressed above
|
|
656
774
|
`threshold` (0.85 default). Important statuses are never suppressed. No new
|
|
657
|
-
dependencies and no external embedding model are required.
|
|
775
|
+
dependencies and no external embedding model are required. CJK text (Chinese,
|
|
776
|
+
Japanese, Korean) is tokenized into overlapping bigrams, so messages without
|
|
777
|
+
spaces produce non-zero vectors and participate in dedup too.
|
|
658
778
|
- `notifications.summary` renders at most three short lines for Telegram and
|
|
659
779
|
toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
|
|
660
780
|
back to deterministic truncation (status, error, runtime/tokens/cost), and
|
|
@@ -689,8 +809,10 @@ and troubleshooting (including `OLLAMA_CONTEXT_LENGTH`) are documented in
|
|
|
689
809
|
not supported.
|
|
690
810
|
- **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
|
|
691
811
|
- **No authentication on the dashboard.** Localhost only by design.
|
|
692
|
-
- **Secrets are
|
|
693
|
-
|
|
812
|
+
- **Secrets are encrypted at rest with AES-256-GCM** in `<PLUGIN_DIR>/secrets.json`
|
|
813
|
+
(see the Secrets section). The key lives in `secrets.key`; losing it makes stored
|
|
814
|
+
values unrecoverable. For higher-sensitivity values, prefer environment variables
|
|
815
|
+
or an external secret manager.
|
|
694
816
|
- **`allowedTools` / `deniedTools` restrict the agent process, not the whole job.**
|
|
695
817
|
Hooks, Quality Gates and wrapper scripts still run with your user privileges, and a
|
|
696
818
|
project-level or system `opencode.jsonc` can weaken task-scoped denies. See the
|
package/docs/FEATURES.zh.md
CHANGED
|
@@ -210,6 +210,14 @@ read/edit/glob/grep/subagent/skill/webfetch/websearch 并拒绝 `shell` 和 `que
|
|
|
210
210
|
`legacyShell: true` 会在 `hybrid` 下为从旧版本迁移来的作业重新启用 `shell`;
|
|
211
211
|
`legacy` 是粗放的替代方案。
|
|
212
212
|
|
|
213
|
+
> **自治任务与 `tool.blocked`:** 默认的 `hybrid` 策略会拒绝 agent 使用 `shell`
|
|
214
|
+
> 和 `question`,因此无人值守任务若尝试运行 `git status`(或询问澄清问题),
|
|
215
|
+
> 会在日志中留下 `tool.blocked` 且无法完成该步骤。这是有意设计——不要仅为消除
|
|
216
|
+
> 它而全局把 `defaultPolicy` 改成 `legacy`。应当为该具体任务授予能力:把 `shell`
|
|
217
|
+
> (确有需要时也包括 `question`)加入该任务的 `allowedTools`,为迁移作业使用
|
|
218
|
+
> `legacyShell: true`,或把命令移入 `beforeScript` / `qualityGate` / `afterScript`
|
|
219
|
+
> ——它们以你的用户权限运行,不受 agent 工具限制约束。推荐在脚本中执行 shell 命令。
|
|
220
|
+
|
|
213
221
|
`allowedTools` 和 `deniedTools` 对任务包装器启动的 `opencode run` 进程
|
|
214
222
|
强制生效。包装器通过 `OPENCODE_CONFIG_CONTENT` 把生成的 `permissions` 规则
|
|
215
223
|
传给该进程;不会向任务工作目录写入任何文件,因此项目级
|
|
@@ -221,6 +229,36 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
221
229
|
嵌套子代理)见
|
|
222
230
|
[ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)。
|
|
223
231
|
|
|
232
|
+
### 一次性 git worktree(W-1)
|
|
233
|
+
|
|
234
|
+
设置 `worktree: true` 后,每次运行都会在 `workingDirectory` 的全新 `git worktree`
|
|
235
|
+
中执行,并使用独立的 `agent-steward/...` 分支。包装脚本在调度门禁之后、启动
|
|
236
|
+
`opencode` 之前创建 worktree,通过提示词前导和 `AGENT_STEWARD_WORKTREE` 把路径传给
|
|
237
|
+
Agent;创建失败时(例如目录不是 git 仓库)运行会 fail-closed 终止。每次运行的路径和
|
|
238
|
+
分支都唯一,因此矩阵克隆和并行任务可以各自写文件,互不影响主工作区和彼此——无需
|
|
239
|
+
Docker 即可安全扇出。
|
|
240
|
+
|
|
241
|
+
Worktree 位于 `PLUGIN_DIR/worktrees`,旁边的 `.json` sidecar 用于清理。运行结束后,
|
|
242
|
+
包装脚本会删除 worktree 及其 `agent-steward/...` 分支,任务失败时也会删除(W-2.1)。
|
|
243
|
+
崩溃留下的残留会在下一次运行时顺带清扫:超过 24 小时的 worktree 被删除,没有工作
|
|
244
|
+
副本的 sidecar 被清理,`.cleanup-lock` 串行化并发清扫(W-2.2)。清理只处理 worktree
|
|
245
|
+
根目录下带 sidecar 且分支为 `agent-steward/` 的路径,因此不会删除外来目录和正在
|
|
246
|
+
运行的 worktree。worktree 不隔离网络、API 或数据库访问,Quality Gate 仍以你的
|
|
247
|
+
用户权限运行。
|
|
248
|
+
|
|
249
|
+
### Guard 条件(W-3)
|
|
250
|
+
|
|
251
|
+
可以为任务设置 `guards` — 运行前必须满足的条件:可选的 shell `command`
|
|
252
|
+
(exit 0 表示通过,非 0 表示跳过,`timeoutSeconds` 1..3600)和/或 `semantic`
|
|
253
|
+
条件 — `filesExist` / `filesMissing`(相对路径,在 worktree 或 cwd 内解析)、
|
|
254
|
+
`branch`(glob)和 `changedPaths`(glob;`changedSince..HEAD` 的 diff 中至少
|
|
255
|
+
匹配一个路径,默认 `HEAD~1`)。所有条件按「与」组合:任一检查失败或出错时,
|
|
256
|
+
运行会被优雅跳过,并在历史记录和 GUI 中显示为可见的 `skipped` 状态
|
|
257
|
+
(`record-history --skip`;不发送通知、不触发成功/错误链)。检查在创建
|
|
258
|
+
worktree 之后执行,因此与 `worktree: true` 组合时它们在新 worktree 内运行;
|
|
259
|
+
`guard-run.js` 帮助程序位于 `src/core/guard-run.ts`,`src/core/guard.ts`
|
|
260
|
+
提供规范化、求值和退出码约定(4 = 跳过)。
|
|
261
|
+
|
|
224
262
|
## 编排
|
|
225
263
|
|
|
226
264
|
### 链式调度
|
|
@@ -283,6 +321,20 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
283
321
|
- `matrix_control` 的 `action: "cleanup"` 会移除父任务已不存在的孤立
|
|
284
322
|
克隆;同样的清理也会在插件启动时运行。
|
|
285
323
|
|
|
324
|
+
### 流水线即代码
|
|
325
|
+
|
|
326
|
+
整个 DAG 可以声明在 `opencode.pipeline.yaml` 中并按代码应用:
|
|
327
|
+
|
|
328
|
+
- `version: 1`、流水线 `name`、可选的 `defaults` 和 1..200 个 `steps`。
|
|
329
|
+
- 每个步骤有稳定的 `id`、`prompt` 和可选的 `needs`(转换为 `dependsOn`)。
|
|
330
|
+
- `trigger: cron`(默认)需要 `schedule`;`trigger: once` 需要 `runAt`;
|
|
331
|
+
`trigger: dag` 只在其 `needs` 成功后运行。
|
|
332
|
+
- `matrix.workspaces` 按 workspace 名称或 id 将步骤扇出。
|
|
333
|
+
- `agent-steward pipeline validate|apply|export` 与 `pipeline_validate`、
|
|
334
|
+
`pipeline_apply`、`pipeline_export` 工具覆盖整个生命周期;apply 幂等、
|
|
335
|
+
跳过未变化的步骤,且从不删除 stale 任务。
|
|
336
|
+
- 完整格式与限制:[PIPELINE.md](PIPELINE.md)。
|
|
337
|
+
|
|
286
338
|
## 多仓库工作区
|
|
287
339
|
|
|
288
340
|
工作区是一个命名目录:id、name、path、可选的 git 远程仓库和颜色。
|
|
@@ -308,7 +360,9 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
|
|
|
308
360
|
`active-profile` 文件 → `default`。切换配置档案会写入标记文件,并且需要
|
|
309
361
|
重启 OpenCode,因为插件目录在模块加载时解析。
|
|
310
362
|
- 每个配置档案的仪表板端口:`OPENCODE_SCHEDULER_PORT` 环境变量 → 来自
|
|
311
|
-
`profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782
|
|
363
|
+
`profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。新配置档案
|
|
364
|
+
会分配 3783 起的第一个空闲端口,跳过 3782/4782、其他配置档案 `profile.json`
|
|
365
|
+
中已记录的端口以及 `OPENCODE_SCHEDULER_PORT`。
|
|
312
366
|
- RPC:`get_profiles` 列出配置档案及其目录、端口和活动标志;
|
|
313
367
|
`set_profile` 切换活动配置档案(会提示重启);`create_profile` /
|
|
314
368
|
`delete_profile` 管理命名配置档案(`default` 不能被删除)。
|
|
@@ -362,6 +416,19 @@ OTLP/JSON(`GET /api/history/export?format=otlp`)。
|
|
|
362
416
|
[docs/SAVINGS.md](SAVINGS.md) 的完整方法说明;`report.savings` 暴露
|
|
363
417
|
`savedUsd`、`runs`、`tokens` 以及按任务的细分。
|
|
364
418
|
|
|
419
|
+
每日/每周 **预算**(Economy v2)通过 `manage_settings`
|
|
420
|
+
(`budgets: { enabled, dailyUsd, weeklyUsd }`,单位 USD;`0` 表示无限制)
|
|
421
|
+
或 `get_settings`/`save_settings` RPC 方法配置。支出按当前 UTC 日 /
|
|
422
|
+
UTC 周(周一开始)从已完成的历史记录中统计,使用与分析相同的成本规则;
|
|
423
|
+
未完成的运行会被忽略。`get_analytics`(以及 `GET /api/analytics`)在
|
|
424
|
+
`report.budgets` 中提供 `day`/`week` 用量(`spentUsd`、`runs`、`limitUsd`、
|
|
425
|
+
`remainingUsd`、`ratio`、`exceeded`、`disabled`)以及总的 `exceeded` 标志。
|
|
426
|
+
当启用某个限额并达到时,新运行会自动暂停:`run_task`、`run_mission`、
|
|
427
|
+
`run_task_now` 以及 RPC/GUI、文件触发和 MCP 入口都会拒绝启动,并给出原因,
|
|
428
|
+
直到下一个周期。运行被阻止时会向已配置的通知渠道(webhook/Telegram/原生通知)
|
|
429
|
+
发送警报;相同原因的重复警报在 24 小时内会被抑制。预算默认 fail-open:
|
|
430
|
+
禁用的分组和零限制永远不会阻止运行,且统计始终可见。
|
|
431
|
+
|
|
365
432
|
### Prometheus
|
|
366
433
|
|
|
367
434
|
`GET /metrics` 暴露 Prometheus 文本格式(0.0.4):`opencode_scheduler_info`、
|
|
@@ -566,14 +633,14 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
566
633
|
|
|
567
634
|
## Agent 接口
|
|
568
635
|
|
|
569
|
-
|
|
636
|
+
二十九个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
|
|
570
637
|
`run_task_now`、`pause_task`、`resume_task`、`get_history`、`get_task_logs`、`dry_run`、
|
|
571
638
|
`manage_workspaces`、`matrix_control`(results/cancel/cleanup/preview)、`get_metrics`、
|
|
572
639
|
`get_analytics`、`self_analysis`(健康评分、异常、趋势)、`manage_settings`、
|
|
573
640
|
`manage_local_ai`、`manage_templates`、`manage_profiles`、
|
|
574
641
|
`transfer_tasks`、`send_notification`、`get_dashboard_info`、`cleanup_history`、
|
|
575
642
|
`manage_secrets`、`get_audit_log`、
|
|
576
|
-
`emit_event`。
|
|
643
|
+
`emit_event`、`pipeline_validate`、`pipeline_apply`、`pipeline_export`。
|
|
577
644
|
|
|
578
645
|
捆绑的 skill `scheduled-job-best-practices` 教会 agent 安全的默认做法:
|
|
579
646
|
最小权限、Quality Gate、超时、矩阵并发、DAG 规则以及
|
|
@@ -583,6 +650,27 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
583
650
|
`manage_local_ai` 工具读取、更新并测试本地分诊设置
|
|
584
651
|
(`action: "get" | "update" | "test"`);见 [LOCAL-AI.md](LOCAL-AI.md)。
|
|
585
652
|
|
|
653
|
+
## 作者反馈(bug 报告)
|
|
654
|
+
|
|
655
|
+
`report_bug` 通过**只写**接收端(Cloudflare Worker,在 `DeadSno/agent-steward`
|
|
656
|
+
创建 GitHub Issue)把结构化报告发送给插件作者;npm 包里不含任何 token,
|
|
657
|
+
fine-grained PAT(仅 `issues:write`)保存在 Worker 的 secrets 中。
|
|
658
|
+
|
|
659
|
+
参数:`description`(必填)、`destination: "author" | "local" | "both"`
|
|
660
|
+
(默认 `author`)、`dryRun`(只展示 payload,不发网络请求)、
|
|
661
|
+
`includeLogs`(默认 **false**)、`includeAnalytics`、`contactEmail`、`taskName`。
|
|
662
|
+
|
|
663
|
+
默认发送的 payload(`schemaVersion: 1`)包含插件/操作系统/Node 版本、locale、
|
|
664
|
+
当前 profile、可选任务名、描述,以及明确允许时才附上的脱敏日志和汇总指标。
|
|
665
|
+
默认**不**发送日志、邮箱或原始环境变量;客户端会剔除 `sk-`/`ghp_`/`xox*`/bot
|
|
666
|
+
token、`manage_secrets` 中的值、home → `~`、email → `[EMAIL]`。
|
|
667
|
+
|
|
668
|
+
隐私控制:`feedback.enabled` 默认 **false**,`includeLogs` 默认 **false**;
|
|
669
|
+
endpoint 必须是 https(localhost 可用 http),保存时校验。先调用
|
|
670
|
+
`report_bug` 且 `dryRun: true` 可查看完整 payload,确认后再发送。GUI 中有
|
|
671
|
+
专门的「作者反馈」设置区,消息提供 ru/en/zh 三种语言。投递采用 fail-open:
|
|
672
|
+
接收端不可用时报告写入本地 outbox,启动时重试(最多 5 次),不阻塞任务。
|
|
673
|
+
|
|
586
674
|
## 本地助手(分诊)
|
|
587
675
|
|
|
588
676
|
一个可选的离线模型对失败和 partial 的运行进行分类(类别、严重程度、
|
|
@@ -611,7 +699,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
611
699
|
在窗口内按余弦相似度比较,超过
|
|
612
700
|
`threshold`(默认 0.85)时被抑制。重要状态
|
|
613
701
|
永远不会被抑制。不需要新依赖,也不需要外部
|
|
614
|
-
嵌入模型。
|
|
702
|
+
嵌入模型。CJK 文本(中文、日文、韩文)按重叠的
|
|
703
|
+
二元组切分,因此没有空格的消息也会得到非零向量
|
|
704
|
+
并参与去重。
|
|
615
705
|
- `notifications.summary` 为 Telegram 和
|
|
616
706
|
toast 最多渲染三行短文本。模型返回严格的 JSON
|
|
617
707
|
`{"lines": [...]}`;任何失败都会回退到确定性截断(状态、
|
|
@@ -646,8 +736,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
|
|
|
646
736
|
和 `last` 覆盖常见场景;不支持按消息分叉/分支会话。
|
|
647
737
|
- **没有沙箱。** 钩子、Quality Gate 和 prompt 都以你的用户权限运行。
|
|
648
738
|
- **仪表板没有认证。** 设计上仅限 localhost。
|
|
649
|
-
-
|
|
650
|
-
|
|
739
|
+
- **密钥在静态存储时使用 AES-256-GCM 加密**,保存在 `<PLUGIN_DIR>/secrets.json`
|
|
740
|
+
(见 Secrets 一节)。密钥存放在 `secrets.key` 中;丢失后已存储的值无法恢复。
|
|
741
|
+
对于更高敏感度的密钥,建议使用环境变量或外部密钥管理器。
|
|
651
742
|
- **`allowedTools` / `deniedTools` 限制的是 agent 进程,而不是整个作业。**
|
|
652
743
|
钩子、Quality Gate 和包装器脚本仍以你的用户权限运行,而且项目级
|
|
653
744
|
或系统级 `opencode.jsonc` 可以削弱任务范围的拒绝规则。见
|
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
|