agent-steward 0.0.3 → 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.
Files changed (287) hide show
  1. package/CHANGELOG.md +154 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +54 -9
  4. package/ROADMAP-STRATEGY.md +23 -20
  5. package/ROADMAP.md +140 -143
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +351 -0
  9. package/dist/core/dlq-api.d.ts +44 -0
  10. package/dist/core/dlq-api.d.ts.map +1 -0
  11. package/dist/core/dlq-api.js +68 -0
  12. package/dist/core/dry-run.d.ts.map +1 -1
  13. package/dist/core/dry-run.js +18 -1
  14. package/dist/core/execution.d.ts +203 -0
  15. package/dist/core/execution.d.ts.map +1 -0
  16. package/dist/core/execution.js +309 -0
  17. package/dist/core/gate-integrity.d.ts +35 -0
  18. package/dist/core/gate-integrity.d.ts.map +1 -0
  19. package/dist/core/gate-integrity.js +132 -0
  20. package/dist/core/git-trigger.d.ts.map +1 -1
  21. package/dist/core/git-trigger.js +14 -2
  22. package/dist/core/guard-run.d.ts +4 -0
  23. package/dist/core/guard-run.d.ts.map +1 -0
  24. package/dist/core/guard-run.js +101 -0
  25. package/dist/core/guard.d.ts +52 -0
  26. package/dist/core/guard.d.ts.map +1 -0
  27. package/dist/core/guard.js +362 -0
  28. package/dist/core/lock.d.ts +61 -4
  29. package/dist/core/lock.d.ts.map +1 -1
  30. package/dist/core/lock.js +213 -26
  31. package/dist/core/matrix.d.ts.map +1 -1
  32. package/dist/core/matrix.js +75 -15
  33. package/dist/core/mission.d.ts +83 -0
  34. package/dist/core/mission.d.ts.map +1 -0
  35. package/dist/core/mission.js +334 -0
  36. package/dist/core/one-shot.d.ts +5 -1
  37. package/dist/core/one-shot.d.ts.map +1 -1
  38. package/dist/core/one-shot.js +33 -8
  39. package/dist/core/opencode-cli.d.ts +28 -0
  40. package/dist/core/opencode-cli.d.ts.map +1 -0
  41. package/dist/core/opencode-cli.js +74 -0
  42. package/dist/core/opencode-models.d.ts +62 -0
  43. package/dist/core/opencode-models.d.ts.map +1 -0
  44. package/dist/core/opencode-models.js +277 -0
  45. package/dist/core/pipeline-apply.d.ts +38 -0
  46. package/dist/core/pipeline-apply.d.ts.map +1 -0
  47. package/dist/core/pipeline-apply.js +117 -0
  48. package/dist/core/pipeline-io.d.ts +13 -0
  49. package/dist/core/pipeline-io.d.ts.map +1 -0
  50. package/dist/core/pipeline-io.js +64 -0
  51. package/dist/core/pipeline-map.d.ts +46 -0
  52. package/dist/core/pipeline-map.d.ts.map +1 -0
  53. package/dist/core/pipeline-map.js +196 -0
  54. package/dist/core/pipeline-spec.d.ts +109 -0
  55. package/dist/core/pipeline-spec.d.ts.map +1 -0
  56. package/dist/core/pipeline-spec.js +554 -0
  57. package/dist/core/ps-wrapper.d.ts +19 -2
  58. package/dist/core/ps-wrapper.d.ts.map +1 -1
  59. package/dist/core/ps-wrapper.js +261 -63
  60. package/dist/core/record-history.d.ts +15 -0
  61. package/dist/core/record-history.d.ts.map +1 -1
  62. package/dist/core/record-history.js +183 -58
  63. package/dist/core/router/dispatch.d.ts +36 -0
  64. package/dist/core/router/dispatch.d.ts.map +1 -0
  65. package/dist/core/router/dispatch.js +59 -0
  66. package/dist/core/router/escalation.d.ts +47 -0
  67. package/dist/core/router/escalation.d.ts.map +1 -0
  68. package/dist/core/router/escalation.js +87 -0
  69. package/dist/core/router/planner.d.ts +53 -0
  70. package/dist/core/router/planner.d.ts.map +1 -0
  71. package/dist/core/router/planner.js +113 -0
  72. package/dist/core/router/rules.d.ts +46 -0
  73. package/dist/core/router/rules.d.ts.map +1 -0
  74. package/dist/core/router/rules.js +91 -0
  75. package/dist/core/run-panel-api.d.ts +94 -0
  76. package/dist/core/run-panel-api.d.ts.map +1 -0
  77. package/dist/core/run-panel-api.js +169 -0
  78. package/dist/core/schedule-gate.js +5 -1
  79. package/dist/core/schedule-v2.d.ts +34 -0
  80. package/dist/core/schedule-v2.d.ts.map +1 -1
  81. package/dist/core/schedule-v2.js +91 -5
  82. package/dist/core/scheduler/at-fallback.d.ts +55 -2
  83. package/dist/core/scheduler/at-fallback.d.ts.map +1 -1
  84. package/dist/core/scheduler/at-fallback.js +135 -5
  85. package/dist/core/scheduler/linux.d.ts +18 -2
  86. package/dist/core/scheduler/linux.d.ts.map +1 -1
  87. package/dist/core/scheduler/linux.js +63 -20
  88. package/dist/core/scheduler/mac.d.ts +44 -2
  89. package/dist/core/scheduler/mac.d.ts.map +1 -1
  90. package/dist/core/scheduler/mac.js +126 -15
  91. package/dist/core/scheduler/posix.d.ts.map +1 -1
  92. package/dist/core/scheduler/posix.js +25 -1
  93. package/dist/core/scheduler/registry.d.ts +11 -0
  94. package/dist/core/scheduler/registry.d.ts.map +1 -1
  95. package/dist/core/scheduler/registry.js +83 -21
  96. package/dist/core/scheduler/run-now.d.ts +16 -0
  97. package/dist/core/scheduler/run-now.d.ts.map +1 -0
  98. package/dist/core/scheduler/run-now.js +28 -0
  99. package/dist/core/scheduler/windows.d.ts.map +1 -1
  100. package/dist/core/scheduler/windows.js +15 -12
  101. package/dist/core/secrets.d.ts.map +1 -1
  102. package/dist/core/secrets.js +125 -28
  103. package/dist/core/session.d.ts.map +1 -1
  104. package/dist/core/session.js +18 -11
  105. package/dist/core/structured-log.d.ts +7 -1
  106. package/dist/core/structured-log.d.ts.map +1 -1
  107. package/dist/core/task-name.d.ts +24 -0
  108. package/dist/core/task-name.d.ts.map +1 -0
  109. package/dist/core/task-name.js +40 -0
  110. package/dist/core/worktree-run.d.ts +4 -0
  111. package/dist/core/worktree-run.d.ts.map +1 -0
  112. package/dist/core/worktree-run.js +164 -0
  113. package/dist/core/worktree.d.ts +115 -0
  114. package/dist/core/worktree.d.ts.map +1 -0
  115. package/dist/core/worktree.js +462 -0
  116. package/dist/core/wrappers/bash.d.ts +17 -0
  117. package/dist/core/wrappers/bash.d.ts.map +1 -1
  118. package/dist/core/wrappers/bash.js +224 -28
  119. package/dist/db/capability-repo.d.ts +124 -0
  120. package/dist/db/capability-repo.d.ts.map +1 -0
  121. package/dist/db/capability-repo.js +267 -0
  122. package/dist/db/history-repo.d.ts +46 -5
  123. package/dist/db/history-repo.d.ts.map +1 -1
  124. package/dist/db/history-repo.js +107 -25
  125. package/dist/db/index.d.ts +4 -0
  126. package/dist/db/index.d.ts.map +1 -1
  127. package/dist/db/index.js +39 -1
  128. package/dist/db/metrics-repo.js +2 -2
  129. package/dist/db/migrate.d.ts.map +1 -1
  130. package/dist/db/migrate.js +3 -1
  131. package/dist/db/recovery.d.ts.map +1 -1
  132. package/dist/db/recovery.js +5 -4
  133. package/dist/db/run-context.d.ts +103 -0
  134. package/dist/db/run-context.d.ts.map +1 -0
  135. package/dist/db/run-context.js +224 -0
  136. package/dist/db/run-dlq.d.ts +100 -0
  137. package/dist/db/run-dlq.d.ts.map +1 -0
  138. package/dist/db/run-dlq.js +191 -0
  139. package/dist/db/run-journal.d.ts +33 -5
  140. package/dist/db/run-journal.d.ts.map +1 -1
  141. package/dist/db/run-journal.js +78 -14
  142. package/dist/db/run-resume.d.ts +10 -2
  143. package/dist/db/run-resume.d.ts.map +1 -1
  144. package/dist/db/run-resume.js +39 -13
  145. package/dist/db/runs-repo.d.ts +32 -7
  146. package/dist/db/runs-repo.d.ts.map +1 -1
  147. package/dist/db/runs-repo.js +50 -11
  148. package/dist/db/schema.d.ts +2 -2
  149. package/dist/db/schema.d.ts.map +1 -1
  150. package/dist/db/schema.js +216 -3
  151. package/dist/db/settings-repo.d.ts +11 -0
  152. package/dist/db/settings-repo.d.ts.map +1 -1
  153. package/dist/db/settings-repo.js +25 -0
  154. package/dist/db/step-idempotency.d.ts +51 -0
  155. package/dist/db/step-idempotency.d.ts.map +1 -0
  156. package/dist/db/step-idempotency.js +136 -0
  157. package/dist/history.d.ts +1 -1
  158. package/dist/history.d.ts.map +1 -1
  159. package/dist/i18n.d.ts +5 -0
  160. package/dist/i18n.d.ts.map +1 -1
  161. package/dist/i18n.js +11 -4
  162. package/dist/index.d.ts +140 -6
  163. package/dist/index.d.ts.map +1 -1
  164. package/dist/index.js +480 -18
  165. package/dist/notifications.d.ts +22 -0
  166. package/dist/notifications.d.ts.map +1 -1
  167. package/dist/notifications.js +36 -8
  168. package/dist/profiles.d.ts.map +1 -1
  169. package/dist/profiles.js +25 -4
  170. package/dist/rpc.d.ts +924 -0
  171. package/dist/rpc.d.ts.map +1 -1
  172. package/dist/rpc.js +352 -0
  173. package/dist/server.d.ts +46 -0
  174. package/dist/server.d.ts.map +1 -1
  175. package/dist/server.js +172 -53
  176. package/dist/settings.d.ts +2 -2
  177. package/dist/settings.d.ts.map +1 -1
  178. package/dist/settings.js +3 -3
  179. package/dist/shared/jobs-view.d.ts +1 -1
  180. package/dist/shared/jobs-view.d.ts.map +1 -1
  181. package/dist/shared/jobs-view.js +2 -0
  182. package/dist/task-transfer.d.ts +16 -0
  183. package/dist/task-transfer.d.ts.map +1 -1
  184. package/dist/task-transfer.js +16 -0
  185. package/dist/types.d.ts.map +1 -1
  186. package/dist/types.js +7 -0
  187. package/dist/workspaces.d.ts +25 -3
  188. package/dist/workspaces.d.ts.map +1 -1
  189. package/dist/workspaces.js +43 -8
  190. package/docs/ARCHITECTURE.md +498 -58
  191. package/docs/COMPATIBILITY.md +2 -2
  192. package/docs/CONCEPT.md +185 -91
  193. package/docs/CROSS_PLATFORM.ru.md +20 -0
  194. package/docs/CROSS_PLATFORM.zh.md +18 -0
  195. package/docs/EXECUTION-LOOP.md +211 -0
  196. package/docs/FEATURES.md +65 -4
  197. package/docs/FEATURES.zh.md +52 -4
  198. package/docs/MIGRATION.md +2 -2
  199. package/docs/PIPELINE.md +293 -0
  200. package/docs/README.ru.md +44 -5
  201. package/docs/README.zh.md +46 -6
  202. package/docs/SAFETY.md +142 -0
  203. package/docs/SAVINGS.md +29 -0
  204. package/docs/SAVINGS.ru.md +29 -0
  205. package/docs/SAVINGS.zh.md +18 -0
  206. package/gui-experimental.cjs +9 -8
  207. package/locales/en.json +84 -1
  208. package/locales/ru.json +84 -1
  209. package/locales/zh.json +84 -1
  210. package/opencode.pipeline.yaml +35 -0
  211. package/package.json +46 -2
  212. package/scripts/audit-bundle.mjs +215 -0
  213. package/scripts/test-home.mjs +83 -0
  214. package/src/cli.ts +412 -0
  215. package/src/core/dlq-api.ts +98 -0
  216. package/src/core/dry-run.ts +27 -3
  217. package/src/core/execution.ts +538 -0
  218. package/src/core/file-watcher.ts +2 -2
  219. package/src/core/gate-integrity.ts +160 -0
  220. package/src/core/git-trigger.ts +18 -5
  221. package/src/core/guard-run.ts +119 -0
  222. package/src/core/guard.ts +431 -0
  223. package/src/core/lock.ts +244 -30
  224. package/src/core/matrix.ts +95 -50
  225. package/src/core/mission.ts +485 -0
  226. package/src/core/native-notify.ts +1 -1
  227. package/src/core/one-shot.ts +36 -8
  228. package/src/core/opencode-cli.ts +103 -0
  229. package/src/core/opencode-models.ts +315 -0
  230. package/src/core/pipeline-apply.ts +158 -0
  231. package/src/core/pipeline-io.ts +79 -0
  232. package/src/core/pipeline-map.ts +264 -0
  233. package/src/core/pipeline-spec.ts +775 -0
  234. package/src/core/ps-wrapper.ts +274 -64
  235. package/src/core/record-history.ts +229 -104
  236. package/src/core/router/dispatch.ts +94 -0
  237. package/src/core/router/escalation.ts +129 -0
  238. package/src/core/router/planner.ts +166 -0
  239. package/src/core/router/rules.ts +115 -0
  240. package/src/core/run-panel-api.ts +262 -0
  241. package/src/core/schedule-gate.ts +7 -3
  242. package/src/core/schedule-v2.ts +114 -5
  243. package/src/core/scheduler/at-fallback.ts +190 -5
  244. package/src/core/scheduler/linux.ts +72 -21
  245. package/src/core/scheduler/logs.ts +2 -2
  246. package/src/core/scheduler/mac.ts +174 -14
  247. package/src/core/scheduler/posix.ts +20 -1
  248. package/src/core/scheduler/registry.ts +107 -26
  249. package/src/core/scheduler/run-now.ts +32 -0
  250. package/src/core/scheduler/windows.ts +19 -15
  251. package/src/core/secrets.ts +131 -31
  252. package/src/core/session.ts +23 -10
  253. package/src/core/structured-log.ts +22 -5
  254. package/src/core/task-name.ts +67 -0
  255. package/src/core/telegram.ts +2 -2
  256. package/src/core/triage-worker.ts +7 -7
  257. package/src/core/triage.ts +2 -2
  258. package/src/core/worktree-run.ts +199 -0
  259. package/src/core/worktree.ts +600 -0
  260. package/src/core/wrappers/bash.ts +239 -27
  261. package/src/db/capability-repo.ts +402 -0
  262. package/src/db/history-repo.ts +151 -22
  263. package/src/db/index.ts +37 -1
  264. package/src/db/metrics-repo.ts +2 -2
  265. package/src/db/migrate.ts +3 -1
  266. package/src/db/recovery.ts +5 -4
  267. package/src/db/run-context.ts +370 -0
  268. package/src/db/run-dlq.ts +310 -0
  269. package/src/db/run-journal.ts +100 -13
  270. package/src/db/run-resume.ts +65 -13
  271. package/src/db/runs-repo.ts +66 -13
  272. package/src/db/schema.ts +218 -3
  273. package/src/db/settings-repo.ts +31 -0
  274. package/src/db/step-idempotency.ts +185 -0
  275. package/src/gui.tsx +692 -13
  276. package/src/history.ts +1 -1
  277. package/src/i18n.ts +12 -4
  278. package/src/index.ts +648 -8
  279. package/src/notifications.ts +38 -8
  280. package/src/profiles.ts +26 -4
  281. package/src/rpc.ts +379 -0
  282. package/src/server.ts +206 -54
  283. package/src/settings.ts +5 -5
  284. package/src/shared/jobs-view.ts +3 -1
  285. package/src/task-transfer.ts +31 -0
  286. package/src/types.ts +9 -0
  287. package/src/workspaces.ts +58 -9
