akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

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 (587) hide show
  1. package/CHANGELOG.md +1190 -52
  2. package/README.md +62 -37
  3. package/SECURITY.md +46 -31
  4. package/dist/akm +162 -38
  5. package/dist/akm-migrate +44 -0
  6. package/dist/assets/backends/schtasks-template.xml +2 -1
  7. package/dist/assets/hints/cli-hints-full.md +268 -118
  8. package/dist/assets/hints/cli-hints-short.md +87 -24
  9. package/dist/assets/{profiles → improve-strategies}/catchup.json +3 -1
  10. package/dist/assets/{profiles → improve-strategies}/consolidate.json +3 -1
  11. package/dist/assets/{profiles → improve-strategies}/default.json +6 -7
  12. package/dist/assets/improve-strategies/frequent.json +15 -0
  13. package/dist/assets/{profiles → improve-strategies}/graph-refresh.json +4 -2
  14. package/dist/assets/{profiles → improve-strategies}/memory-focus.json +4 -1
  15. package/dist/assets/{profiles → improve-strategies}/proactive-maintenance.json +5 -5
  16. package/dist/assets/{profiles → improve-strategies}/quick.json +4 -2
  17. package/dist/assets/improve-strategies/reflect-distill.json +30 -0
  18. package/dist/assets/{profiles → improve-strategies}/thorough.json +1 -1
  19. package/dist/assets/prompts/consolidate-system.md +5 -5
  20. package/dist/assets/prompts/extract-session.md +2 -6
  21. package/dist/assets/prompts/memory-infer-user.md +2 -3
  22. package/dist/assets/prompts/reflect-llm-framed-contract.md +11 -0
  23. package/dist/assets/prompts/reflect-llm-schema-contract.md +3 -0
  24. package/dist/assets/prompts/reflect-output-repair.md +3 -0
  25. package/dist/assets/stash-skeleton/README.md +38 -10
  26. package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md +8 -0
  27. package/dist/assets/stash-skeleton/facts/conventions/assets/command.md +8 -0
  28. package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md +14 -1
  29. package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md +13 -1
  30. package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md +9 -1
  31. package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md +11 -0
  32. package/dist/assets/stash-skeleton/facts/conventions/assets/script.md +9 -0
  33. package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md +9 -0
  34. package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md +8 -0
  35. package/dist/assets/stash-skeleton/facts/conventions/backlinks.md +100 -0
  36. package/dist/assets/stash-skeleton/facts/conventions/domains.md +64 -0
  37. package/dist/assets/stash-skeleton/facts/conventions/organization.md +136 -0
  38. package/dist/assets/tasks/core/extract.yml +3 -2
  39. package/dist/assets/tasks/core/improve.yml +2 -1
  40. package/dist/assets/tasks/core/index-refresh.yml +1 -0
  41. package/dist/assets/tasks/core/sync.yml +1 -0
  42. package/dist/assets/tasks/core/version-check.yml +2 -1
  43. package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml +5 -0
  44. package/dist/assets/tasks/improve/akm-improve-catchup.yml +8 -0
  45. package/dist/assets/tasks/improve/akm-improve-consolidate.yml +5 -0
  46. package/dist/assets/tasks/improve/akm-improve-frequent.yml +5 -0
  47. package/dist/assets/tasks/improve/akm-improve-nightly.yml +5 -0
  48. package/dist/assets/templates/html/health.html +5 -4
  49. package/dist/assets/workflows/workflow-template.md +31 -15
  50. package/dist/cli/invocation.js +279 -0
  51. package/dist/cli/parse-args.js +5 -90
  52. package/dist/cli/retired-commands.js +78 -0
  53. package/dist/cli/shared.js +158 -48
  54. package/dist/cli-node.mjs +2 -1
  55. package/dist/cli.js +747 -293
  56. package/dist/commands/agent/agent-dispatch.js +19 -18
  57. package/dist/commands/agent/agent-support.js +0 -24
  58. package/dist/commands/agent/contribute-cli.js +43 -97
  59. package/dist/commands/completions.js +80 -23
  60. package/dist/commands/config-cli.js +44 -281
  61. package/dist/commands/env/env-binding.js +13 -9
  62. package/dist/commands/env/env-cli.js +76 -159
  63. package/dist/commands/env/env.js +12 -163
  64. package/dist/commands/env/marker-path.js +6 -0
  65. package/dist/commands/env/secret-cli.js +45 -61
  66. package/dist/commands/env/secret.js +32 -62
  67. package/dist/commands/feedback-cli.js +179 -85
  68. package/dist/commands/health/accept-rate.js +58 -0
  69. package/dist/commands/health/advisories.js +7 -8
  70. package/dist/commands/health/checks.js +279 -94
  71. package/dist/commands/health/html-report.js +197 -578
  72. package/dist/commands/health/improve-metrics.js +277 -246
  73. package/dist/commands/health/llm-usage.js +19 -19
  74. package/dist/commands/health/md-report.js +16 -7
  75. package/dist/commands/health/metrics.js +67 -32
  76. package/dist/commands/health/renderers.js +47 -0
  77. package/dist/commands/health/report-view-model.js +508 -0
  78. package/dist/commands/health/stash-exposure.js +1 -1
  79. package/dist/commands/health/surfaces.js +16 -56
  80. package/dist/commands/health/task-runs.js +3 -67
  81. package/dist/{migrate-storage-node.mjs → commands/health/types-checks.js} +1 -5
  82. package/dist/commands/health/types-improve.js +29 -0
  83. package/dist/{output/text/save.js → commands/health/types-metrics.js} +1 -2
  84. package/dist/commands/health/types-result.js +7 -0
  85. package/dist/commands/health/types-runs.js +4 -0
  86. package/dist/commands/health/types-session-log.js +4 -0
  87. package/dist/commands/health/types-windows.js +4 -0
  88. package/dist/commands/health/types.js +26 -21
  89. package/dist/commands/health/windows.js +2 -3
  90. package/dist/commands/health.js +296 -167
  91. package/dist/commands/improve/anti-collapse.js +5 -5
  92. package/dist/commands/improve/autonomy-gate.js +68 -0
  93. package/dist/commands/improve/collapse-detector.js +65 -52
  94. package/dist/commands/improve/consolidate/chunking.js +9 -7
  95. package/dist/commands/improve/consolidate/eligibility.js +1 -23
  96. package/dist/commands/improve/consolidate/merge.js +4 -0
  97. package/dist/commands/improve/consolidate.js +454 -1354
  98. package/dist/commands/improve/content-hash.js +39 -0
  99. package/dist/commands/improve/distill/content-repair.js +4 -10
  100. package/dist/commands/improve/distill/promote-memory.js +89 -64
  101. package/dist/commands/improve/distill/quality-gate.js +118 -42
  102. package/dist/commands/improve/distill-guards.js +1 -1
  103. package/dist/commands/improve/distill-promotion-policy.js +33 -888
  104. package/dist/commands/improve/distill.js +607 -363
  105. package/dist/commands/improve/eligibility.js +165 -79
  106. package/dist/commands/improve/extract-cli.js +35 -126
  107. package/dist/commands/improve/extract-prompt.js +6 -35
  108. package/dist/commands/improve/extract.js +640 -391
  109. package/dist/commands/improve/feedback-valence.js +2 -12
  110. package/dist/commands/improve/improve-cli.js +134 -135
  111. package/dist/commands/improve/improve-result-file.js +30 -50
  112. package/dist/commands/improve/improve-run-types.js +4 -0
  113. package/dist/commands/improve/improve-strategies.js +135 -0
  114. package/dist/commands/improve/improve.js +904 -701
  115. package/dist/commands/improve/locks.js +64 -111
  116. package/dist/commands/improve/loop-stages.js +1110 -923
  117. package/dist/commands/improve/memory/derived-ref.js +124 -0
  118. package/dist/commands/improve/memory/memory-belief.js +79 -7
  119. package/dist/commands/improve/memory/memory-contradiction-detect.js +49 -52
  120. package/dist/commands/improve/memory/memory-improve.js +25 -37
  121. package/dist/commands/improve/outcome-loop.js +25 -88
  122. package/dist/commands/improve/preparation.js +1034 -813
  123. package/dist/commands/improve/proactive-maintenance.js +34 -9
  124. package/dist/commands/improve/proposal-envelope.js +31 -0
  125. package/dist/commands/improve/reflect.js +983 -794
  126. package/dist/commands/improve/run-context.js +119 -0
  127. package/dist/commands/improve/salience.js +24 -127
  128. package/dist/commands/improve/session-asset.js +7 -3
  129. package/dist/commands/improve/shared.js +14 -34
  130. package/dist/commands/improve/source-identity.js +28 -0
  131. package/dist/commands/improve/triage.js +20 -17
  132. package/dist/commands/lint/base-linter.js +340 -313
  133. package/dist/commands/lint/env-key-rules.js +31 -47
  134. package/dist/commands/lint/index.js +185 -30
  135. package/dist/commands/{events.js → log.js} +28 -38
  136. package/dist/commands/migrate-cli.js +54 -0
  137. package/dist/commands/migration-tool.js +55 -0
  138. package/dist/commands/observability-cli.js +70 -208
  139. package/dist/commands/proposal/diff-format.js +50 -0
  140. package/dist/commands/proposal/drain-policies.js +0 -6
  141. package/dist/commands/proposal/drain.js +91 -40
  142. package/dist/commands/proposal/proposal-cli.js +134 -132
  143. package/dist/commands/proposal/proposal-types.js +56 -0
  144. package/dist/commands/proposal/proposal.js +83 -65
  145. package/dist/commands/proposal/propose-cli.js +88 -0
  146. package/dist/commands/proposal/propose.js +105 -88
  147. package/dist/commands/proposal/repository.js +1303 -278
  148. package/dist/commands/proposal/validators/proposal-quality-validators.js +16 -6
  149. package/dist/commands/proposal/validators/proposal-validators.js +61 -12
  150. package/dist/commands/proposal/validators/proposals.js +6 -8
  151. package/dist/commands/read/curate.js +78 -73
  152. package/dist/commands/read/knowledge.js +510 -13
  153. package/dist/commands/read/registry-search.js +2 -2
  154. package/dist/commands/read/remember-cli.js +84 -15
  155. package/dist/commands/read/search-cli.js +203 -96
  156. package/dist/commands/read/search.js +126 -94
  157. package/dist/commands/read/show.js +226 -250
  158. package/dist/commands/registry-cli.js +34 -60
  159. package/dist/commands/remember.js +18 -57
  160. package/dist/commands/sources/add-cli.js +104 -49
  161. package/dist/commands/sources/bundle-cli.js +166 -0
  162. package/dist/commands/sources/bundle-config-ops.js +63 -0
  163. package/dist/commands/sources/info.js +27 -15
  164. package/dist/commands/sources/init.js +30 -40
  165. package/dist/commands/sources/installed-stashes.js +469 -172
  166. package/dist/commands/sources/schema-repair.js +10 -9
  167. package/dist/commands/sources/self-update.js +182 -121
  168. package/dist/commands/sources/source-add.js +169 -178
  169. package/dist/commands/sources/source-clone.js +144 -41
  170. package/dist/commands/sources/source-manage.js +94 -59
  171. package/dist/commands/sources/sources-cli.js +64 -205
  172. package/dist/commands/sources/stash-cli.js +91 -54
  173. package/dist/commands/sources/stash-skeleton.js +1 -1
  174. package/dist/commands/tasks/tasks-cli.js +106 -104
  175. package/dist/commands/tasks/tasks.js +445 -262
  176. package/dist/commands/workflow-cli.js +75 -228
  177. package/dist/core/action-contributors.js +1 -1
  178. package/dist/core/activation-policy.js +49 -0
  179. package/dist/core/adapter/adapters/agent-skills-adapter.js +181 -0
  180. package/dist/core/adapter/adapters/akm-adapter.js +528 -0
  181. package/dist/core/adapter/adapters/akm-lint.js +392 -0
  182. package/dist/core/adapter/adapters/akm-metadata.js +387 -0
  183. package/dist/core/adapter/adapters/akm-task-adapter.js +149 -0
  184. package/dist/core/adapter/adapters/akm-workflow-adapter.js +180 -0
  185. package/dist/core/adapter/adapters/claude-adapter.js +61 -0
  186. package/dist/core/adapter/adapters/dotenv-adapter.js +187 -0
  187. package/dist/core/adapter/adapters/generic-files-adapter.js +119 -0
  188. package/dist/core/adapter/adapters/index.js +80 -0
  189. package/dist/core/adapter/adapters/llm-wiki-adapter.js +419 -0
  190. package/dist/core/adapter/adapters/okf-adapter.js +391 -0
  191. package/dist/core/adapter/adapters/opencode-adapter.js +68 -0
  192. package/dist/core/adapter/adapters/shared.js +286 -0
  193. package/dist/core/adapter/adapters/tool-dir-shared.js +217 -0
  194. package/dist/core/adapter/adapters/website-snapshot-adapter.js +155 -0
  195. package/dist/core/adapter/bundle-adapter.js +4 -0
  196. package/dist/core/adapter/detect-adapter.js +17 -0
  197. package/dist/core/adapter/recognize-match.js +44 -0
  198. package/dist/core/adapter/registry.js +56 -0
  199. package/dist/core/adapter/types.js +4 -0
  200. package/dist/core/asset/akm-markdown.js +30 -0
  201. package/dist/core/asset/asset-placement.js +243 -0
  202. package/dist/core/asset/asset-ref.js +110 -79
  203. package/dist/core/asset/asset-serialize.js +20 -0
  204. package/dist/core/asset/frontmatter.js +28 -12
  205. package/dist/core/asset/markdown.js +40 -51
  206. package/dist/core/asset/resolve-ref.js +274 -0
  207. package/dist/core/asset/stash-meta.js +2 -2
  208. package/dist/core/bundle-id.js +51 -0
  209. package/dist/core/common.js +281 -86
  210. package/dist/core/config/config-io.js +42 -128
  211. package/dist/core/config/config-schema.js +233 -855
  212. package/dist/core/config/config-sources.js +162 -39
  213. package/dist/core/config/config-types.js +16 -11
  214. package/dist/core/config/config-version.js +29 -0
  215. package/dist/core/config/config-walker.js +126 -37
  216. package/dist/core/config/config.js +154 -331
  217. package/dist/core/config/deep-merge.js +41 -0
  218. package/dist/core/config/engine-semantics.js +28 -0
  219. package/dist/core/config/experimental.js +21 -0
  220. package/dist/core/config/schema/embedding.js +38 -0
  221. package/dist/core/config/schema/engines.js +116 -0
  222. package/dist/core/config/schema/experimental.js +47 -0
  223. package/dist/core/config/schema/feedback.js +31 -0
  224. package/dist/core/config/schema/improve-processes.js +389 -0
  225. package/dist/core/config/schema/improve.js +94 -0
  226. package/dist/core/config/schema/index-config.js +176 -0
  227. package/dist/core/config/schema/output.js +18 -0
  228. package/dist/core/config/schema/primitives.js +94 -0
  229. package/dist/core/config/schema/search.js +30 -0
  230. package/dist/core/config/schema/setup.js +18 -0
  231. package/dist/core/config/schema/sources-bundles.js +169 -0
  232. package/dist/core/config/schema/workflow.js +29 -0
  233. package/dist/core/env-secret-ref.js +155 -20
  234. package/dist/core/errors.js +17 -15
  235. package/dist/core/events-types.js +4 -0
  236. package/dist/core/events.js +46 -128
  237. package/dist/core/extra-params.js +62 -0
  238. package/dist/core/file-change.js +17 -0
  239. package/dist/core/file-lock.js +202 -57
  240. package/dist/core/fs-txn.js +392 -0
  241. package/dist/core/git-message.js +59 -0
  242. package/dist/core/improve-result.js +167 -0
  243. package/dist/core/lesson-lint.js +1 -17
  244. package/dist/core/logs-db.js +1 -1
  245. package/dist/core/maintenance-barrier.js +135 -0
  246. package/dist/core/migration-operation.js +44 -0
  247. package/dist/core/mutation-target.js +78 -0
  248. package/dist/core/paths.js +22 -25
  249. package/dist/core/platform.js +10 -0
  250. package/dist/core/recognition-util.js +128 -0
  251. package/dist/core/redaction.js +392 -0
  252. package/dist/core/standards/resolve-standards-context.js +36 -65
  253. package/dist/core/standards/resolve-stash-standards.js +2 -2
  254. package/dist/core/standards/resolve-type-conventions.js +5 -5
  255. package/dist/core/state/migrations.js +242 -11
  256. package/dist/core/state-db.js +98 -10
  257. package/dist/core/structured.js +1 -1
  258. package/dist/core/subprocess.js +303 -0
  259. package/dist/core/text-truncation.js +9 -5
  260. package/dist/core/time.js +20 -0
  261. package/dist/core/type-presentation.js +130 -0
  262. package/dist/core/warn.js +0 -3
  263. package/dist/core/write-source.js +834 -118
  264. package/dist/indexer/bundle-identity-guard.js +92 -0
  265. package/dist/indexer/db/graph-db.js +1 -25
  266. package/dist/indexer/db/llm-cache.js +1 -1
  267. package/dist/indexer/ensure-index.js +30 -9
  268. package/dist/indexer/graph/graph-boost.js +9 -30
  269. package/dist/indexer/graph/graph-extraction.js +41 -27
  270. package/dist/indexer/graph/graph-types.js +4 -0
  271. package/dist/indexer/index-writer-lock.js +93 -49
  272. package/dist/indexer/index-written-assets.js +100 -53
  273. package/dist/indexer/indexer.js +746 -329
  274. package/dist/indexer/init.js +18 -25
  275. package/dist/indexer/installations.js +142 -0
  276. package/dist/indexer/passes/dir-staleness.js +18 -10
  277. package/dist/indexer/passes/memory-inference.js +25 -15
  278. package/dist/indexer/passes/metadata.js +412 -243
  279. package/dist/indexer/scan/doc-to-entry.js +160 -0
  280. package/dist/indexer/scan/drain-dir.js +134 -0
  281. package/dist/indexer/search/db-search.js +292 -108
  282. package/dist/indexer/search/fts-query.js +64 -0
  283. package/dist/indexer/search/ranking-contributors.js +145 -25
  284. package/dist/indexer/search/ranking-types.js +4 -0
  285. package/dist/indexer/search/ranking.js +28 -71
  286. package/dist/indexer/search/search-attribution.js +67 -0
  287. package/dist/indexer/search/search-fields.js +18 -3
  288. package/dist/indexer/search/search-hit-enrichers.js +30 -40
  289. package/dist/indexer/search/search-source.js +157 -111
  290. package/dist/indexer/search/semantic-status.js +4 -1
  291. package/dist/indexer/usage/usage-events.js +10 -30
  292. package/dist/indexer/walk/file-context.js +3 -45
  293. package/dist/indexer/walk/matchers.js +42 -73
  294. package/dist/indexer/walk/path-resolver.js +11 -5
  295. package/dist/indexer/walk/walker.js +42 -14
  296. package/dist/integrations/agent/builder-shared.js +7 -0
  297. package/dist/integrations/agent/builders.js +5 -58
  298. package/dist/integrations/agent/config.js +3 -143
  299. package/dist/integrations/agent/detect.js +17 -2
  300. package/dist/integrations/agent/engine-resolution.js +231 -0
  301. package/dist/integrations/agent/index.js +1 -2
  302. package/dist/integrations/agent/model-aliases.js +8 -3
  303. package/dist/integrations/agent/profiles.js +6 -99
  304. package/dist/integrations/agent/prompts.js +46 -18
  305. package/dist/integrations/agent/runner-dispatch.js +78 -13
  306. package/dist/integrations/agent/runner.js +76 -208
  307. package/dist/integrations/agent/spawn.js +48 -279
  308. package/dist/integrations/harnesses/aider/agent-builder.js +9 -8
  309. package/dist/integrations/harnesses/aider/index.js +2 -12
  310. package/dist/integrations/harnesses/amazonq/agent-builder.js +10 -16
  311. package/dist/integrations/harnesses/amazonq/index.js +3 -17
  312. package/dist/integrations/harnesses/claude/agent-builder.js +2 -3
  313. package/dist/integrations/harnesses/claude/config-import.js +1 -3
  314. package/dist/integrations/harnesses/claude/index.js +1 -14
  315. package/dist/integrations/harnesses/claude/session-log.js +27 -75
  316. package/dist/integrations/harnesses/codex/agent-builder.js +8 -7
  317. package/dist/integrations/harnesses/codex/index.js +2 -13
  318. package/dist/integrations/harnesses/copilot/agent-builder.js +9 -9
  319. package/dist/integrations/harnesses/copilot/index.js +1 -13
  320. package/dist/integrations/harnesses/gemini/agent-builder.js +8 -9
  321. package/dist/integrations/harnesses/gemini/index.js +1 -13
  322. package/dist/integrations/harnesses/ids.js +24 -0
  323. package/dist/integrations/harnesses/index.js +31 -33
  324. package/dist/integrations/harnesses/opencode/agent-builder.js +23 -5
  325. package/dist/integrations/harnesses/opencode/config-import.js +1 -3
  326. package/dist/integrations/harnesses/opencode/index.js +1 -18
  327. package/dist/integrations/harnesses/opencode/session-log.js +67 -125
  328. package/dist/integrations/harnesses/opencode-sdk/harness.js +3 -17
  329. package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +274 -191
  330. package/dist/integrations/harnesses/openhands/agent-builder.js +12 -10
  331. package/dist/integrations/harnesses/openhands/index.js +2 -12
  332. package/dist/integrations/harnesses/pi/agent-builder.js +11 -18
  333. package/dist/integrations/harnesses/pi/index.js +3 -16
  334. package/dist/integrations/harnesses/shared.js +17 -0
  335. package/dist/integrations/harnesses/types.js +38 -34
  336. package/dist/integrations/lockfile.js +211 -24
  337. package/dist/integrations/session-logs/index.js +24 -40
  338. package/dist/integrations/session-logs/provider-base.js +113 -0
  339. package/dist/llm/client.js +182 -110
  340. package/dist/llm/embedders/deterministic.js +2 -2
  341. package/dist/llm/embedders/remote.js +21 -9
  342. package/dist/llm/feature-gate.js +17 -57
  343. package/dist/llm/graph-extract.js +12 -13
  344. package/dist/llm/index-passes.js +8 -42
  345. package/dist/llm/memory-infer.js +144 -1
  346. package/dist/llm/metadata-enhance.js +45 -30
  347. package/dist/llm/structured-call.js +16 -8
  348. package/dist/llm/usage-persist.js +30 -5
  349. package/dist/llm/usage-telemetry.js +59 -6
  350. package/dist/output/cli-hints.js +1 -2
  351. package/dist/output/command-registry.js +27 -0
  352. package/dist/output/context.js +22 -7
  353. package/dist/output/format-exempt.js +80 -0
  354. package/dist/output/generic-render.js +251 -0
  355. package/dist/output/html-render.js +11 -16
  356. package/dist/output/render-registry.js +57 -0
  357. package/dist/output/renderers.js +15 -281
  358. package/dist/output/shapes/curate.js +10 -1
  359. package/dist/output/shapes/events.js +12 -7
  360. package/dist/output/shapes/helpers.js +58 -84
  361. package/dist/output/shapes/passthrough.js +8 -40
  362. package/dist/output/shapes/proposal/producer.js +15 -7
  363. package/dist/output/shapes/registry.js +12 -6
  364. package/dist/output/shapes.js +0 -9
  365. package/dist/output/text/{init.js → bundle-create.js} +3 -1
  366. package/dist/output/text/bundle-show.js +7 -0
  367. package/dist/output/text/command-format.js +562 -0
  368. package/dist/output/text/env.js +1 -3
  369. package/dist/output/text/events.js +8 -7
  370. package/dist/output/text/helpers.js +15 -1375
  371. package/dist/output/text/proposal/producer.js +4 -2
  372. package/dist/output/text/proposal-format.js +202 -0
  373. package/dist/output/text/registry-commands.js +1 -2
  374. package/dist/output/text/registry.js +12 -6
  375. package/dist/output/text/show-directives.js +117 -0
  376. package/dist/output/text/show-format.js +103 -0
  377. package/dist/output/text/sync.js +5 -0
  378. package/dist/output/text/workflow-format.js +332 -0
  379. package/dist/output/text/workflow.js +1 -2
  380. package/dist/output/text.js +10 -19
  381. package/dist/registry/factory.js +4 -6
  382. package/dist/registry/origin-resolve.js +16 -27
  383. package/dist/registry/providers/skills-sh.js +3 -3
  384. package/dist/registry/providers/static-index.js +15 -25
  385. package/dist/registry/resolve.js +43 -94
  386. package/dist/registry/semver.js +43 -0
  387. package/dist/runtime.js +81 -12
  388. package/dist/scripts/akm-migrate.js +35529 -0
  389. package/dist/setup/detect.js +5 -7
  390. package/dist/setup/detected-engines.js +136 -0
  391. package/dist/setup/engine-config.js +100 -0
  392. package/dist/setup/registry-stash-loader.js +3 -3
  393. package/dist/setup/semantic-assets.js +12 -9
  394. package/dist/setup/setup.js +444 -208
  395. package/dist/setup/steps/connection-shared.js +120 -0
  396. package/dist/setup/steps/connection.js +108 -305
  397. package/dist/setup/steps/platforms.js +13 -12
  398. package/dist/setup/steps/semantic.js +15 -3
  399. package/dist/setup/steps/sources.js +21 -15
  400. package/dist/setup/steps/stashdir.js +6 -4
  401. package/dist/setup/steps/tasks.js +236 -119
  402. package/dist/setup/steps.js +3 -2
  403. package/dist/sources/freshness.js +39 -0
  404. package/dist/sources/provider-factory.js +11 -17
  405. package/dist/sources/providers/filesystem.js +2 -3
  406. package/dist/sources/providers/git-install.js +278 -34
  407. package/dist/sources/providers/git-provider.js +54 -56
  408. package/dist/sources/providers/git-stash.js +420 -91
  409. package/dist/sources/providers/git.js +2 -2
  410. package/dist/sources/providers/npm.js +16 -19
  411. package/dist/sources/providers/provider-utils.js +47 -22
  412. package/dist/sources/providers/sync-from-ref.js +3 -9
  413. package/dist/sources/providers/website.js +2 -2
  414. package/dist/sources/resolve.js +11 -10
  415. package/dist/sources/snapshot-fetchers/types.js +4 -0
  416. package/dist/sources/{website-ingest.js → snapshot-fetchers/website-ingest.js} +110 -41
  417. package/dist/storage/database.js +60 -4
  418. package/dist/storage/engines/sqlite-migrations.js +156 -5
  419. package/dist/storage/locations.js +1 -2
  420. package/dist/storage/repositories/canaries-repository.js +1 -1
  421. package/dist/storage/repositories/events-repository.js +51 -11
  422. package/dist/storage/repositories/improve-runs-repository.js +6 -32
  423. package/dist/storage/repositories/index-connection.js +79 -0
  424. package/dist/storage/repositories/index-db.js +4 -3
  425. package/dist/storage/repositories/index-entries-repository.js +863 -0
  426. package/dist/{indexer/db/entry-mapper.js → storage/repositories/index-entry-mapper.js} +19 -2
  427. package/dist/storage/repositories/index-entry-types.js +4 -0
  428. package/dist/storage/repositories/index-fts-repository.js +167 -0
  429. package/dist/storage/repositories/index-llm-cache-repository.js +108 -0
  430. package/dist/storage/repositories/index-meta-repository.js +49 -0
  431. package/dist/{indexer/db/schema.js → storage/repositories/index-schema.js} +226 -100
  432. package/dist/storage/repositories/index-sql.js +12 -0
  433. package/dist/storage/repositories/index-utility-repository.js +356 -0
  434. package/dist/storage/repositories/index-vec-repository.js +250 -0
  435. package/dist/storage/repositories/outcome-repository.js +119 -0
  436. package/dist/storage/repositories/proposals-repository.js +317 -75
  437. package/dist/storage/repositories/registry-cache.js +1 -1
  438. package/dist/storage/repositories/salience-repository.js +172 -0
  439. package/dist/storage/repositories/task-history-repository.js +110 -3
  440. package/dist/storage/repositories/workflow-runs-repository.js +68 -35
  441. package/dist/tasks/backends/cron.js +169 -46
  442. package/dist/tasks/backends/exec-utils.js +76 -3
  443. package/dist/tasks/backends/index.js +6 -9
  444. package/dist/tasks/backends/launchd.js +292 -55
  445. package/dist/tasks/backends/schtasks.js +557 -70
  446. package/dist/tasks/backends/types.js +4 -0
  447. package/dist/tasks/command-executable.js +93 -0
  448. package/dist/tasks/embedded.js +56 -38
  449. package/dist/tasks/parser.js +156 -64
  450. package/dist/tasks/resolve-akm-bin.js +144 -51
  451. package/dist/tasks/runner.js +377 -209
  452. package/dist/tasks/schedule.js +108 -19
  453. package/dist/tasks/scheduler-invocation.js +296 -0
  454. package/dist/tasks/schema.js +1 -1
  455. package/dist/tasks/task-id.js +35 -0
  456. package/dist/tasks/validator.js +30 -16
  457. package/dist/workflows/authoring/authoring.js +96 -148
  458. package/dist/workflows/authoring/scope-key.js +1 -1
  459. package/dist/workflows/cli.js +0 -20
  460. package/dist/workflows/concurrency-policy.js +15 -0
  461. package/dist/workflows/exec/brief.js +25 -59
  462. package/dist/workflows/exec/frozen-judge.js +47 -0
  463. package/dist/workflows/exec/native-executor.js +157 -94
  464. package/dist/workflows/exec/report.js +365 -200
  465. package/dist/workflows/exec/run-workflow.js +46 -40
  466. package/dist/workflows/exec/scheduler.js +12 -41
  467. package/dist/workflows/exec/step-work.js +239 -205
  468. package/dist/workflows/exec/workflow-engine-gate.js +67 -0
  469. package/dist/workflows/ir/compile.js +141 -283
  470. package/dist/workflows/ir/freeze.js +233 -0
  471. package/dist/workflows/ir/plan-hash.js +40 -5
  472. package/dist/workflows/ir/schema.js +537 -1
  473. package/dist/workflows/parser.js +878 -306
  474. package/dist/workflows/program/expressions.js +20 -208
  475. package/dist/workflows/program/schema.js +7 -10
  476. package/dist/workflows/renderer.js +99 -121
  477. package/dist/workflows/resource-limits.js +22 -0
  478. package/dist/workflows/runtime/checkin.js +1 -1
  479. package/dist/workflows/runtime/plan-classifier.js +131 -0
  480. package/dist/workflows/runtime/runs.js +200 -113
  481. package/dist/workflows/runtime/unit-checkin.js +1 -1
  482. package/dist/workflows/runtime/unit-phases.js +20 -0
  483. package/dist/workflows/runtime/workflow-asset-loader.js +235 -97
  484. package/dist/workflows/schema.js +1 -11
  485. package/dist/workflows/validate-summary.js +4 -26
  486. package/dist/workflows/validator.js +52 -30
  487. package/docs/README.md +42 -78
  488. package/docs/migration/README.md +8 -0
  489. package/docs/migration/release-notes/0.6.0.md +1 -1
  490. package/docs/migration/release-notes/0.7.0.md +9 -8
  491. package/docs/migration/release-notes/0.9.0.md +158 -14
  492. package/docs/migration/v0.7-to-v0.8.md +46 -47
  493. package/docs/migration/v0.8-to-v0.9.md +844 -0
  494. package/docs/reference/README.md +12 -0
  495. package/docs/reference/data-and-telemetry.md +333 -0
  496. package/package.json +21 -17
  497. package/schemas/akm-asset-envelope.json +93 -0
  498. package/schemas/akm-config.json +4636 -0
  499. package/schemas/akm-task.json +87 -0
  500. package/{dist/schemas → schemas}/akm-workflow.json +127 -82
  501. package/dist/akm-migrate-storage +0 -38
  502. package/dist/assets/help/help-accept.md +0 -12
  503. package/dist/assets/help/help-improve.md +0 -84
  504. package/dist/assets/help/help-proposals.md +0 -17
  505. package/dist/assets/help/help-propose.md +0 -17
  506. package/dist/assets/help/help-reject.md +0 -11
  507. package/dist/assets/profiles/frequent.json +0 -13
  508. package/dist/assets/profiles/recombine-only.json +0 -21
  509. package/dist/assets/profiles/reflect-distill.json +0 -30
  510. package/dist/assets/profiles/synthesize.json +0 -15
  511. package/dist/assets/prompts/procedural-system.md +0 -44
  512. package/dist/assets/prompts/recombine-system.md +0 -40
  513. package/dist/assets/prompts/staleness-detect-system.md +0 -6
  514. package/dist/assets/tasks/core/backup.yml +0 -4
  515. package/dist/assets/tasks/graph-refresh-weekly.yml +0 -10
  516. package/dist/assets/templates/html/default.html +0 -78
  517. package/dist/assets/templates/html/vendor/echarts.min.js +0 -45
  518. package/dist/assets/wiki/index-template.md +0 -12
  519. package/dist/assets/wiki/ingest-workflow-template.md +0 -83
  520. package/dist/assets/wiki/log-template.md +0 -8
  521. package/dist/assets/wiki/schema-template.md +0 -61
  522. package/dist/cli/config-migrate.js +0 -150
  523. package/dist/cli/config-validate.js +0 -39
  524. package/dist/commands/graph/graph-cli.js +0 -124
  525. package/dist/commands/graph/graph.js +0 -487
  526. package/dist/commands/improve/calibration.js +0 -161
  527. package/dist/commands/improve/dedup.js +0 -482
  528. package/dist/commands/improve/extract-watch.js +0 -140
  529. package/dist/commands/improve/hot-probation.js +0 -45
  530. package/dist/commands/improve/improve-auto-accept.js +0 -276
  531. package/dist/commands/improve/improve-profiles.js +0 -168
  532. package/dist/commands/improve/procedural.js +0 -398
  533. package/dist/commands/improve/recombine.js +0 -818
  534. package/dist/commands/improve/schema-similarity-gate.js +0 -168
  535. package/dist/commands/lint/agent-linter.js +0 -44
  536. package/dist/commands/lint/command-linter.js +0 -44
  537. package/dist/commands/lint/default-linter.js +0 -16
  538. package/dist/commands/lint/fact-linter.js +0 -39
  539. package/dist/commands/lint/knowledge-linter.js +0 -16
  540. package/dist/commands/lint/memory-linter.js +0 -61
  541. package/dist/commands/lint/registry.js +0 -41
  542. package/dist/commands/lint/skill-linter.js +0 -45
  543. package/dist/commands/lint/task-linter.js +0 -50
  544. package/dist/commands/lint/workflow-linter.js +0 -81
  545. package/dist/commands/proposal/legacy-import.js +0 -115
  546. package/dist/commands/sources/history.js +0 -196
  547. package/dist/commands/tasks/default-tasks.js +0 -186
  548. package/dist/commands/wiki-cli.js +0 -292
  549. package/dist/core/asset/asset-registry.js +0 -76
  550. package/dist/core/asset/asset-spec.js +0 -316
  551. package/dist/core/config/config-migration.js +0 -602
  552. package/dist/core/deep-merge.js +0 -38
  553. package/dist/core/eval/rank-metrics.js +0 -113
  554. package/dist/core/ripgrep/install.js +0 -163
  555. package/dist/core/ripgrep/resolve.js +0 -81
  556. package/dist/indexer/db/db.js +0 -1414
  557. package/dist/indexer/manifest.js +0 -170
  558. package/dist/indexer/passes/metadata-contributors.js +0 -31
  559. package/dist/indexer/usage/unmigrated-vaults-guard.js +0 -94
  560. package/dist/integrations/harnesses/opencode-sdk/index.js +0 -25
  561. package/dist/llm/call-ai.js +0 -62
  562. package/dist/llm/memory-infer-impl.js +0 -138
  563. package/dist/output/shapes/distill.js +0 -14
  564. package/dist/output/shapes/history.js +0 -11
  565. package/dist/output/text/distill.js +0 -6
  566. package/dist/output/text/enable-disable.js +0 -8
  567. package/dist/output/text/history.js +0 -6
  568. package/dist/output/text/wiki.js +0 -16
  569. package/dist/registry/build-index.js +0 -386
  570. package/dist/schemas/akm-config.json +0 -14225
  571. package/dist/scripts/migrate-storage.js +0 -13169
  572. package/dist/scripts/migrations/import-fs-improve-runs-to-db.js +0 -10169
  573. package/dist/scripts/migrations/v16-to-v17.js +0 -141
  574. package/dist/setup/legacy-config.js +0 -106
  575. package/dist/storage/repositories/consolidation-repository.js +0 -38
  576. package/dist/storage/repositories/recombine-repository.js +0 -213
  577. package/dist/wiki/wiki-templates.js +0 -15
  578. package/dist/wiki/wiki.js +0 -1012
  579. package/dist/workflows/authoring/workflow-program-template.yaml +0 -31
  580. package/dist/workflows/db.js +0 -350
  581. package/dist/workflows/exec/watch.js +0 -116
  582. package/dist/workflows/program/parser.js +0 -760
  583. package/dist/workflows/program/project.js +0 -105
  584. package/docs/data-and-telemetry.md +0 -227
  585. package/docs/migration/release-notes/0.9.0-beta.60.md +0 -19
  586. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/registry.js +0 -0
  587. /package/dist/sources/{wiki-fetchers → snapshot-fetchers}/youtube.js +0 -0
