forjajs 5.0.1 → 5.3.0

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 (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -30,6 +30,9 @@ export declare class ForjaNestController {
30
30
  graphImpact(request: Request, response: Response): Promise<unknown>;
31
31
  taskNext(request: Request, response: Response): Promise<unknown>;
32
32
  handoff(request: Request, response: Response): Promise<unknown>;
33
+ planPropose(request: Request, response: Response): Promise<unknown>;
34
+ planGet(request: Request, response: Response): Promise<unknown>;
35
+ planReview(request: Request, response: Response): Promise<unknown>;
33
36
  runtimeStart(request: Request, response: Response): Promise<unknown>;
34
37
  runtimeGet(request: Request, response: Response): Promise<unknown>;
35
38
  runtimeExecute(request: Request, response: Response): Promise<unknown>;
@@ -42,6 +45,9 @@ export declare class ForjaNestController {
42
45
  taskCreate(request: Request, response: Response): Promise<unknown>;
43
46
  taskStart(request: Request, response: Response): Promise<unknown>;
44
47
  taskBlock(request: Request, response: Response): Promise<unknown>;
48
+ approvalList(request: Request, response: Response): Promise<unknown>;
49
+ metrics(request: Request, response: Response): Promise<unknown>;
50
+ observations(request: Request, response: Response): Promise<unknown>;
45
51
  approvalGet(request: Request, response: Response): Promise<unknown>;
46
52
  approvalDecide(request: Request, response: Response): Promise<unknown>;
47
53
  tools(request: Request, response: Response): Promise<unknown>;
@@ -56,6 +56,9 @@ let ForjaNestController = class ForjaNestController {
56
56
  graphImpact(request, response) { return this.route(request, response, 'GET', '/api/graph/impact'); }
57
57
  taskNext(request, response) { return this.route(request, response, 'GET', '/api/tasks/next'); }
58
58
  handoff(request, response) { return this.route(request, response, 'POST', '/api/handoffs', request.body); }
59
+ planPropose(request, response) { return this.route(request, response, 'POST', '/api/plans', request.body); }
60
+ planGet(request, response) { return this.route(request, response, 'GET', `/api/plans/${request.params.id}`); }
61
+ planReview(request, response) { return this.route(request, response, 'POST', `/api/plans/${request.params.id}/review`, request.body); }
59
62
  runtimeStart(request, response) { return this.route(request, response, 'POST', '/api/executions', request.body); }
60
63
  runtimeGet(request, response) { return this.route(request, response, 'GET', `/api/executions/${request.params.id}`); }
61
64
  runtimeExecute(request, response) { return this.route(request, response, 'POST', `/api/executions/${request.params.id}/execute`); }
@@ -68,6 +71,9 @@ let ForjaNestController = class ForjaNestController {
68
71
  taskCreate(request, response) { return this.route(request, response, 'POST', '/api/tasks', request.body); }
69
72
  taskStart(request, response) { return this.route(request, response, 'POST', `/api/tasks/${request.params.id}/start`); }
70
73
  taskBlock(request, response) { return this.route(request, response, 'POST', `/api/tasks/${request.params.id}/block`); }
74
+ approvalList(request, response) { return this.route(request, response, 'GET', '/api/approvals'); }
75
+ metrics(request, response) { return this.route(request, response, 'GET', '/api/control-plane/metrics'); }
76
+ observations(request, response) { return this.route(request, response, 'GET', '/api/observability/observations'); }
71
77
  approvalGet(request, response) { return this.route(request, response, 'GET', `/api/approvals/${request.params.id}`); }
72
78
  approvalDecide(request, response) { return this.route(request, response, 'POST', `/api/approvals/${request.params.id}/decide`, request.body); }
73
79
  tools(request, response) { return this.route(request, response, 'GET', '/mcp/tools'); }
@@ -157,6 +163,30 @@ __decorate([
157
163
  __metadata("design:paramtypes", [Object, Object]),
158
164
  __metadata("design:returntype", Promise)
159
165
  ], ForjaNestController.prototype, "handoff", null);
166
+ __decorate([
167
+ Post('api/plans'),
168
+ __param(0, Req()),
169
+ __param(1, Res({ passthrough: true })),
170
+ __metadata("design:type", Function),
171
+ __metadata("design:paramtypes", [Object, Object]),
172
+ __metadata("design:returntype", Promise)
173
+ ], ForjaNestController.prototype, "planPropose", null);
174
+ __decorate([
175
+ Get('api/plans/:id'),
176
+ __param(0, Req()),
177
+ __param(1, Res({ passthrough: true })),
178
+ __metadata("design:type", Function),
179
+ __metadata("design:paramtypes", [Object, Object]),
180
+ __metadata("design:returntype", Promise)
181
+ ], ForjaNestController.prototype, "planGet", null);
182
+ __decorate([
183
+ Post('api/plans/:id/review'),
184
+ __param(0, Req()),
185
+ __param(1, Res({ passthrough: true })),
186
+ __metadata("design:type", Function),
187
+ __metadata("design:paramtypes", [Object, Object]),
188
+ __metadata("design:returntype", Promise)
189
+ ], ForjaNestController.prototype, "planReview", null);
160
190
  __decorate([
161
191
  Post('api/executions'),
162
192
  __param(0, Req()),
@@ -253,6 +283,30 @@ __decorate([
253
283
  __metadata("design:paramtypes", [Object, Object]),
254
284
  __metadata("design:returntype", Promise)
255
285
  ], ForjaNestController.prototype, "taskBlock", null);
286
+ __decorate([
287
+ Get('api/approvals'),
288
+ __param(0, Req()),
289
+ __param(1, Res({ passthrough: true })),
290
+ __metadata("design:type", Function),
291
+ __metadata("design:paramtypes", [Object, Object]),
292
+ __metadata("design:returntype", Promise)
293
+ ], ForjaNestController.prototype, "approvalList", null);
294
+ __decorate([
295
+ Get('api/control-plane/metrics'),
296
+ __param(0, Req()),
297
+ __param(1, Res({ passthrough: true })),
298
+ __metadata("design:type", Function),
299
+ __metadata("design:paramtypes", [Object, Object]),
300
+ __metadata("design:returntype", Promise)
301
+ ], ForjaNestController.prototype, "metrics", null);
302
+ __decorate([
303
+ Get('api/observability/observations'),
304
+ __param(0, Req()),
305
+ __param(1, Res({ passthrough: true })),
306
+ __metadata("design:type", Function),
307
+ __metadata("design:paramtypes", [Object, Object]),
308
+ __metadata("design:returntype", Promise)
309
+ ], ForjaNestController.prototype, "observations", null);
256
310
  __decorate([
257
311
  Get('api/approvals/:id'),
258
312
  __param(0, Req()),
@@ -294,6 +348,7 @@ __decorate([
294
348
  ForjaNestController = __decorate([
295
349
  Controller(),
296
350
  UseGuards(ForjaLocalAuthGuard),
351
+ __param(0, Inject(ForjaNestAdapter)),
297
352
  __metadata("design:paramtypes", [ForjaNestAdapter])
298
353
  ], ForjaNestController);
299
354
  export { ForjaNestController };
@@ -4,15 +4,32 @@ import { PolicyEngine } from '../../../packages/policy/src/index.ts';
4
4
  import { McpServer } from '../../../packages/mcp/src/index.ts';
5
5
  import { ControlPlane, type ObservationStore } from '../../../packages/observability/src/index.ts';
6
6
  import { ApprovalLedger } from '../../../packages/policy/src/index.ts';
7
- import { type OrchestrationStore } from '../../../packages/orchestration/src/index.ts';
7
+ import { HandoffEngine, TaskEngine, type OrchestrationStore } from '../../../packages/orchestration/src/index.ts';
8
8
  import { InMemoryEventStream, type LocalAuthenticator } from '../../../packages/adapter-nest/src/index.ts';
9
+ import { type TaskRuntimeValidator } from './task-runtime-coordinator.ts';
10
+ import { type PlanningStore } from '../../../packages/planner/src/proposal-store.ts';
11
+ import type { ContextSource } from '../../../packages/context/src/index.ts';
9
12
  import { GraphLoop } from '../../../packages/graph/src/index.ts';
10
13
  import { ContextEngine } from '../../../packages/context/src/index.ts';
11
14
  import { EventBus } from '../../../packages/events/src/index.ts';
12
15
  import type { RuntimePersistence } from '../../../packages/runtime/src/index.ts';
16
+ import type { AgentIdentity } from '../../../packages/contracts/src/index.ts';
17
+ export interface ServerPlanningOptions {
18
+ readonly executor?: AgentIdentity;
19
+ readonly reviewer?: AgentIdentity;
20
+ readonly memory?: ContextSource;
21
+ readonly store?: PlanningStore;
22
+ }
13
23
  export declare function createDefaultCapabilityRegistry(root?: string, cwd?: string): CapabilityRegistry;
14
- export declare function createDefaultMcp(registry?: CapabilityRegistry, policy?: PolicyEngine, graph?: GraphLoop, audit?: import('../../../packages/mcp/src/index.ts').McpAuditSink, context?: ContextEngine): McpServer;
15
- export declare function createDefaultPolicy(): PolicyEngine;
24
+ export declare function createDefaultMcp(registry?: CapabilityRegistry, policy?: PolicyEngine, graph?: GraphLoop, audit?: import('../../../packages/mcp/src/index.ts').McpAuditSink, context?: ContextEngine, orchestration?: {
25
+ readonly taskEngine: TaskEngine;
26
+ readonly handoffEngine: HandoffEngine;
27
+ }, planning?: import('../../../packages/mcp/src/index.ts').McpPlanning): McpServer;
28
+ export declare function createDefaultPolicy(approvals?: ApprovalLedger): PolicyEngine;
16
29
  export declare function createLocalAuthenticator(token?: string | undefined): LocalAuthenticator | undefined;
17
- export declare function createDefaultControlPlane(eventStream: InMemoryEventStream, registry?: CapabilityRegistry, policy?: PolicyEngine, persistence?: RuntimePersistence, approvals?: ApprovalLedger, events?: EventBus, graph?: GraphLoop, context?: ContextEngine, orchestrationStore?: OrchestrationStore, observationStore?: ObservationStore): ControlPlane;
30
+ export declare function createDefaultControlPlane(eventStream: InMemoryEventStream, registry?: CapabilityRegistry, policy?: PolicyEngine, persistence?: RuntimePersistence, approvals?: ApprovalLedger, events?: EventBus, graph?: GraphLoop, context?: ContextEngine, orchestrationStore?: OrchestrationStore, observationStore?: ObservationStore, validator?: TaskRuntimeValidator): Promise<ControlPlane>;
31
+ export declare function createDefaultServerServices(eventStream: InMemoryEventStream, registry?: CapabilityRegistry, policy?: PolicyEngine, persistence?: RuntimePersistence, approvals?: ApprovalLedger, events?: EventBus, graph?: GraphLoop, context?: ContextEngine, orchestrationStore?: OrchestrationStore, observationStore?: ObservationStore, validator?: TaskRuntimeValidator, mcpAudit?: import('../../../packages/mcp/src/index.ts').McpAuditSink, planningOptions?: ServerPlanningOptions): Promise<{
32
+ readonly controlPlane: ControlPlane;
33
+ readonly mcp: McpServer;
34
+ }>;
18
35
  export declare function bootstrap(port?: number): Promise<import("@nestjs/common").INestApplication<any>>;
@@ -12,9 +12,13 @@ import { ControlPlane, InMemoryObservationStore, ObservabilityRecorder } from '.
12
12
  import { ApprovalLedger } from '../../../packages/policy/src/index.js';
13
13
  import { HandoffEngine, InMemoryOrchestrationStore, SprintEngine, TaskEngine } from '../../../packages/orchestration/src/index.js';
14
14
  import { validateTokenBudget } from '../../../packages/contracts/src/index.js';
15
- import { createBearerAuthenticator, InMemoryEventStream } from '../../../packages/adapter-nest/src/index.js';
15
+ import { createBearerAuthenticator, InMemoryEventStream, planningOpenApiPaths } from '../../../packages/adapter-nest/src/index.js';
16
16
  import { AppModule } from './app.module.js';
17
17
  import { RuntimeEngine } from '../../../packages/runtime/src/index.js';
18
+ import { TaskRuntimeCoordinator } from './task-runtime-coordinator.js';
19
+ import { TaskPlanningService } from './task-planning-service.js';
20
+ import { InMemoryPlanningStore, PlanningError } from '../../../packages/planner/src/proposal-store.js';
21
+ import { SqlitePlanningStore } from '../../../packages/adapter-sqlite/src/index.js';
18
22
  import { GraphExecutionMemory, GraphLoop } from '../../../packages/graph/src/index.js';
19
23
  import { ContextEngine, GraphContextSource } from '../../../packages/context/src/index.js';
20
24
  import { SqliteContextCache, SqliteGraphStore, SqliteMigrationRunner, SqliteRuntimePersistence } from '../../../packages/adapter-sqlite/src/index.js';
@@ -31,12 +35,18 @@ export function createDefaultCapabilityRegistry(root = serverRoot, cwd = process
31
35
  registerCliCapabilities(registry, createLegacyCliRunner(root, cwd));
32
36
  return registry;
33
37
  }
34
- export function createDefaultMcp(registry = createDefaultCapabilityRegistry(), policy = createDefaultPolicy(), graph = new GraphLoop(), audit, context) {
35
- return new McpServer({ registry, policy, graph, audit, context, agent: { id: 'local-server', name: 'Forja local server', role: 'server', autonomy: 'supervised', permissions: ['read', 'write', 'execution', 'database'], capabilities: registry.list().map((definition) => definition.id) } });
38
+ export function createDefaultMcp(registry = createDefaultCapabilityRegistry(), policy = createDefaultPolicy(), graph = new GraphLoop(), audit, context, orchestration, planning) {
39
+ const store = new InMemoryOrchestrationStore();
40
+ const services = orchestration ?? { taskEngine: new TaskEngine(store, new SprintEngine(store)), handoffEngine: new HandoffEngine(store) };
41
+ const agent = { id: 'local-server', name: 'Forja local server', role: 'server', autonomy: 'supervised', permissions: ['read', 'write', 'execution', 'database'], capabilities: registry.list().map((definition) => definition.id) };
42
+ return new McpServer({ registry, policy, graph, audit, context, planning, ...services, agent, mcpPolicy: { authorize: ({ action, category, risk, files }) => {
43
+ const now = new Date().toISOString();
44
+ return policy.authorize({ agent, environment: 'local', categories: [category], files, now, definition: { schemaVersion: '2.0', createdAt: now, updatedAt: now, correlationId: action, id: action, version: '1.0.0', description: action, permissions: [category], risk, sideEffects: category === 'read' ? [] : [category], requirements: [], supportsAutonomy: false, idempotent: category === 'read', timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] } });
45
+ } } });
36
46
  }
37
- export function createDefaultPolicy() {
47
+ export function createDefaultPolicy(approvals = new ApprovalLedger()) {
38
48
  const readOnlyRule = { id: 'local-read-only', priority: 10, effect: 'ALLOW', reason: 'Default local server permits read capabilities only', scope: { categories: ['read'], environments: ['local'] } };
39
- return new PolicyEngine({ rules: [readOnlyRule] });
49
+ return new PolicyEngine({ rules: [readOnlyRule], approvalLedger: approvals });
40
50
  }
41
51
  export function createLocalAuthenticator(token = process.env.FORJA_AUTH_TOKEN) {
42
52
  if (token === undefined || token.length === 0)
@@ -44,59 +54,40 @@ export function createLocalAuthenticator(token = process.env.FORJA_AUTH_TOKEN) {
44
54
  return createBearerAuthenticator(token);
45
55
  }
46
56
  class DefaultRuntimeApplication {
47
- contexts = new Map();
48
- runtime;
49
- policy;
50
- constructor(registry, policy, persistence, graph, context) {
51
- this.policy = policy;
52
- this.runtime = new RuntimeEngine({
57
+ context;
58
+ coordinator;
59
+ constructor(registry, policy, store, tasks, persistence, graph, context, validator) {
60
+ this.context = context;
61
+ const runtime = new RuntimeEngine({
53
62
  registry,
54
63
  planner: { plan: (_objective, context) => { if (!isRecord(context) || !Array.isArray(context.steps))
55
64
  throw new Error('Runtime plan context is missing'); return context.steps; } },
56
- contextBuilder: { build: async (objective) => { const request = this.contexts.get(objective); if (request === undefined)
57
- return undefined; const contextPackage = context === undefined ? undefined : await context.build({ objective, budget: request.budget, requireEvidence: false }); return { ...request, contextPackage }; } },
58
- validator: { validate: (run, results) => this.validate(run, results) },
65
+ validator: { validate: async (run, results) => {
66
+ const linked = await this.coordinator.validationContext(run);
67
+ return validator === undefined ? this.validate(run) : validator.validate(run, results, linked);
68
+ } },
59
69
  persistence,
70
+ beforeExecution: (run) => this.coordinator.executionStarted(run),
60
71
  memory: graph === undefined ? undefined : new GraphExecutionMemory(graph),
61
72
  });
73
+ this.coordinator = new TaskRuntimeCoordinator(runtime, policy, store, tasks, persistence);
62
74
  }
75
+ initialize() { return this.coordinator.initialize(); }
63
76
  async start(input) {
64
77
  const value = runtimeInput(input);
65
- this.contexts.set(value.objective, { steps: value.steps, budget: value.budget });
66
- try {
67
- return await this.runtime.start({ objective: value.objective, agent: value.agent, budget: value.budget, policy: this.policy, sprintId: value.sprintId, taskId: value.taskId, correlationId: value.correlationId });
68
- }
69
- finally {
70
- this.contexts.delete(value.objective);
71
- }
78
+ const contextPackage = await this.context?.build({ objective: value.objective, budget: value.budget, requireEvidence: false });
79
+ return this.coordinator.start(value, { steps: value.steps, budget: value.budget, contextPackage });
72
80
  }
73
- async execute(id) { return this.executeWithRecovery(id); }
74
- async get(id) { return this.getWithRecovery(id); }
75
- pause(id) { return this.runtime.pause(id); }
76
- resume(id) { return this.runtime.resume(id, this.policy); }
77
- cancel(id) { return this.runtime.cancel(id); }
78
- async getWithRecovery(id) {
79
- try {
80
- return this.runtime.get(id);
81
- }
82
- catch {
83
- await this.runtime.recover(id, this.policy);
84
- return this.runtime.get(id);
85
- }
86
- }
87
- async executeWithRecovery(id) {
88
- try {
89
- return await this.runtime.execute(id);
90
- }
91
- catch {
92
- await this.runtime.recover(id, this.policy);
93
- return this.runtime.execute(id);
94
- }
95
- }
96
- validate(run, results) {
97
- const passed = results.length === run.steps && results.every((result) => result.status === 'succeeded' && result.evidence.length > 0);
81
+ execute(id) { return this.coordinator.execute(this.runId(id)); }
82
+ get(id) { return this.coordinator.get(this.runId(id)); }
83
+ pause(id) { return this.coordinator.pause(this.runId(id)); }
84
+ resume(id) { return this.coordinator.resume(this.runId(id)); }
85
+ cancel(id) { return this.coordinator.cancel(this.runId(id)); }
86
+ runId(value) { if (typeof value !== 'string' || value.trim().length === 0)
87
+ throw new Error('Execution id is required'); return value; }
88
+ validate(run) {
98
89
  const now = new Date().toISOString();
99
- return { schemaVersion: '2.0', createdAt: now, updatedAt: now, correlationId: run.correlationId, status: passed ? 'accepted' : 'rejected', checks: [{ name: 'capabilities-succeeded-with-evidence', passed, evidenceIds: results.flatMap((result) => result.evidence.map((item) => item.id)) }], summary: passed ? 'All runtime steps succeeded with evidence' : 'Runtime step failed or lacked evidence' };
90
+ return { schemaVersion: '2.0', createdAt: now, updatedAt: now, correlationId: run.correlationId, status: 'inconclusive', checks: [], summary: 'Independent validation checks are not configured' };
100
91
  }
101
92
  }
102
93
  function runtimeInput(input) {
@@ -107,20 +98,39 @@ function runtimeInput(input) {
107
98
  if (input.objective.trim().length === 0 || typeof agent.id !== 'string' || typeof agent.name !== 'string' || typeof agent.role !== 'string')
108
99
  throw new Error('Runtime agent and objective are invalid');
109
100
  validateTokenBudget(budget);
110
- const steps = input.steps.map((step) => { if (!isRecord(step) || typeof step.capabilityId !== 'string' || typeof step.estimatedTokens !== 'number')
111
- throw new Error('Runtime step requires capabilityId and estimatedTokens'); return step; });
101
+ const steps = input.steps.map((step) => {
102
+ if (!isRecord(step) || typeof step.capabilityId !== 'string' || step.capabilityId.trim().length === 0 || typeof step.estimatedTokens !== 'number' || !Number.isSafeInteger(step.estimatedTokens) || step.estimatedTokens < 0)
103
+ throw new Error('Runtime step requires capabilityId and nonnegative integer estimatedTokens');
104
+ for (const field of ['files', 'categories'])
105
+ if (step[field] !== undefined && (!Array.isArray(step[field]) || !step[field].every((item) => typeof item === 'string')))
106
+ throw new Error(`Runtime ${field} must be a string array`);
107
+ return step;
108
+ });
112
109
  if (steps.length === 0)
113
110
  throw new Error('Runtime requires at least one capability step');
114
- return { objective: input.objective, agent, budget, steps, sprintId: typeof input.sprintId === 'string' ? input.sprintId : undefined, taskId: typeof input.taskId === 'string' ? input.taskId : undefined, correlationId: typeof input.correlationId === 'string' ? input.correlationId : undefined };
111
+ for (const field of ['taskId', 'sprintId', 'handoffId', 'correlationId'])
112
+ if (input[field] !== undefined && (typeof input[field] !== 'string' || input[field].trim().length === 0))
113
+ throw new Error(`Runtime ${field} must be a nonempty string`);
114
+ return { objective: input.objective, agent, budget, steps, sprintId: input.sprintId, taskId: input.taskId, handoffId: input.handoffId, correlationId: input.correlationId };
115
115
  }
116
116
  function isRecord(value) { return typeof value === 'object' && value !== null; }
117
- export function createDefaultControlPlane(eventStream, registry = createDefaultCapabilityRegistry(), policy = createDefaultPolicy(), persistence, approvals = new ApprovalLedger(), events, graph, context, orchestrationStore = new InMemoryOrchestrationStore(), observationStore = new InMemoryObservationStore()) {
117
+ export async function createDefaultControlPlane(eventStream, registry = createDefaultCapabilityRegistry(), policy = createDefaultPolicy(), persistence, approvals = policy.approvals, events, graph, context, orchestrationStore = new InMemoryOrchestrationStore(), observationStore = new InMemoryObservationStore(), validator) {
118
+ return (await createDefaultServerServices(eventStream, registry, policy, persistence, approvals, events, graph, context, orchestrationStore, observationStore, validator)).controlPlane;
119
+ }
120
+ export async function createDefaultServerServices(eventStream, registry = createDefaultCapabilityRegistry(), policy = createDefaultPolicy(), persistence, approvals = policy.approvals, events, graph, context, orchestrationStore = new InMemoryOrchestrationStore(), observationStore = new InMemoryObservationStore(), validator, mcpAudit, planningOptions = {}) {
118
121
  const store = orchestrationStore;
119
122
  const sprintEngine = new SprintEngine(store);
120
123
  const taskEngine = new TaskEngine(store, sprintEngine);
121
124
  const handoffEngine = new HandoffEngine(store);
122
- const runtime = new DefaultRuntimeApplication(registry, policy, persistence, graph, context);
123
- return new ControlPlane(new ObservabilityRecorder(observationStore), {
125
+ const sharedGraph = graph ?? new GraphLoop();
126
+ const sharedContext = context ?? new ContextEngine({ graph: new GraphContextSource({ searchContext: (objective) => sharedGraph.contextRecords(objective) }), memory: planningOptions.memory });
127
+ const planningContext = context !== undefined && planningOptions.memory !== undefined ? new ContextEngine({ graph: new GraphContextSource({ searchContext: (objective) => sharedGraph.contextRecords(objective) }), memory: planningOptions.memory }) : sharedContext;
128
+ const planningStore = planningOptions.store ?? new InMemoryPlanningStore({ getTask: (id) => synchronousSnapshot(store.getTask(id)), getSprint: (id) => synchronousSnapshot(store.getSprint(id)), getHandoff: (id) => synchronousSnapshot(store.getHandoff(id)) });
129
+ const planning = new TaskPlanningService({ orchestration: store, tasks: taskEngine, context: planningContext, proposals: planningStore, policy, executor: planningOptions.executor ?? { id: 'local-server', name: 'Forja local server', role: 'server', autonomy: 'supervised' }, reviewer: planningOptions.reviewer });
130
+ const runtime = new DefaultRuntimeApplication(registry, policy, store, taskEngine, persistence, sharedGraph, context, validator);
131
+ await runtime.initialize();
132
+ const controlPlane = new ControlPlane(new ObservabilityRecorder(observationStore), {
133
+ planning: { propose: (input) => planning.propose(input), get: (id) => planning.get(id), review: (id, input) => planning.review(id, input) },
124
134
  runtime: { start: (input) => runtime.start(input), get: (input) => runtime.get(input), execute: (input) => runtime.execute(input), pause: (input) => runtime.pause(input), resume: (input) => runtime.resume(input), cancel: (input) => runtime.cancel(input) },
125
135
  sprint: { create: (input) => sprintEngine.create(input), start: (id) => sprintEngine.start(id), pause: (id) => sprintEngine.pause(id) },
126
136
  task: { create: (input) => taskEngine.create(input), start: (id) => taskEngine.start(id), block: (id) => taskEngine.block(id) },
@@ -128,16 +138,25 @@ export function createDefaultControlPlane(eventStream, registry = createDefaultC
128
138
  approvals: { get: (id) => approvals.get(id), list: () => approvals.list(), decide: (input) => { const value = input; return approvals.decide(value.id, { decision: value.input.decision, approverId: value.input.approverId, decidedAt: value.input.decidedAt ?? new Date().toISOString() }); } },
129
139
  events: { publish: (event) => { eventStream.publish({ id: event.id, event: event.type, data: event.data, correlationId: event.correlationId }); void events?.append({ type: event.type, aggregateId: event.aggregateId, payload: event.data, idempotencyKey: `${event.type}:${event.id}`, correlationId: event.correlationId }); } },
130
140
  });
141
+ const mcp = createDefaultMcp(registry, policy, sharedGraph, mcpAudit, sharedContext, { taskEngine, handoffEngine }, { propose: (input) => controlPlane.planPropose(input), get: (id) => controlPlane.planGet(id) });
142
+ return { controlPlane, mcp };
143
+ }
144
+ function synchronousSnapshot(value) {
145
+ if (value instanceof Promise) {
146
+ void value.catch(() => undefined);
147
+ throw new PlanningError('PLANNING_SOURCE_UNSUPPORTED', 'Planning requires an atomic local snapshot store');
148
+ }
149
+ return value;
131
150
  }
132
151
  export async function bootstrap(port = Number(process.env.FORJA_PORT ?? 3000)) {
133
152
  const eventStream = new InMemoryEventStream();
134
153
  const registry = createDefaultCapabilityRegistry();
135
- const policy = createDefaultPolicy();
136
154
  fs.mkdirSync(getWorkspaceDbDir(), { recursive: true });
137
155
  const runtimeDatabase = new Database(process.env.FORJA_RUNTIME_DB ?? getWorkspaceDbPath());
138
156
  new SqliteMigrationRunner(runtimeDatabase).apply();
139
157
  const runtimePersistence = new SqliteRuntimePersistence(runtimeDatabase);
140
158
  const approvals = new ApprovalLedger(new SqliteApprovalStore(runtimeDatabase));
159
+ const policy = createDefaultPolicy(approvals);
141
160
  const mcpAudit = new SqliteMcpAuditSink(runtimeDatabase);
142
161
  const events = new EventBus(new SqliteEventStore(runtimeDatabase));
143
162
  const graph = new GraphLoop(new SqliteGraphStore(runtimeDatabase));
@@ -145,13 +164,16 @@ export async function bootstrap(port = Number(process.env.FORJA_PORT ?? 3000)) {
145
164
  const observationStore = new SqliteObservationStore(runtimeDatabase);
146
165
  registerGraphSyncCapability(registry, graph, new GitGraphDocumentSource(process.env.FORJA_GRAPH_ROOT ?? process.cwd(), new SpawnCommandRunner()));
147
166
  const context = new ContextEngine({ graph: new GraphContextSource({ searchContext: (objective) => graph.contextRecords(objective) }), cache: new SqliteContextCache(runtimeDatabase) });
148
- const mcp = createDefaultMcp(registry, policy, graph, mcpAudit, context);
167
+ const { mcp, controlPlane } = await createDefaultServerServices(eventStream, registry, policy, runtimePersistence, approvals, events, graph, context, orchestrationStore, observationStore, undefined, mcpAudit, { store: new SqlitePlanningStore(runtimeDatabase) });
149
168
  const authenticator = createLocalAuthenticator();
150
169
  if (authenticator === undefined)
151
170
  console.warn('[forja] FORJA_AUTH_TOKEN is not set — only loopback (127.0.0.1/::1) requests will be accepted. Set FORJA_AUTH_TOKEN before exposing this server beyond localhost.');
152
- const app = await NestFactory.create(AppModule.register({ mcp, eventStream, authenticator, controlPlane: createDefaultControlPlane(eventStream, registry, policy, runtimePersistence, approvals, events, graph, context, orchestrationStore, observationStore) }));
171
+ const app = await NestFactory.create(AppModule.register({ mcp, eventStream, authenticator, controlPlane }));
153
172
  const config = new DocumentBuilder().setTitle('ForjaJS 2.0 API').setDescription('Local-first agent control plane').setVersion('2.0.0').build();
154
- SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, config));
173
+ const document = SwaggerModule.createDocument(app, config);
174
+ document.openapi = '3.1.0';
175
+ Object.assign(document.paths, planningOpenApiPaths());
176
+ SwaggerModule.setup('docs', app, document);
155
177
  await app.listen(port, '127.0.0.1');
156
178
  const shutdown = (signal) => {
157
179
  console.log(`[forja] received ${signal}, closing database and shutting down`);
@@ -0,0 +1,29 @@
1
+ import { type AgentIdentity, type PlanningProposal } from '../../../packages/contracts/src/index.ts';
2
+ import type { CapabilityPolicy } from '../../../packages/core/src/index.ts';
3
+ import { ContextEngine } from '../../../packages/context/src/index.ts';
4
+ import { type OrchestrationStore, type TaskEngine } from '../../../packages/orchestration/src/index.ts';
5
+ import { type PlanningStore } from '../../../packages/planner/src/proposal-store.ts';
6
+ export interface TaskPlanningDependencies {
7
+ readonly orchestration: OrchestrationStore;
8
+ readonly tasks: TaskEngine;
9
+ readonly context: ContextEngine;
10
+ readonly proposals: PlanningStore;
11
+ readonly policy: CapabilityPolicy;
12
+ readonly executor: AgentIdentity;
13
+ readonly reviewer?: AgentIdentity;
14
+ }
15
+ export declare class TaskPlanningService {
16
+ private readonly dependencies;
17
+ constructor(dependencies: TaskPlanningDependencies);
18
+ propose(input: unknown): Promise<PlanningProposal>;
19
+ get(id: unknown): Promise<PlanningProposal>;
20
+ review(id: unknown, input: unknown): Promise<PlanningProposal>;
21
+ private generate;
22
+ private snapshot;
23
+ private eligible;
24
+ private authorize;
25
+ private budget;
26
+ private find;
27
+ private string;
28
+ private object;
29
+ }
@@ -0,0 +1,195 @@
1
+ import { createHash, randomUUID } from 'node:crypto';
2
+ import path from 'node:path';
3
+ import { CONTRACT_VERSION, validateTokenBudget } from '../../../packages/contracts/src/index.js';
4
+ import { ContextEngineError } from '../../../packages/context/src/index.js';
5
+ import { OrchestrationError } from '../../../packages/orchestration/src/index.js';
6
+ import { DeterministicPlanner } from '../../../packages/planner/src/index.js';
7
+ import { PlanningError } from '../../../packages/planner/src/proposal-store.js';
8
+ export class TaskPlanningService {
9
+ dependencies;
10
+ constructor(dependencies) {
11
+ this.dependencies = dependencies;
12
+ }
13
+ async propose(input) {
14
+ const value = this.object(input, ['taskId', 'handoffId', 'budget', 'correlationId']);
15
+ const taskId = this.string(value.taskId);
16
+ const handoffId = value.handoffId === undefined ? undefined : this.string(value.handoffId);
17
+ const correlationId = value.correlationId === undefined ? randomUUID() : this.string(value.correlationId);
18
+ const snapshot = await this.snapshot(taskId, handoffId);
19
+ const budget = this.budget(value.budget, snapshot.task.budget);
20
+ this.authorize('planning.propose', this.dependencies.executor, snapshot, budget);
21
+ await this.eligible(snapshot);
22
+ const proposal = await this.generate(randomUUID(), snapshot, budget, correlationId);
23
+ await this.dependencies.proposals.create(proposal);
24
+ return this.find(proposal.id);
25
+ }
26
+ async get(id) {
27
+ const proposal = await this.find(id);
28
+ this.authorize('planning.get', this.dependencies.executor, proposal.snapshot, proposal.budget.limit);
29
+ return proposal;
30
+ }
31
+ async review(id, input) {
32
+ const value = this.object(input, ['decision', 'expectedDigest', 'reason']);
33
+ if (value.decision !== 'approved' && value.decision !== 'rejected')
34
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Review decision must be approved or rejected');
35
+ const digest = this.string(value.expectedDigest);
36
+ const reason = this.string(value.reason);
37
+ const reviewer = this.dependencies.reviewer;
38
+ if (reviewer === undefined)
39
+ throw new PlanningError('PLANNING_REVIEWER_UNAVAILABLE', 'A trusted host reviewer is not configured');
40
+ const proposal = await this.find(id);
41
+ this.authorize('planning.review', reviewer, proposal.snapshot, proposal.budget.limit);
42
+ if (proposal.digest !== digest)
43
+ throw new PlanningError('PLANNING_CONFLICT', 'The proposal digest does not match');
44
+ if (proposal.review !== undefined) {
45
+ if (proposal.review.decision === value.decision && proposal.review.reason === reason && proposal.review.reviewerId === reviewer.id)
46
+ return proposal;
47
+ throw new PlanningError('PLANNING_CONFLICT', 'A different review is already recorded');
48
+ }
49
+ if (proposal.status !== 'draft')
50
+ throw new PlanningError('PLANNING_INVALID_REVIEW', 'Only a draft proposal can be reviewed');
51
+ let snapshot;
52
+ let sourcesVerifiedAt;
53
+ if (value.decision === 'approved') {
54
+ snapshot = await this.snapshot(proposal.snapshot.task.id, proposal.snapshot.handoff?.id);
55
+ if (canonical(snapshot) !== canonical(proposal.snapshot) || canonical(this.dependencies.executor) !== canonical(proposal.executor))
56
+ throw new PlanningError('PLANNING_STALE', 'Task, handoff or executor changed; generate a new proposal');
57
+ await this.eligible(snapshot);
58
+ const current = await this.generate(proposal.id, snapshot, proposal.budget.limit, proposal.correlationId);
59
+ if (current.status !== 'draft' || current.digest !== proposal.digest)
60
+ throw new PlanningError('PLANNING_STALE', 'Planning sources changed; generate a new proposal');
61
+ sourcesVerifiedAt = new Date().toISOString();
62
+ }
63
+ const decidedAt = new Date().toISOString();
64
+ const reviewed = { ...proposal, status: value.decision, updatedAt: decidedAt, review: { decision: value.decision, reviewerId: reviewer.id, reason, digest, decidedAt, ...(sourcesVerifiedAt === undefined ? {} : { sourcesVerifiedAt }) } };
65
+ await this.dependencies.proposals.review(proposal, reviewed, snapshot);
66
+ return this.find(proposal.id);
67
+ }
68
+ async generate(id, snapshot, limit, correlationId) {
69
+ const { task, handoff } = snapshot;
70
+ const acceptanceCriteria = [...new Set([...task.acceptanceCriteria, ...(handoff?.acceptance ?? [])])];
71
+ const briefing = {
72
+ objective: task.objective, acceptanceCriteria, allowedFiles: task.allowedFiles, dependencyIds: task.dependencyIds,
73
+ handoff: handoff === undefined ? undefined : { from: handoff.from, to: handoff.to, nextAgent: handoff.nextAgent, intent: handoff.intent, objective: handoff.objective, completedWork: handoff.completedWork, decisions: handoff.decisions, constraints: handoff.constraints, pending: handoff.pending, blockers: handoff.blockers },
74
+ };
75
+ const briefingTokens = Math.ceil(Buffer.byteLength(canonical(briefing), 'utf8') / 4);
76
+ const inputAvailable = Math.max(0, limit.inputTokens - limit.usedTokens);
77
+ const outputAvailable = Math.max(0, limit.outputTokens - limit.usedTokens);
78
+ const blockers = (handoff?.blockers ?? []).map((message) => ({ code: 'HANDOFF_BLOCKED', message }));
79
+ let context;
80
+ if (briefingTokens >= inputAvailable)
81
+ blockers.push({ code: 'CONTEXT_BUDGET_EXCEEDED', message: 'The mandatory briefing leaves no input budget for evidence' });
82
+ if (blockers.length === 0) {
83
+ const available = inputAvailable - briefingTokens;
84
+ try {
85
+ context = await this.dependencies.context.build({ objective: [task.objective, ...acceptanceCriteria, ...(handoff?.pending ?? [])].join('\n'), budget: { inputTokens: available, outputTokens: 0, totalTokens: available, usedTokens: 0 }, requireEvidence: true, includeContent: true, includeProvenanceInBudget: true, maxItems: 20, correlationId });
86
+ if (context.items === undefined || context.items.length === 0)
87
+ throw new ContextEngineError('INSUFFICIENT_EVIDENCE', 'The context source did not provide item provenance');
88
+ }
89
+ catch (error) {
90
+ if (!(error instanceof ContextEngineError) || !['INSUFFICIENT_EVIDENCE', 'CONTEXT_BUDGET_EXCEEDED'].includes(error.code))
91
+ throw error;
92
+ blockers.push({ code: error.code, message: error.message });
93
+ }
94
+ }
95
+ const contextTokens = context?.metrics.selectedTokens ?? 0;
96
+ const allocatedInput = Math.max(0, inputAvailable - briefingTokens - contextTokens);
97
+ const allocation = { inputTokens: allocatedInput, outputTokens: outputAvailable, totalTokens: allocatedInput + outputAvailable, usedTokens: 0 };
98
+ const budget = { limit, briefingTokens, contextTokens, allocation };
99
+ const plan = blockers.length > 0 || context === undefined ? undefined : new DeterministicPlanner().plan({
100
+ planId: id, objective: task.objective, acceptanceCriteria, allowedFiles: task.allowedFiles, dependencyIds: task.dependencyIds,
101
+ evidenceIds: context.references.map((evidence) => evidence.id), contextItems: context.items, constraints: handoff?.constraints ?? [], decisions: handoff?.decisions ?? [], pending: handoff?.pending ?? [], budget: allocation, correlationId,
102
+ });
103
+ const now = new Date().toISOString();
104
+ const digest = createHash('sha256').update(canonical({ snapshot, executor: this.dependencies.executor, budget, plan, items: context?.items, blockers }, true)).digest('hex');
105
+ return { schemaVersion: CONTRACT_VERSION, id, version: 1, createdAt: now, updatedAt: now, correlationId, digest, executor: { ...this.dependencies.executor }, snapshot, status: blockers.length > 0 ? 'blocked' : 'draft', plan, context, budget, blockers, declaredEvidenceIds: [...new Set([...task.evidenceIds, ...(handoff?.evidenceIds ?? [])])] };
106
+ }
107
+ async snapshot(taskId, handoffId) {
108
+ const task = await this.dependencies.orchestration.getTask(taskId);
109
+ if (task === undefined)
110
+ throw new PlanningError('PLANNING_NOT_FOUND', 'Task not found');
111
+ const sprint = await this.dependencies.orchestration.getSprint(task.sprintId);
112
+ if (sprint === undefined)
113
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'Task sprint is missing');
114
+ const handoff = handoffId === undefined ? undefined : await this.dependencies.orchestration.getHandoff(handoffId);
115
+ if (handoffId !== undefined && (handoff === undefined || handoff.taskId !== task.id || handoff.runId !== undefined || handoff.status !== 'pending' || handoff.nextAgent !== this.dependencies.executor.id))
116
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'Handoff does not match the task and host executor');
117
+ const dependencies = [];
118
+ for (const id of task.dependencyIds) {
119
+ const dependency = await this.dependencies.orchestration.getTask(id);
120
+ if (dependency === undefined)
121
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'Task dependency is missing');
122
+ dependencies.push(dependency);
123
+ }
124
+ return JSON.parse(JSON.stringify({ task, sprint, dependencies, ...(handoff === undefined ? {} : { handoff }) }));
125
+ }
126
+ async eligible(snapshot) {
127
+ const { task } = snapshot;
128
+ if ((task.status !== 'todo' && task.status !== 'in_progress') || task.runtimeRunId !== undefined)
129
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'Planning requires an open, unbound task');
130
+ if (task.allowedFiles.some((file) => file !== '*' && (file.length === 0 || file.includes('\\') || path.posix.isAbsolute(file) || file.split('/').includes('..') || path.posix.normalize(file) !== file)))
131
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'Task file scope must use normalized relative paths');
132
+ try {
133
+ await this.dependencies.tasks.assertEligible(task);
134
+ }
135
+ catch (error) {
136
+ if (!(error instanceof OrchestrationError))
137
+ throw error;
138
+ throw new PlanningError('PLANNING_INVALID_SCOPE', 'The task is not eligible in its sprint');
139
+ }
140
+ }
141
+ authorize(action, actor, snapshot, budget) {
142
+ const category = action === 'planning.get' ? 'read' : 'write';
143
+ const now = new Date().toISOString();
144
+ const decision = this.dependencies.policy.authorize({ agent: actor, input: { capabilityId: action, payload: { taskId: snapshot.task.id, handoffId: snapshot.handoff?.id } }, environment: 'local', files: snapshot.task.allowedFiles, categories: [category], budget, now, definition: { schemaVersion: CONTRACT_VERSION, createdAt: now, updatedAt: now, correlationId: action, id: action, version: '1.0.0', description: action, permissions: [category], risk: category === 'read' ? 'low' : 'medium', sideEffects: category === 'read' ? [] : ['planning-proposal'], requirements: [], supportsAutonomy: false, idempotent: category === 'read', timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] } });
145
+ if (decision.effect !== 'ALLOW' && decision.effect !== 'ALLOW_WITH_LIMITS')
146
+ throw new PlanningError('PLANNING_DENIED', 'Policy does not permit this planning action');
147
+ for (const [key, limit] of Object.entries(decision.limits ?? {})) {
148
+ if (!Number.isFinite(limit) || limit < 0 || (key !== 'maxTokens' && key !== 'maxFiles'))
149
+ throw new PlanningError('PLANNING_DENIED', 'Policy contains an unsupported planning limit');
150
+ if ((key === 'maxTokens' && budget.totalTokens > limit) || (key === 'maxFiles' && (snapshot.task.allowedFiles.some((file) => file === '*' || file.endsWith('/')) || snapshot.task.allowedFiles.length > limit)))
151
+ throw new PlanningError('PLANNING_DENIED', 'Planning scope exceeds policy limits');
152
+ }
153
+ }
154
+ budget(value, ceiling) {
155
+ const budget = value === undefined ? ceiling : this.object(value, ['inputTokens', 'outputTokens', 'totalTokens', 'usedTokens']);
156
+ for (const field of ['inputTokens', 'outputTokens', 'totalTokens', 'usedTokens'])
157
+ if (!Number.isSafeInteger(budget[field]))
158
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Budget values must be safe integers');
159
+ try {
160
+ validateTokenBudget(budget);
161
+ }
162
+ catch {
163
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Budget is inconsistent');
164
+ }
165
+ const result = budget;
166
+ if (result.inputTokens > ceiling.inputTokens || result.outputTokens > ceiling.outputTokens || result.totalTokens > ceiling.totalTokens || result.usedTokens < ceiling.usedTokens)
167
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Planning budget cannot expand the task budget or erase consumption');
168
+ return { ...result };
169
+ }
170
+ async find(value) {
171
+ const proposal = await this.dependencies.proposals.get(this.string(value));
172
+ if (proposal === undefined)
173
+ throw new PlanningError('PLANNING_NOT_FOUND', 'Planning proposal not found');
174
+ return proposal;
175
+ }
176
+ string(value) {
177
+ if (typeof value !== 'string' || value.trim().length === 0)
178
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Expected a nonempty string');
179
+ return value;
180
+ }
181
+ object(value, fields) {
182
+ if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype || Object.keys(value).some((key) => !fields.includes(key)))
183
+ throw new PlanningError('PLANNING_INVALID_INPUT', 'Unexpected planning input fields');
184
+ return value;
185
+ }
186
+ }
187
+ function canonical(value, omitAudit = false) {
188
+ return JSON.stringify(value, (key, item) => {
189
+ if (omitAudit && ['createdAt', 'updatedAt', 'correlationId'].includes(key))
190
+ return undefined;
191
+ if (typeof item === 'object' && item !== null && !Array.isArray(item))
192
+ return Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right)));
193
+ return item;
194
+ });
195
+ }