@@ -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.
package/docs/README.ru.md CHANGED
@@ -18,7 +18,7 @@ Translations: [English](../README.md) · [中文](README.zh.md).
18
18
 
19
19
  > Поставь задачу «утренний-отчёт»: каждый день в 09:00 с промптом «Просуммаризируй вчерашние git-коммиты и запиши отчёт в ~/reports/».
20
20
 
21
- 3. Откройте дашборд: агент печатает ссылку при создании задачи (по умолчанию `http://localhost:4380`), позже её можно получить инструментом `get_dashboard_info`. Посмотреть демо без установки: `node scripts/demo-dashboard.mjs` — дашборд с демо-данными на `http://localhost:4380`.
21
+ 3. Откройте дашборд: агент печатает ссылку при создании задачи (по умолчанию `http://localhost:3782`), позже её можно получить инструментом `get_dashboard_info`. Посмотреть демо без установки: `node scripts/demo-dashboard.mjs` — дашборд с демо-данными на `http://localhost:3782`.
22
22
 
23
23
  ![Локальный веб-дашборд: матричные сборки, граф DAG, метрики и история запусков](dashboard.png)
24
24
 
@@ -46,11 +46,11 @@ Translations: [English](../README.md) · [中文](README.zh.md).
46
46
  | Мультирепо | workspaces с валидацией путей, запуски по workspace, матрица поверх родительской задачи |
