@studio-foundation/engine 0.3.0-beta.1

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 (90) hide show
  1. package/ARCHITECTURE.md +57 -0
  2. package/LICENSE +663 -0
  3. package/README.md +118 -0
  4. package/package.json +47 -0
  5. package/src/__tests__/__fixtures__/script-stage/contracts/book-context.contract.yaml +4 -0
  6. package/src/__tests__/engine.conditions-group.test.ts +244 -0
  7. package/src/__tests__/engine.conditions.test.ts +186 -0
  8. package/src/__tests__/engine.resume.test.ts +108 -0
  9. package/src/__tests__/engine.script-stage.test.ts +125 -0
  10. package/src/db/client.ts +5 -0
  11. package/src/engine.context-event.test.ts +175 -0
  12. package/src/engine.ts +491 -0
  13. package/src/events.ts +167 -0
  14. package/src/index.ts +64 -0
  15. package/src/pipeline/agent-loader.test.ts +151 -0
  16. package/src/pipeline/agent-loader.ts +39 -0
  17. package/src/pipeline/condition-evaluator.test.ts +129 -0
  18. package/src/pipeline/condition-evaluator.ts +121 -0
  19. package/src/pipeline/context-pack-loader.ts +63 -0
  20. package/src/pipeline/context-propagation.test.ts +237 -0
  21. package/src/pipeline/context-propagation.ts +235 -0
  22. package/src/pipeline/contract-loader.ts +41 -0
  23. package/src/pipeline/group-orchestrator.ts +483 -0
  24. package/src/pipeline/hook-executor.test.ts +121 -0
  25. package/src/pipeline/hook-executor.ts +87 -0
  26. package/src/pipeline/invariants-loader.test.ts +51 -0
  27. package/src/pipeline/invariants-loader.ts +14 -0
  28. package/src/pipeline/loader.test.ts +128 -0
  29. package/src/pipeline/loader.ts +149 -0
  30. package/src/pipeline/output-validator.test.ts +100 -0
  31. package/src/pipeline/output-validator.ts +40 -0
  32. package/src/pipeline/post-validator.ts +124 -0
  33. package/src/pipeline/skill-loader.test.ts +44 -0
  34. package/src/pipeline/skill-loader.ts +32 -0
  35. package/src/pipeline/stage-executor.ts +654 -0
  36. package/src/pipeline/stage-resolver.ts +8 -0
  37. package/src/pipeline/startup-executor.test.ts +37 -0
  38. package/src/pipeline/startup-executor.ts +32 -0
  39. package/src/pipeline/types.ts +42 -0
  40. package/src/repo-resolver.ts +61 -0
  41. package/src/spawners/direct-engine-spawner.ts +26 -0
  42. package/src/state/run-store.test.ts +157 -0
  43. package/src/state/run-store.ts +362 -0
  44. package/src/state/state-machine.ts +35 -0
  45. package/src/state/status-derivation.ts +36 -0
  46. package/tests/context-pack-loader.test.ts +113 -0
  47. package/tests/context-propagation.test.ts +267 -0
  48. package/tests/direct-engine-spawner.test.ts +102 -0
  49. package/tests/e2e/feature-v5.test.ts +57 -0
  50. package/tests/events.test.ts +56 -0
  51. package/tests/fixtures/agents/test-agent.agent.yaml +5 -0
  52. package/tests/fixtures/contracts/code-gen.contract.yaml +6 -0
  53. package/tests/fixtures/contracts/qa-gate.contract.yaml +15 -0
  54. package/tests/fixtures/contracts/test-contract.contract.yaml +6 -0
  55. package/tests/fixtures/pipelines/group-test.pipeline.yaml +40 -0
  56. package/tests/fixtures/pipelines/simple.pipeline.yaml +15 -0
  57. package/tests/fixtures/pipelines/two-stage.pipeline.yaml +24 -0
  58. package/tests/fixtures/software/pipelines/feature-builder.pipeline.yaml +75 -0
  59. package/tests/fixtures/test-project/agents/test-agent.agent.yaml +5 -0
  60. package/tests/fixtures/test-project/contracts/basic-result.contract.yaml +6 -0
  61. package/tests/fixtures/test-project/contracts/code-gen.contract.yaml +6 -0
  62. package/tests/fixtures/test-project/contracts/maximum-only.contract.yaml +8 -0
  63. package/tests/fixtures/test-project/contracts/qa-gate.contract.yaml +15 -0
  64. package/tests/fixtures/test-project/contracts/strict-result.contract.yaml +7 -0
  65. package/tests/fixtures/test-project/contracts/test-contract.contract.yaml +6 -0
  66. package/tests/fixtures/test-project/pipelines/group-simple.pipeline.yaml +26 -0
  67. package/tests/fixtures/test-project/pipelines/group-test.pipeline.yaml +40 -0
  68. package/tests/fixtures/test-project/pipelines/hook-output-template.pipeline.yaml +19 -0
  69. package/tests/fixtures/test-project/pipelines/hook-reject-on-failure.pipeline.yaml +19 -0
  70. package/tests/fixtures/test-project/pipelines/maximum-only.pipeline.yaml +15 -0
  71. package/tests/fixtures/test-project/pipelines/parallel-collect-all-test.pipeline.yaml +39 -0
  72. package/tests/fixtures/test-project/pipelines/parallel-context-isolation-test.pipeline.yaml +38 -0
  73. package/tests/fixtures/test-project/pipelines/parallel-fail-test.pipeline.yaml +39 -0
  74. package/tests/fixtures/test-project/pipelines/parallel-test.pipeline.yaml +39 -0
  75. package/tests/fixtures/test-project/pipelines/parallel-then-sequential-test.pipeline.yaml +38 -0
  76. package/tests/fixtures/test-project/pipelines/simple.pipeline.yaml +15 -0
  77. package/tests/fixtures/test-project/pipelines/two-stage.pipeline.yaml +24 -0
  78. package/tests/fixtures/test-project/pipelines/with-startup.pipeline.yaml +19 -0
  79. package/tests/loader.test.ts +385 -0
  80. package/tests/post-validator.test.ts +297 -0
  81. package/tests/repo-resolver.test.ts +102 -0
  82. package/tests/run-store.test.ts +143 -0
  83. package/tests/state-machine.test.ts +110 -0
  84. package/tests/unit/context-propagation.test.ts +45 -0
  85. package/tests/unit/engine.test.ts +770 -0
  86. package/tests/unit/group-loop.test.ts +389 -0
  87. package/tests/unit/group-parallel.test.ts +423 -0
  88. package/tests/unit/state/status-derivation.test.ts +88 -0
  89. package/tsconfig.json +24 -0
  90. package/vitest.config.ts +14 -0
