@studio-foundation/engine 0.3.0-beta.6 → 0.4.0-beta

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 (2) hide show
  1. package/README.md +32 -12
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,18 +1,24 @@
1
1
  # @studio-foundation/engine
2
2
 
3
- Pipeline orchestration, state machine, persistence, hooks, and skills injection.
3
+ **Studio** is an agentic pipeline runtime that executes multi-stage LLM workflows with structural validation and automatic retry. This package is the **engine**: pipeline orchestration, state machine, persistence, lifecycle hooks, and skills injection.
4
4
 
5
- ## Role
5
+ It loads pipeline configs, sequences stages, delegates each stage to [`ralph`](https://www.npmjs.com/package/@studio-foundation/ralph) + [`runner`](https://www.npmjs.com/package/@studio-foundation/runner), persists state, and emits events for observability. It knows about pipelines, stages, groups, hooks, and skills, but never about LLMs, files, or domain concepts.
6
6
 
7
- engine is the conductor. It loads pipeline configs, sequences stages, delegates execution to ralph+runner, tracks state in SQLite, and emits events for observability. It knows about pipelines, stages, groups, hooks, and skills — but never about LLMs, files, or domain concepts.
7
+ - Homepage: https://github.com/studio-foundation/studio
8
+ - Full docs: [README](https://github.com/studio-foundation/studio#readme) · [CONCEPTS](https://github.com/studio-foundation/studio/blob/main/CONCEPTS.md) · [INVARIANTS](https://github.com/studio-foundation/studio/blob/main/INVARIANTS.md)
9
+ - Use via the CLI: [`@studio-foundation/cli`](https://www.npmjs.com/package/@studio-foundation/cli)
8
10
 
11
+ ## Install
12
+
13
+ ```bash
14
+ npm install @studio-foundation/engine
15
+ # or
16
+ pnpm add @studio-foundation/engine
9
17
  ```
10
- cli → engine.run(pipeline, input) → PipelineRun
11
- ↓
12
- [load pipeline] → [on_pipeline_start] → [for each stage: hooks + ralph(runner)] → [persist state] → [emit events]
13
- ```
14
18
 
15
- ## Key exports
19
+ Most users don't consume `engine` directly, they use the [`studio`](https://www.npmjs.com/package/@studio-foundation/cli) CLI, which wraps it. Install this package if you're embedding Studio into your own runtime.
20
+
21
+ ## Quick start
16
22
 
17
23
  ```typescript
18
24
  import { PipelineEngine } from '@studio-foundation/engine';
@@ -35,6 +41,14 @@ const run = await engine.run({
35
41
  });
36
42
  ```
37
43
 
44
+ ## Architecture
45
+
46
+ ```
47
+ cli → engine.run(pipeline, input) → PipelineRun
48
+ ↓
49
+ [load pipeline] → [on_pipeline_start] → [for each stage: hooks + ralph(runner)] → [persist state] → [emit events]
50
+ ```
51
+
38
52
  ## State machine
39
53
 
40
54
  ```
@@ -58,9 +72,9 @@ The engine executes stage hooks at four deterministic points:
58
72
  | `post_tool_use` | After a tool call (matcher-gated) | `{{tool.argName}}` |
59
73
 
60
74
  Hook failure semantics via `on_failure`:
61
- - `warn` (default) — log and continue
62
- - `reject` — stage → `rejected` (can trigger group retry)
63
- - `fail` — stage → `failed` (stops pipeline)
75
+ - `warn` (default): log and continue
76
+ - `reject`: stage → `rejected` (can trigger group retry)
77
+ - `fail`: stage → `failed` (stops pipeline)
64
78
 
65
79
  `pre_tool_use` hooks with any failure block the tool call. Hook commands run in `repoPath` (or `configsDir` as fallback). Implemented in `pipeline/hook-executor.ts`.
66
80
 
@@ -110,9 +124,15 @@ engine.run({ pipeline, input, anonymize: true })
110
124
 
111
125
  Per-agent anonymization also supported via `anonymize: true` in agent YAML.
112
126
 
113
- ## Rules
127
+ ## For contributors
128
+
129
+ Internal rules that govern this package:
114
130
 
115
131
  - **engine is domain-agnostic.** No references to "code", "file", "git", "QA" in engine source. All domain knowledge is in YAML configs.
116
132
  - **engine doesn't execute tools.** It passes tool configs to runner. The runner decides what `repo_manager-write_file` means.
117
133
  - **engine doesn't build prompts.** That's runner's job.
118
134
  - Persistence: `PgRunStore` (PostgreSQL) for production, `InMemoryRunStore` for tests. Both implement `AnyRunStore`.
135
+
136
+ ## License
137
+
138
+ AGPL-3.0-only
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@studio-foundation/engine",
3
- "version": "0.3.0-beta.6",
3
+ "version": "0.4.0-beta",
4
4
  "description": "Pipeline orchestration engine for Studio v7",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -26,9 +26,9 @@
26
26
  "better-sqlite3": "^9.0.0",
27
27
  "js-yaml": "^4.1.0",
28
28
  "pg": "^8.19.0",
29
- "@studio-foundation/contracts": "0.3.0-beta.6",
30
- "@studio-foundation/runner": "0.3.0-beta.6",
31
- "@studio-foundation/ralph": "0.3.0-beta.6"
29
+ "@studio-foundation/contracts": "0.4.0-beta",
30
+ "@studio-foundation/ralph": "0.4.0-beta",
31
+ "@studio-foundation/runner": "0.4.0-beta"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@types/better-sqlite3": "^7.6.8",