47
47
  | Наблюдаемость | история SQLite (success / error / timeout / partial / running), метрики (длительность, токены, стоимость), JSONL-логи с `/api/logs`, Prometheus `/metrics`, экспорт OTLP, логи по задачам, веб-дашборд с аналитикой за 14 дней, ретеншн истории и экспорт CSV/JSON |
48
48
  | Эксплуатация | dry-run, экспорт/импорт JSON, шаблоны, уведомления по нескольким каналам (webhook, Telegram, нативные toast), тихие часы, дайджест, локальный ассистент для триажа уведомлений (fail-open, shadow-режим), зашифрованные секреты (`${secret:NAME}`), журнал аудита, настройки |
49
- | Интерфейсы | панель OpenCode GUI, веб-дашборд, 26 инструментов для агента, встроенный скилл |
49
+ | Интерфейсы | панель OpenCode GUI, веб-дашборд, 29 инструментов для агента, встроенный скилл |
50
50
 
51
51
  ### Язык интерфейса
52
52
 
53
- Интерфейс доступен на русском (по умолчанию), английском и китайском (упрощённом). Переключатель языка находится в шапке панели планировщика (🌐 Авто / Русский / English / 中文), а также доступен через инструмент `manage_settings` (`action: "update"`, `locale: "zh"`). Значение `locale: "auto"` («Авто») следует за языком интерфейса OpenCode: панель реагирует на смену языка сразу, а разрешённая локаль отправляется на сервер, чтобы уведомления, дайджест и дашборд использовали тот же язык. Переключение применяется без перезапуска. Локализация дашборда ещё не завершена: часть строк на стороне клиента пока остаётся русской. Описания и схемы инструментов агента остаются английскими, диагностика в консоли — русской.
53
+ Интерфейс доступен на русском, английском и китайском (упрощённом). По умолчанию выбран режим **«Авто»** — как в OpenCode, язык интерфейса следует за языком OpenCode; русский, английский и китайский можно выбрать явно. Переключатель языка находится в шапке панели планировщика (🌐 Авто / Русский / English / 中文), а также доступен через инструмент `manage_settings` (`action: "update"`, `locale: "zh"`). Значение `locale: "auto"` («Авто», используется по умолчанию) следует за языком интерфейса OpenCode: панель реагирует на смену языка сразу, а разрешённая локаль отправляется на сервер, чтобы уведомления, дайджест и дашборд использовали тот же язык. Переключение применяется без перезапуска. Локализация дашборда ещё не завершена: часть строк на стороне клиента пока остаётся русской. Описания и схемы инструментов агента остаются английскими, диагностика в консоли — русской.
54
54
 