package/ARCHITECTURE.md ADDED
@@ -0,0 +1,57 @@
1
+ # @studio-foundation/engine
2
+
3
+ Orchestrateur de pipelines. Le cerveau de Studio.
4
+
5
+ ## Concept
6
+
7
+ Charge une pipeline YAML → exécute les stages en séquence (ou en groups avec feedback loops) → pour chaque stage : hooks + `ralph(runAgent, validator)` → persiste les runs → émet des events.
8
+
9
+ ## Règles
10
+
11
+ - **Domain-agnostic.** Pas de référence à "code", "file", "git", "QA" dans le source. `StageKind = string`.
12
+ - `deriveStageStatus()` dans `state/status-derivation.ts` est LA fonction critique — mapping déterministe ralph result → stage status
13
+ - La DB est configurable : `SQLiteRunStore` | `PgRunStore` | `InMemoryRunStore` (union `AnyRunStore`)
14
+ - Le engine ne construit pas de prompts — c'est runner
15
+ - Le engine ne sait pas ce qu'est `repo_manager-write_file` — c'est runner
16
+ - Dépend de `@studio-foundation/contracts`, `@studio-foundation/ralph`, `@studio-foundation/runner`, `@studio-foundation/anonymizer`
17
+
18
+ ## Fichiers clés
19
+
20
+ - `engine.ts` — `PipelineEngine` (classe principale), `EngineConfig`, `RunInput`
21
+ - `events.ts` — `EngineEvents`, `PipelineEventEmitter`
22
+ - `state/status-derivation.ts` — `deriveStageStatus()` ← CRITIQUE
23
+ - `state/run-store.ts` — `AnyRunStore`, `InMemoryRunStore`
24
+ - `pipeline/loader.ts` — charge YAML → `PipelineDefinition`
25
+ - `pipeline/agent-loader.ts` — charge agent YAML + injecte skills
26
+ - `pipeline/contract-loader.ts` — charge contract YAML
27
+ - `pipeline/context-propagation.ts` — `createInitialContext`, `addStageOutput`, `getContextForStage`
28
+ - `pipeline/context-pack-loader.ts` — charge les context packs
29
+ - `pipeline/hook-executor.ts` — `runStageHook()`, `runToolHook()` (4 points de hook)
30
+ - `pipeline/startup-executor.ts` — `executeStartupCommands()` pour `on_pipeline_start`
31
+ - `pipeline/post-validator.ts` — `postValidate()` (rejection detection)
32
+ - `pipeline/skill-loader.ts` — charge les `.skill.md` files
33
+ - `db/client.ts` — SQLite client (pour WebhookStore, IntegrationStore côté api)
34
+ - `spawners/direct-engine-spawner.ts` — `DirectEngineSpawner` implémente `RunSpawner`
35
+
36
+ ## Groups (feedback loops)
37
+
38
+ Un group contient plusieurs stages qui itèrent ensemble. Si le dernier stage rejette (via `post_validation.rejection_detection`), le group redémarre depuis le début avec le feedback accumulé. `max_iterations` cap.
39
+
40
+ ## Hooks lifecycle
41
+
42
+ 4 points déterministes : `on_stage_start`, `on_stage_complete`, `pre_tool_use`, `post_tool_use`.
43
+ `on_failure: warn | reject | fail`. Les hooks `pre_tool_use` avec reject bloquent le tool call.
44
+
45
+ ## État machine
46
+
47
+ ```
48
+ pending → running → success
49
+ → failed (ralph exhausted, ou hook on_failure: fail)
50
+ → rejected (post_validation, ou hook on_failure: reject)
51
+ → skipped
52
+ → cancelled (AbortSignal)
53
+ ```
54
+
55
+ ## Dépendances
56
+
57
+ `@studio-foundation/contracts`, `@studio-foundation/ralph`, `@studio-foundation/runner`, `@studio-foundation/anonymizer`