@@ -1,31 +0,0 @@
1
- # akm YAML workflow program (redesign addendum, v1).
2
- # Save under workflows/<name>.yaml and lint with:
3
- # akm workflow validate workflows/<name>.yaml
4
- version: 1
5
- name: example-workflow
6
- description: Describe what this workflow accomplishes.
7
-
8
- params:
9
- example_param: { type: string, description: Explain this parameter }
10
-
11
- defaults: # run-level defaults, overridable per unit
12
- runner: inherit # llm | agent | sdk | inherit
13
- timeout: 10m # "<n>ms" | "<n>s" | "<n>m" | "none"
14
- on_error: fail # fail | continue
15
-
16
- steps:
17
- - id: first-step
18
- title: First Step
19
- unit:
20
- instructions: |
21
- Describe what to do in this step.
22
- Reference run parameters explicitly: ${{ params.example_param }}.
23
- gate:
24
- criteria:
25
- - Confirm the first step is complete
26
-
27
- - id: second-step
28
- title: Second Step
29
- unit:
30
- instructions: |
31
- Describe what happens next.
@@ -1,350 +0,0 @@
1
- // This Source Code Form is subject to the terms of the Mozilla Public
2
- // License, v. 2.0. If a copy of the MPL was not distributed with this
3
- // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
- import fs from "node:fs";
5
- import path from "node:path";
6
- import { getWorkflowDbPath } from "../core/paths.js";
7
- import { openDatabase } from "../storage/database.js";
8
- import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
9
- import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
10
- /**
11
- * workflow.db — Durable SQLite database for workflow run state.
12
- *
13
- * Owns the `workflow_runs` and `workflow_run_steps` tables that track active /
14
- * completed workflow executions. Like `state.db` (and unlike `index.db`), the
15
- * rows here are NON-REGENERABLE — losing them is data loss. Schema must evolve
16
- * via incremental, additive migrations recorded in `schema_migrations`.
17
- *
18
- * ## Migration-safety contract
19
- *
20
- * The `schema_migrations` table records every applied migration by a stable
21
- * string ID. `runMigrations(db)` is idempotent: new installs run every
22
- * migration in order; upgrades run only the ones not yet applied. The
23
- * migration framework here intentionally mirrors `src/core/state-db.ts` so
24
- * future schema evolution follows a single proven pattern.
25
- *
26
- * Permitted schema evolution operations (always migration-safe in SQLite):
27
- * - ALTER TABLE … ADD COLUMN <name> <type> DEFAULT <value>
28
- * - CREATE INDEX IF NOT EXISTS …
29
- * - CREATE TABLE IF NOT EXISTS … (additive new tables)
30
- *
31
- * ## Bootstrapping pre-versioning databases
32
- *
33
- * Workflow databases created before this file gained `schema_migrations`
34
- * already have the `workflow_runs.scope_key` column applied by the previous
35
- * ad-hoc `PRAGMA table_info` + `ALTER TABLE` code. To avoid re-running the
36
- * migration (which would no-op but still wastes work and clutters logs), the
37
- * runner detects this state and back-fills the `schema_migrations` row for
38
- * the scope-key migration before evaluating the migration list. See
39
- * `bootstrapPreVersioningDb()`.
40
- *
41
- * @module workflows/db
42
- */
43
- // ── Public API ───────────────────────────────────────────────────────────────
44
- export function openWorkflowDatabase(dbPath = getWorkflowDbPath()) {
45
- const dir = path.dirname(dbPath);
46
- if (!fs.existsSync(dir)) {
47
- fs.mkdirSync(dir, { recursive: true });
48
- }
49
- const db = openDatabase(dbPath);
50
- // #589: 30 s busy timeout, matching index.db / state.db. Without it the
51
- // default is 0 ms, so any concurrent writer fails immediately with
52
- // SQLITE_BUSY. #628: journal_mode is configurable via AKM_SQLITE_JOURNAL_MODE.
53
- applyStandardPragmas(db, { dataDir: dir });
54
- ensureBaseSchema(db);
55
- runMigrations(db);
56
- return db;
57
- }
58
- export function closeWorkflowDatabase(db) {
59
- db.close();
60
- }
61
- // ── Base schema ──────────────────────────────────────────────────────────────
62
- /**
63
- * Create the baseline `workflow_runs` and `workflow_run_steps` tables if they
64
- * do not exist. These statements are idempotent: existing databases keep their
65
- * current schema, and migrations evolve them further.
66
- *
67
- * NOTE: the `scope_key` column on `workflow_runs` is intentionally NOT declared
68
- * here. It is added by migration `001-add-scope-key`. Fresh databases will run
69
- * the migration immediately on first open; pre-versioning databases that
70
- * already have the column are bootstrapped — see {@link runMigrations}.
71
- */
72
- function ensureBaseSchema(db) {
73
- db.exec(`
74
- CREATE TABLE IF NOT EXISTS workflow_runs (
75
- id TEXT PRIMARY KEY,
76
- workflow_ref TEXT NOT NULL,
77
- workflow_entry_id INTEGER,
78
- workflow_title TEXT NOT NULL,
79
- status TEXT NOT NULL CHECK (status IN ('active', 'completed', 'blocked', 'failed')),
80
- params_json TEXT NOT NULL DEFAULT '{}',
81
- current_step_id TEXT,
82
- created_at TEXT NOT NULL,
83
- updated_at TEXT NOT NULL,
84
- completed_at TEXT
85
- );
86
-
87
- CREATE INDEX IF NOT EXISTS idx_workflow_runs_ref ON workflow_runs(workflow_ref);
88
- CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
89
-
90
- CREATE TABLE IF NOT EXISTS workflow_run_steps (
91
- run_id TEXT NOT NULL,
92
- step_id TEXT NOT NULL,
93
- step_title TEXT NOT NULL,
94
- instructions TEXT NOT NULL,
95
- completion_json TEXT,
96
- sequence_index INTEGER NOT NULL,
97
- status TEXT NOT NULL CHECK (status IN ('pending', 'completed', 'blocked', 'failed', 'skipped')),
98
- notes TEXT,
99
- evidence_json TEXT,
100
- completed_at TEXT,
101
- PRIMARY KEY (run_id, step_id),
102
- FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
103
- );
104
-
105
- CREATE INDEX IF NOT EXISTS idx_workflow_run_steps_run_sequence
106
- ON workflow_run_steps(run_id, sequence_index);
107
- `);
108
- }
109
- // ── Migration engine ─────────────────────────────────────────────────────────
110
- //
111
- // The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
112
- // engine at src/storage/engines/sqlite-migrations.ts. This module owns its own
113
- // MIGRATIONS array plus the pre-versioning `bootstrap` hook, and delegates
114
- // application to that shared runner. The {@link Migration} interface is imported
115
- // from there.
116
- /**
117
- * All workflow.db migrations in application order. New migrations are
118
- * APPENDED — never inserted in the middle or reordered.
119
- */
120
- const MIGRATIONS = [
121
- // ── Migration 001 — add scope_key column ────────────────────────────────────
122
- //
123
- // Adds the `scope_key` column to `workflow_runs` so runs can be partitioned
124
- // per stash/scope. Pre-versioning databases that already have this column
125
- // are bootstrapped before this migration runs — see runMigrations().
126
- {
127
- id: "001-add-scope-key",
128
- up: `
129
- ALTER TABLE workflow_runs ADD COLUMN scope_key TEXT;
130
-
131
- CREATE INDEX IF NOT EXISTS idx_workflow_runs_scope_ref_status
132
- ON workflow_runs(scope_key, workflow_ref, status);
133
- `,
134
- },
135
- // ── Migration 002 — record agent harness + session identity ──────────────────
136
- //
137
- // Persists the agent harness identifier (e.g. "claude-code", "opencode") and
138
- // the platform-native session id that owns each workflow run. This is the
139
- // first concrete slice of #501 / #506: capturing *who* is driving a run so a
140
- // future (separately-approved) monitor can correlate workflow runs with
141
- // session activity. Both columns are nullable — runs started outside an agent
142
- // harness, and all pre-existing runs, simply have NULL identity.
143
- {
144
- id: "002-add-agent-identity",
145
- up: `
146
- ALTER TABLE workflow_runs ADD COLUMN agent_harness TEXT;
147
- ALTER TABLE workflow_runs ADD COLUMN agent_session_id TEXT;
148
-
149
- CREATE INDEX IF NOT EXISTS idx_workflow_runs_agent_session
150
- ON workflow_runs(agent_harness, agent_session_id);
151
- `,
152
- },
153
- // ── Migration 003 — check-in arming + per-step summary (#506) ────────────────
154
- //
155
- // Builds on the agent identity recorded by migration 002. Arms a file-signal
156
- // check-in (a timestamp, NOT a background thread — see
157
- // docs/technical/workflow-agent-checkin-adr.md) so a stalled run can be
158
- // re-targeted with a `continue` directive, and adds a per-step `summary`
159
- // column so step/workflow completion can capture and validate a required
160
- // summary of work done. Both columns are nullable.
161
- {
162
- id: "003-checkin-and-step-summary",
163
- up: `
164
- ALTER TABLE workflow_runs ADD COLUMN checkin_armed_at TEXT;
165
- ALTER TABLE workflow_run_steps ADD COLUMN summary TEXT;
166
- `,
167
- },
168
- // ── Migration 004 — per-unit run state (orchestration plan P1) ──────────────
169
- //
170
- // A step's execution may now fan out into N concurrent units (native
171
- // executor, docs/technical/akm-workflows-orchestration-plan.md). Units hang
172
- // off the gated step spine: `workflow_run_steps` stays the durable top-level
173
- // record; each dispatched unit gets its own row here so a crash-and-resume
174
- // re-dispatches only incomplete units (durable-row resume) and budget/usage
175
- // is attributable per unit. `input_hash` is reserved for the P5 deterministic
176
- // replay mode; `failure_reason` carries runAgent's structured failure
177
- // vocabulary so retry/continue-on-error policy has semantics to act on.
178
- {
179
- id: "004-workflow-run-units",
180
- up: `
181
- CREATE TABLE IF NOT EXISTS workflow_run_units (
182
- run_id TEXT NOT NULL,
183
- unit_id TEXT NOT NULL,
184
- step_id TEXT,
185
- node_id TEXT NOT NULL,
186
- parent_unit_id TEXT,
187
- phase TEXT,
188
- runner TEXT,
189
- model TEXT,
190
- status TEXT NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'skipped')),
191
- input_hash TEXT,
192
- result_json TEXT,
193
- tokens INTEGER,
194
- failure_reason TEXT,
195
- worktree_path TEXT,
196
- started_at TEXT,
197
- finished_at TEXT,
198
- PRIMARY KEY (run_id, unit_id),
199
- FOREIGN KEY (run_id) REFERENCES workflow_runs(id) ON DELETE CASCADE
200
- );
201
-
202
- CREATE INDEX IF NOT EXISTS idx_workflow_run_units_run_step
203
- ON workflow_run_units(run_id, step_id);
204
- `,
205
- },
206
- // ── Migration 005 — harness-native unit session id (plan P2) ────────────────
207
- //
208
- // The P2 harness adapters' result extractors reveal the harness-native
209
- // session id of a dispatched unit (codex `session_configured`, gemini/pi
210
- // JSON envelopes, the opencode SDK session). It is stored opportunistically
211
- // on the unit row so resume can replay the harness's own context cache
212
- // (e.g. `codex exec resume <id>`, `gemini --resume <id>`); akm never
213
- // *depends* on it — `workflow_run_units` remains the durable source of
214
- // truth (plan §"Session, MCP, and identity across harnesses").
215
- {
216
- id: "005-unit-session-id",
217
- up: `
218
- ALTER TABLE workflow_run_units ADD COLUMN session_id TEXT;
219
- `,
220
- },
221
- // ── Migration 006 — frozen plan + engine lease (redesign addendum, R1) ──────
222
- //
223
- // `workflow start` now compiles the workflow into its plan graph ONCE and
224
- // freezes it on the run row: `plan_json` holds the canonical plan JSON
225
- // (`ir/plan-hash.ts`) and `plan_hash` its sha256, so every subsequent
226
- // invocation executes the frozen snapshot with an integrity check — the
227
- // source file is never re-read for an in-flight run. Runs created before
228
- // this migration have NULL plan_json (legacy) and fall back to
229
- // compile-from-asset with a warning.
230
- //
231
- // `engine_lease_until` / `engine_lease_holder` reserve the run-lease columns
232
- // (a second `workflow run` on a leased run refuses up front). TODO(R2):
233
- // lease ENFORCEMENT is engine-rework scope — only the columns land now.
234
- {
235
- id: "006-frozen-plan-and-lease",
236
- up: `
237
- ALTER TABLE workflow_runs ADD COLUMN plan_json TEXT;
238
- ALTER TABLE workflow_runs ADD COLUMN plan_hash TEXT;
239
- ALTER TABLE workflow_runs ADD COLUMN engine_lease_until TEXT;
240
- ALTER TABLE workflow_runs ADD COLUMN engine_lease_holder TEXT;
241
- `,
242
- },
243
- // ── Migration 007 — unit-level check-in heartbeat (redesign addendum, R3) ────
244
- //
245
- // The harness-neutral driver protocol lets ANY agent session claim and
246
- // heartbeat a unit it is executing via `akm workflow report --status running`.
247
- // `last_checkin_at` records the most recent heartbeat (distinct from
248
- // `started_at`, the first claim) so a pure timestamp evaluator
249
- // (`runtime/unit-checkin.ts`) can surface a claimed-but-silent unit as stale
250
- // in `workflow brief` without any background thread. Nullable and additive;
251
- // engine-dispatched rows never set it (they finish before a heartbeat window
252
- // could elapse), so their transient `running` state is judged from
253
- // `started_at`.
254
- {
255
- id: "007-unit-last-checkin",
256
- up: `
257
- ALTER TABLE workflow_run_units ADD COLUMN last_checkin_at TEXT;
258
- `,
259
- },
260
- // ── Migration 008 — per-unit dispatch-attempt counter (PR #714 review, P2) ───
261
- //
262
- // `workflow_run_units.unit_id` is CONTENT-derived and stable across
263
- // crash/resume (retries/loops carry `~r<n>`/`~l<loop>` suffixes, so they are
264
- // DISTINCT rows). A crash between a unit's dispatch (`insertUnit`, status
265
- // `running`) and its finish leaves a stale `running` row; durable-row resume
266
- // re-dispatches the SAME unit_id and `insertUnit` REPLACES that single row.
267
- // Because the run's budget/lifetime seed was derived from the NUMBER of unit
268
- // rows, each crash/resume of one unit erased the prior dispatch from
269
- // `budget.max_units` / lifetime-cap accounting, letting a run spend past its
270
- // declared ceiling. `attempts` counts how many times a row was (re)dispatched
271
- // — incremented by `insertUnit` on every REPLACE of an existing row — so both
272
- // budget seeds sum `attempts` instead of counting rows and crash-retried
273
- // dispatches are charged. Existing rows back-fill to 1 (one dispatch each).
274
- {
275
- id: "008-unit-attempts",
276
- up: `
277
- ALTER TABLE workflow_run_units ADD COLUMN attempts INTEGER NOT NULL DEFAULT 1;
278
- `,
279
- },
280
- // ── Migration 009 — per-unit claim ownership (PR #714 review round 2) ─────────
281
- //
282
- // `akm workflow report --status running` claims a unit before executing it.
283
- // Round-2 review (#3): a running row had no claim owner, no compare-and-set,
284
- // and no stale-hash guard, so a stale/tampered `running` row could be
285
- // finalized by anyone with a fresh result while keeping an old input_hash.
286
- // These columns record who holds the claim (`claim_holder` — the driver's
287
- // `--session-id` or a token report mints and returns) and until when
288
- // (`claim_expires_at`, ISO-8601 UTC). Heartbeating or finishing a live-claimed
289
- // running row requires the matching holder; an EXPIRED claim is reclaimable by
290
- // a new holder (crash recovery). The TTL equals the unit-checkin stale window
291
- // (`runtime/unit-checkin.UNIT_STALE_MS`), so an expired claim is exactly a unit
292
- // that `workflow brief` already surfaces as stale. Both columns are nullable
293
- // and additive: engine-dispatched rows and simple claimless drivers leave them
294
- // NULL, and finishing a never-claimed unit stays allowed (input_hash is still
295
- // validated always).
296
- {
297
- id: "009-unit-claim",
298
- up: `
299
- ALTER TABLE workflow_run_units ADD COLUMN claim_holder TEXT;
300
- ALTER TABLE workflow_run_units ADD COLUMN claim_expires_at TEXT;
301
- `,
302
- },
303
- ];
304
- /**
305
- * Stable id of the scope_key migration. Exported for bootstrap detection and
306
- * tests.
307
- */
308
- const SCOPE_KEY_MIGRATION_ID = "001-add-scope-key";
309
- /**
310
- * Detect whether a column exists on a given table.
311
- */
312
- function hasColumn(db, table, column) {
313
- const rows = db.prepare(`PRAGMA table_info(${table})`).all();
314
- return rows.some((r) => r.name === column);
315
- }
316
- /**
317
- * Back-fill `schema_migrations` rows for any schema state that existed before
318
- * this file gained migration tracking.
319
- *
320
- * The pre-versioning code added the `scope_key` column on `workflow_runs` via
321
- * an ad-hoc PRAGMA / ALTER TABLE pair. Those databases must not re-run the
322
- * scope_key migration (the ALTER would fail with "duplicate column name"
323
- * since the migration body does not use IF NOT EXISTS — SQLite does not
324
- * support that clause on ALTER TABLE ADD COLUMN). Instead, we mark the
325
- * migration as already applied.
326
- *
327
- * This function is a no-op on fresh databases: the `scope_key` column does
328
- * not exist, so the migration runs normally and records itself.
329
- */
330
- function bootstrapPreVersioningDb(db) {
331
- const alreadyRecorded = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(SCOPE_KEY_MIGRATION_ID);
332
- if (alreadyRecorded)
333
- return;
334
- if (hasColumn(db, "workflow_runs", "scope_key")) {
335
- db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(SCOPE_KEY_MIGRATION_ID);
336
- }
337
- }
338
- /**
339
- * Apply every pending migration in a single transaction per migration.
340
- *
341
- * Delegates to the shared SQLite migration engine, passing the
342
- * `bootstrapPreVersioningDb` hook so databases created before this file gained
343
- * migration tracking back-fill their scope_key row instead of re-running the
344
- * ALTER.
345
- *
346
- * Called automatically by {@link openWorkflowDatabase}.
347
- */
348
- export function runMigrations(db) {
349
- runSqliteMigrations(db, MIGRATIONS, { bootstrap: bootstrapPreVersioningDb });
350
- }
@@ -1,116 +0,0 @@
1
- // This Source Code Form is subject to the terms of the Mozilla Public
2
- // License, v. 2.0. If a copy of the MPL was not distributed with this
3
- // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
- /**
5
- * `akm workflow watch <run>` — run-scoped event tail (redesign addendum R2).
6
- *
7
- * Prints the run's `workflow_*` / `workflow_unit_*` events from the state.db
8
- * `events` table (matched on `metadata.runId`) as NDJSON — one
9
- * {@link EventEnvelope} per line — and exits. With `stream: true` it keeps
10
- * polling from the last seen event id (monotonic rowid cursor, so concurrent
11
- * writers can never cause skips) and exits when the run reaches a terminal
12
- * status.
13
- *
14
- * Design constraints (pinned R2 decisions):
15
- * - FOREGROUND poll loop only — no daemon, no background process, no
16
- * `tailEvents` subscription held past the terminal status.
17
- * - Reads go through the existing events repository (via
18
- * {@link readEvents}); this module issues no SQL of its own.
19
- * - "Terminal" means any non-`active` run status (`completed`, `failed`,
20
- * `blocked`): in all three the engine has stopped driving, so no further
21
- * events arrive until a human resumes the run. The status is read BEFORE
22
- * each drain, so events written before the status flip are always
23
- * emitted before the loop exits. The engine commits the status flip
24
- * (workflow.db transaction) BEFORE it appends the terminal
25
- * `workflow_step_completed` / `workflow_finished` events to state.db, so
26
- * after first observing a terminal status the loop keeps performing
27
- * grace polls (sleep + drain) until one drains nothing new — the
28
- * terminal events landing in that commit→append window are never
29
- * dropped.
30
- * - Event lines are the raw envelopes (ids/status metadata only — event
31
- * emitters never journal workflow-authored content, 07 P1-B rule).
32
- */
33
- import { NotFoundError } from "../../core/errors.js";
34
- import { readEvents } from "../../core/events.js";
35
- import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
36
- /** Default `--stream` poll interval (ms). */
37
- export const DEFAULT_WATCH_INTERVAL_MS = 1000;
38
- /**
39
- * True when `event` belongs to workflow run `runId`: the event type is in the
40
- * `workflow_*` family (which includes `workflow_unit_*`) AND the metadata
41
- * carries a matching `runId`. Events of other families that happen to carry
42
- * a `runId` (e.g. `llm_usage`) are excluded by design.
43
- */
44
- export function isWorkflowRunEvent(event, runId) {
45
- if (!event.eventType.startsWith("workflow_"))
46
- return false;
47
- return event.metadata?.runId === runId;
48
- }
49
- /** Default status reader — repository lookup; a missing run is a structured not-found. */
50
- async function readRunStatus(runId) {
51
- return withWorkflowRunsRepo((repo) => {
52
- const row = repo.getRunById(runId);
53
- if (!row) {
54
- throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
55
- }
56
- return row.status;
57
- });
58
- }
59
- /**
60
- * Watch one workflow run's events. Emits each matching event envelope as a
61
- * single NDJSON line via `emit`, then returns a summary. See the module doc
62
- * for the backlog/stream/terminal-status contract.
63
- */
64
- export async function watchWorkflowRun(options) {
65
- const intervalMs = options.intervalMs ?? DEFAULT_WATCH_INTERVAL_MS;
66
- const emit = options.emit ?? ((line) => process.stdout.write(`${line}\n`));
67
- const read = options.readEventsFn ?? ((readOptions) => readEvents(readOptions));
68
- const getRunStatus = options.getRunStatus ?? readRunStatus;
69
- const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
70
- // Existence check first so an unknown run id is a structured error, not an
71
- // empty NDJSON stream.
72
- let status = await getRunStatus(options.runId);
73
- let eventCount = 0;
74
- let cursor = 0;
75
- const drain = () => {
76
- const { events, nextOffset } = read({ sinceOffset: cursor });
77
- cursor = nextOffset;
78
- for (const event of events) {
79
- if (!isWorkflowRunEvent(event, options.runId))
80
- continue;
81
- emit(JSON.stringify(event));
82
- eventCount++;
83
- }
84
- };
85
- // Backlog: everything already journaled for this run.
86
- drain();
87
- if (options.stream === true) {
88
- // Foreground poll loop (NO daemon). Status is re-read BEFORE each drain
89
- // so events written before a terminal flip are emitted before exit.
90
- while (status === "active") {
91
- await sleep(intervalMs);
92
- status = await getRunStatus(options.runId);
93
- drain();
94
- }
95
- // Terminal grace polls: completeWorkflowStep commits the run-status flip
96
- // (workflow.db) BEFORE appending workflow_step_completed /
97
- // workflow_finished to state.db, so the drain that first observed the
98
- // terminal status can predate those events. Keep sleeping + draining
99
- // until an idle poll (a drain that emits nothing new for this run) —
100
- // the engine has stopped driving, so this converges after the terminal
101
- // events land (already-terminal runs pay exactly one idle poll).
102
- let emittedBefore;
103
- do {
104
- emittedBefore = eventCount;
105
- await sleep(intervalMs);
106
- drain();
107
- } while (eventCount > emittedBefore);
108
- }
109
- return {
110
- runId: options.runId,
111
- status,
112
- eventCount,
113
- lastEventId: cursor,
114
- streamed: options.stream === true,
115
- };
116
- }