55
55
  Каталоги лежат в `locales/ru.json`, `locales/en.json` и `locales/zh.json`; набор ключей в них должен совпадать, иначе CI падает.
56
56
 
@@ -106,7 +106,7 @@ npm run build && npm run build:gui
106
106
 
107
107
  ## Инструменты для агента
108
108
 
109
- Агенту доступен весь функционал — 26 инструментов: расписание, пайплайны, эксплуатация, аналитика и администрирование.
109
+ Агенту доступен весь функционал — 29 инструментов: расписание, пайплайны, эксплуатация, аналитика и администрирование.
110
110
 
111
111
  | Инструмент | Аргументы | Что делает |
112
112
  |---|---|---|
@@ -136,6 +136,9 @@ npm run build && npm run build:gui
136
136
  | `manage_secrets` | `action`, `name?`, `value?` | Создание, список и удаление секретов AES-256-GCM для `env` задач |
137
137
  | `get_audit_log` | `action?`, `target?`, `actor?`, `since?`, `until?`, `limit?` | Журнал мутаций: кто, что и когда изменил и через какой интерфейс |
138
138
  | `emit_event` | `eventName`, `payload?` | Запуск задач, подписанных на MCP-событие |
139
+ | `pipeline_validate` | `path?`, `source?` | Проверяет `opencode.pipeline.yaml`, не меняя задачи |
140
+ | `pipeline_apply` | `path?`, `source?`, `dryRun?` | Идемпотентно создаёт и обновляет задачи конвейера; `dryRun` только показывает diff |
141
+ | `pipeline_export` | `pipeline` | Выгружает задачи конвейера обратно в YAML |
139
142
 
140
143
  `schedule_task` принимает и полную конфигурацию матрицы (`workspaceIds`, `strategy`, `failureMode`, `aggregation`, `concurrency`, `overrides`, `createAggregator`).
141
144
 
@@ -182,6 +185,41 @@ npm run build && npm run build:gui
182
185
 
183
186
  Каждый workspace получает клон `<parent>-matrix-<workspace>`. Родительская задача сама не выполняется: она агрегирует результаты клонов в `success`, `error` или `partial`. Клоны синхронизируются с родителем при его изменении; запущенные клоны не затрагиваются.
184
187
 
188
+ ## Pipeline как код
189
+
190
+ Опишите весь конвейер одним файлом `opencode.pipeline.yaml`, вместо того чтобы создавать задачи по одной:
191
+
192
+ ```yaml
193
+ version: 1
194
+ name: nightly-release
195
+ defaults:
196
+ retryCount: 1
197
+ retryDelay: 120
198
+ steps:
199
+ - id: lint
200
+ schedule: "0 2 * * *"
201
+ prompt: Запусти линтер и исправь найденные проблемы.
202
+ qualityGate: npm run lint
203
+ - id: test
204
+ needs: [lint]
205
+ trigger: dag
206
+ prompt: Запусти тесты и исправь падения.
207
+ qualityGate: npm test
208
+ ```
209
+
210
+ `needs` превращается в DAG-зависимость, шаг с `trigger: dag` запускается только после успеха зависимостей, а `defaults` наследуются всеми шагами. Каждый шаг становится задачей с именем `<pipeline> <step>`.
211
+
212
+ ```bash
213
+ agent-steward pipeline validate opencode.pipeline.yaml
214
+ agent-steward pipeline apply opencode.pipeline.yaml --dry-run
215
+ agent-steward pipeline apply opencode.pipeline.yaml
216
+ agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
217
+ ```
218
+
219
+ Apply идемпотентен: неизменённые шаги пропускаются, изменённые обновляются, а задачи вне конвейера не затрагиваются. Шаги, удалённые из файла, помечаются как устаревшие, но не удаляются. Агенту доступны те же операции через `pipeline_validate`, `pipeline_apply` и `pipeline_export`.
220
+
221
+ Полный формат, матрица, правила валидации и ограничения — в [docs/PIPELINE.md](PIPELINE.md); готовый пример — [opencode.pipeline.yaml](../opencode.pipeline.yaml).
222
+
185
223
  ## GUI и дашборд
186
224
 
187
225
  В боковой панели OpenCode доступны задачи, история, логи, dry-run, шаблоны, импорт/экспорт, лимит конкурентности и группировка матриц. Локальный веб-дашборд добавляет сводку по workspace, вкладки матриц, вид пайплайна и метрики.
@@ -224,7 +262,7 @@ src/
224
262
  npm install
225
263
  npm run build # tsc
226
264
  npm run build:gui # vite
227
- npm test # 73 сюит, 600+ проверок
265
+ npm test # 83 сюит, 600+ проверок
228
266
  npm run test:en # те же сюиты с английской локалью
229
267
  ```
230
268
 
@@ -239,6 +277,7 @@ npm run test:en # те же сюиты с английской локаль
239
277
  - [FEATURES.md](FEATURES.md) — полный каталог возможностей с примерами.
240
278
  - [FAQ.md](FAQ.md) — сценарии восстановления и ответы по эксплуатации (English).
241
279
  - [MIGRATION.md](MIGRATION.md) — переезд с cron, systemd, launchd или Планировщика Windows.
280
+ - [PIPELINE.md](PIPELINE.md) — конвейер как код: формат, CLI, идемпотентный apply.
242
281
  - [SAVINGS.md](SAVINGS.md) — как считается оценка «Сэкономлено $» (English).
243
282
  - [../CROSS_PLATFORM.md](../CROSS_PLATFORM.md) — различия и бэкенды Windows / macOS / Linux.
244
283
 
package/docs/README.zh.md CHANGED
@@ -19,7 +19,7 @@ Translations: [English](../README.md) · [Русский](README.ru.md).
19
19
 
20
20
  > 创建一个名为 "morning-report" 的任务,每天 09:00 运行,提示词为:"Summarize yesterday's git commits and write the report to ~/reports/"。
21
21
 
22
- 3. 打开仪表盘观察运行情况:创建任务时 agent 会打印 URL(默认 `http://localhost:4380`),之后也可以随时用 `get_dashboard_info` 工具获取。想不安装任何东西先看看效果?`node scripts/demo-dashboard.mjs` 会在 `http://localhost:4380` 启动一个演示仪表盘。
22
+ 3. 打开仪表盘观察运行情况:创建任务时 agent 会打印 URL(默认 `http://localhost:3782`),之后也可以随时用 `get_dashboard_info` 工具获取。想不安装任何东西先看看效果?`node scripts/demo-dashboard.mjs` 会在 `http://localhost:3782` 启动一个演示仪表盘。
23
23
 
24
24
  ## 为什么需要它
25
25
 
@@ -35,7 +35,7 @@ Translations: [English](../README.md) · [Русский](README.ru.md).
35
35
 
36
36
  ![本地 Web 仪表盘:矩阵构建、DAG 图、指标与运行历史](dashboard.png)
37
37
 
38
- 不想安装 OpenCode 也想看看效果?`node scripts/demo-dashboard.mjs` 会用演示数据在 http://localhost:4380 启动仪表盘。
38
+ 不想安装 OpenCode 也想看看效果?`node scripts/demo-dashboard.mjs` 会用演示数据在 http://localhost:3782 启动仪表盘。
39
39
 
40
40
  ## 功能
41
41
 
@@ -53,9 +53,10 @@ Translations: [English](../README.md) · [Русский](README.ru.md).
53
53
 
54
54
  ### 语言
55
55
 
56
- 界面提供俄语(默认)、英语和中文。语言选择器位于调度器面板顶部(🌐 自动 / Русский / English / 中文),
56
+ 界面提供俄语、英语和中文。默认选择「自动」模式——与 OpenCode 一样,界面语言跟随 OpenCode;
57
+ 也可以显式选择俄语、英语或中文。语言选择器位于调度器面板顶部(🌐 自动 / Русский / English / 中文),
57
58
  也可通过 `manage_settings` 工具切换(`action: "update"`,`locale: "zh"` 等)。
58
- `locale: "auto"`(「自动」)跟随 OpenCode 界面语言:面板会立即响应语言切换,
59
+ `locale: "auto"`(「自动」,默认)跟随 OpenCode 界面语言:面板会立即响应语言切换,
59
60
  并将解析后的语言发送到服务器,使通知、摘要和仪表盘保持一致。切换无需重启。
60
61
  仪表盘的本地化仍在推进:部分客户端字符串目前仍为俄语。按设计,agent 工具描述
61
62
  与 schema 保持英语,输出到控制台的诊断信息保持俄语。
@@ -115,7 +116,7 @@ npm run build && npm run build:gui
115
116
 
116
117
  ## Agent 工具
117
118
 
118
- agent 可获得完整功能 —— 26 个工具,覆盖调度、流水线、运维、可观测性与管理:
119
+ agent 可获得完整功能 —— 29 个工具,覆盖调度、流水线、运维、可观测性与管理:
119
120
 
120
121
  | 工具 | 参数 | 作用 |
121
122
  |---|---|---|
@@ -145,6 +146,9 @@ agent 可获得完整功能 —— 26 个工具,覆盖调度、流水线、运
145
146
  | `manage_secrets` | `action`、`name?`、`value?` | 创建、列出或删除用于任务 `env` 的 AES-256-GCM 加密密钥 |
146
147
  | `get_audit_log` | `action?`、`target?`、`actor?`、`since?`、`until?`、`limit?` | 变更审计日志:谁、何时、通过哪个界面改了什么 |
147
148
  | `emit_event` | `eventName`、`payload?` | 启动订阅该 MCP 事件的任务 |
149
+ | `pipeline_validate` | `path?`、`source?` | 校验 `opencode.pipeline.yaml`,不修改任务 |
150
+ | `pipeline_apply` | `path?`、`source?`、`dryRun?` | 幂等地创建/更新流水线任务;`dryRun` 只报告差异 |
151
+ | `pipeline_export` | `pipeline` | 将流水线任务导出回 YAML |
148
152
 
149
153
  `schedule_task` 还接受完整的矩阵配置(`workspaceIds`、`strategy`、`failureMode`、`aggregation`、`concurrency`、`overrides`、`createAggregator`)。
150
154
 
@@ -191,6 +195,41 @@ Agent 任务以 `opencode run --auto` 运行,因此其工具策略必须显式
191
195
 
192
196
  每个 workspace 会得到一个名为 `<parent>-matrix-<workspace>` 的克隆。父任务自身从不运行:它把克隆结果聚合为 `success`、`error` 或 `partial`。编辑父任务时克隆会保持同步;正在运行的克隆不会被改动。
193
197
 
198
+ ## Pipeline 即代码
199
+
200
+ 用一个 `opencode.pipeline.yaml` 文件描述整个工作流,而不是逐个创建任务:
201
+
202
+ ```yaml
203
+ version: 1
204
+ name: nightly-release
205
+ defaults:
206
+ retryCount: 1
207
+ retryDelay: 120
208
+ steps:
209
+ - id: lint
210
+ schedule: "0 2 * * *"
211
+ prompt: Run the linter and fix what it reports.
212
+ qualityGate: npm run lint
213
+ - id: test
214
+ needs: [lint]
215
+ trigger: dag
216
+ prompt: Run the tests and fix failures.
217
+ qualityGate: npm test
218
+ ```
219
+
220
+ `needs` 会变成 DAG 依赖,`trigger: dag` 的步骤只在其依赖成功后运行,`defaults` 由所有步骤继承。每个步骤都会成为名为 `<pipeline> <step>` 的任务。
221
+
222
+ ```bash
223
+ agent-steward pipeline validate opencode.pipeline.yaml
224
+ agent-steward pipeline apply opencode.pipeline.yaml --dry-run
225
+ agent-steward pipeline apply opencode.pipeline.yaml
226
+ agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
227
+ ```
228
+
229
+ apply 是幂等的:未变化的步骤会跳过,修改过的步骤会更新,流水线之外的任务不会被触碰。从文件中删除的步骤会被标记为 stale,但不会自动删除。agent 可通过 `pipeline_validate`、`pipeline_apply` 和 `pipeline_export` 使用同样的操作。
230
+
231
+ 完整格式、矩阵扇出、校验规则与限制见 [docs/PIPELINE.md](PIPELINE.md),可直接复制的示例见 [opencode.pipeline.yaml](../opencode.pipeline.yaml)。
232
+
194
233
  ## GUI 与仪表盘
195
234
 
196
235
  OpenCode 侧边栏显示任务、历史、日志、dry-run、模板、导入/导出、并发限制和矩阵分组。本地 Web 仪表盘额外提供按 workspace 的汇总、矩阵标签页、流水线视图和指标。
@@ -231,7 +270,7 @@ src/
231
270
  npm install
232
271
  npm run build # tsc
233
272
  npm run build:gui # vite
234
- npm test # 73 test suites, 600+ checks
273
+ npm test # 83 test suites, 600+ checks
235
274
  npm run test:en # same suites with the English locale
236
275
  ```
237
276
 
@@ -247,6 +286,7 @@ npm run test:en # same suites with the English locale
247
286
  - [docs/FEATURES.md](FEATURES.md) —— 带示例的完整功能目录。
248
287
  - [docs/FAQ.md](FAQ.md) —— 恢复场景与运维问答。
249
288
  - [docs/MIGRATION.md](MIGRATION.md) —— 从 cron、systemd、launchd 或任务计划程序迁移。
289
+ - [docs/PIPELINE.md](PIPELINE.md) —— 流水线即代码:文件格式、CLI、幂等 apply。
250
290
  - [docs/SAVINGS.md](SAVINGS.md) —— "Saved $" 估算如何计算。
251
291
  - [CROSS_PLATFORM.md](../CROSS_PLATFORM.md) —— Windows / macOS / Linux 的差异与后端。
252
292
 
package/docs/SAFETY.md ADDED
@@ -0,0 +1,142 @@
1
+ # SAFETY — контракт безопасности миссии
2
+
3
+ > Шаг 1 цикла v2.1. Принцип: **продукт для людей** — не сломать репо, не слить
4
+ > данные, не разорить. Порядок столпов: надёжно > приватно > дёшево > фичи.
5
+ > Контракт одинаков для **ad-hoc**, внутренних и registered запусков.
6
+
7
+ ## 1. Классы риска
8
+
9
+ | Класс | Что делает | Примеры | Default |
10
+ |-------|-----------|---------|---------|
11
+ | **R0** read-only | Читает, ничего не меняет | анализ, отчёт, обзор | разрешён |
12
+ | **R1** local-write | Меняет файлы в изолированном worktree | правка кода, бойлерплейт | разрешён в worktree |
13
+ | **R2** external-effect | Меняет внешнее состояние | git push, PR, API-запись, деплой | **approval + отложенные эффекты** |
14
+ | **R3** destructive / egress | Удаляет, льёт данные наружу | reset --hard, удаление, отправка наружу | **approval + явный opt-in** |
15
+
16
+ Класс определяется по **инструментам и командам**, а не по описанию миссии.
17
+
18
+ ## 2. Компиляция политики (принуждение, не декларация)
19
+
20
+ ```
21
+ risk R2 → allowedTools: [read, edit, glob, grep]
22
+ deniedTools: [shell]
23
+ egress: [] (кроме явного allowlist)
24
+ requiredGates: [tests, lint, approval]
25
+ effects: deferred (intents)
26
+ budget: из контракта
27
+ ```
28
+
29
+ - Enforcement — существующие `permissions` / `OPENCODE_CONFIG_CONTENT` +
30
+ egress-контроль на уровне исполнения.
31
+ - `policy_hash` пишется в ledger; изменение политики посреди миссии → `fail` +
32
+ аудит-инцидент.
33
+ - Внешние policy-движки (OPA/Cedar) на этом этапе не используем: локальная одна
34
+ машина, мало зависимостей.
35
+
36
+ ## 3. Capability issuance на шаг
37
+
38
+ - Агент получает **scoped-конфиг ровно на шаг**, не на миссию.
39
+ - Секреты — короткоживущая инъекция только используемых (`collectSecretNames`),
40
+ очистка после шага.
41
+ - Никаких долгоживущих токенов в окружении задачи.
42
+
43
+ ## 4. Уровни изоляции
44
+
45
+ | Уровень | Механизм | Когда |
46
+ |---------|----------|-------|
47
+ | 1 (opt-in: `worktree: true`) | git worktree | R0/R1, когда включено у задачи |
48
+ | 2 | OS-jail: ограничение ФС/процессов | R1 с недоверенным контентом |
49
+ | 3 | Docker runner (opt-in, спринт 46) | R2/R3, недоверенные зависимости |
50
+
51
+ **Worktree не защищает от сети/API/БД** — поэтому обязателен следующий раздел.
52
+
53
+ ## 5. Отложенные внешние эффекты
54
+
55
+ 1. До гейта агент **не выполняет** irreversible-действие, а пишет `effect_intents`.
56
+ 2. Гейт проверяет артефакт и валидность intents (политика, egress, blast-radius).
57
+ 3. `pass` → применение, отметка `effects_applied_at`.
58
+ 4. `fail` → discard; частично применённые — компенсация (saga).
59
+
60
+ Так «локальность» действительно ограничивает ущерб, а не только конфликты файлов.
61
+
62
+ ## 6. Blast-radius
63
+
64
+ - Работа в worktree; основное дерево не трогается до принятия.
65
+ - Одноразовый worktree удаляется после прогона; остатки старше суток выметаются,
66
+ sidecar без рабочей копии очищается, чужие каталоги и свежие запуски не трогаются.
67
+ - Запрет push в защищённые ветки; лимит числа файлов и объёма diff.
68
+ - Opt-in guards (W-3): shell-`command` и/или `semantic`-условия (`filesExist`/
69
+ `filesMissing`, `branch` glob, `changedPaths` в `changedSince..HEAD`); любая
70
+ ошибка или невыполненное условие — запуск пропущен (fail-closed), видимый
71
+ статус `skipped` — в W-4.
72
+ - Egress только по явному allowlist; всё в аудит.
73
+ - Destructive-команды запрещены без явного разрешения в контракте.
74
+
75
+ ## 7. Бюджет миссии (живой)
76
+
77
+ ```yaml
78
+ budget:
79
+ maxUsd: 0.50
80
+ maxTokens: 200000
81
+ maxMinutes: 30
82
+ maxEscalations: 2
83
+ ```
84
+
85
+ Счётчик ведётся в durable-run и учитывает **верификацию и эскалации**. При
86
+ подходе к границе роутинг предлагает более дешёвую модель или `review`;
87
+ превышение → circuit-breaker, статус `review`, уведомление.
88
+
89
+ ## 8. Approval-матрица
90
+
91
+ | Условие | Требуется |
92
+ |---------|-----------|
93
+ | R0 / R1 в worktree | нет |
94
+ | R2 (внешний эффект) | approval + отложенные эффекты |
95
+ | R3 (destructive / egress) | approval + явный opt-in |
96
+ | Превышен бюджет | остановка + review |
97
+ | Capability-карта даёт `review` | очередь человеку с evidence |
98
+
99
+ `approval` — **тип гейта**. Исполнение — на существующей паузе с инъекциями:
100
+ paused-миссия **не потребляет compute**, комментарий человека доставляется шагу
101
+ при resume.
102
+
103
+ ## 9. Least privilege и недоверенный контент
104
+
105
+ - Политика прав задачи (`hybrid` по умолчанию) — пол, не потолок.
106
+ - Gate-файлы и gate-команда вне write-scope агента.
107
+ - Внешний контент (web, issues, PR) — недоверенный по умолчанию: prompt-injection
108
+ учитывается как угроза.
109
+ - Секреты маскируются в логах, истории и аудите.
110
+
111
+ ## 10. Kill switch
112
+
113
+ - Остановка миссии в любой момент; откат worktree чистый, intents отбрасываются.
114
+ - Глобальная пауза планировщика останавливает новые **registered** запуски;
115
+ ad-hoc миссии можно запускать и на паузе планировщика (это разные подсистемы).
116
+
117
+ ## 11. Ad-hoc миссии (AB-8)
118
+
119
+ Ad-hoc запуск (`run_mission`, CLI `agent-steward run`, GUI, RPC) строит тот же
120
+ `RunContext`, что и registered-задача: политика `hybrid` по умолчанию,
121
+ `allowedTools` / `deniedTools`, Quality Gate и таймаут передаются в обёртку,
122
+ а результат пишется в `runs` / `run_steps` с `metadata.adHoc = true`. Записи в
123
+ Task Scheduler, launchd или crontab не создаются. Один workspace — одна
124
+ активная миссия: параллельный запуск в том же каталоге отклоняется. `dryRun`
125
+ показывает план и маршрут, не создавая run.
126
+
127
+ ## 12. Инварианты (проверяются тестами)
128
+
129
+ 1. Миссия без gate-спеки не принимается.
130
+ 2. Миссия без safety-контракта получает safe-default (R1, worktree, бюджет).
131
+ 3. R2/R3 без approval не стартует.
132
+ 4. Агент не получает инструмент, запрещённый скомпилированной политикой.
133
+ 5. Подмена gate-файла/команды детектируется: обёртка сверяет snapshot и хэш
134
+ входов гейта перед запуском и падает fail-closed (`gate-integrity.ts`).
135
+ Это обнаружение до вердикта, а не абсолютная изоляция прав: каталог гейта
136
+ находится вне write-scope задачи, но файлы не были бы защищены от процесса
137
+ с привилегиями пользователя.
138
+ 6. Irreversible-действие невозможно до `pass`.
139
+ 7. Превышение бюджета останавливает миссию.
140
+ 8. Каждый вердикт, эскалация и применение эффектов попадают в аудит.
141
+ 9. **Ad-hoc миссия проходит ту же политику, бюджет и gate, что и registered.**
142
+ 10. **Ad-hoc миссия не создаёт записей в планировщике ОС.**