4 4 #
Chef Orchestrator Plugin 6 6 Declarative pipeline orchestration for OpenCode multi-agent workflows.
10 -Chef provides a TypeScript DSL for defining structured workflows that coordinate multiple agents. It leverages OpenCode's SDK capabilities for:
10 +Chef provides a TypeScript DSL for defining structured workflows that coordinate
11 +multiple agents. It leverages OpenCode's SDK capabilities for:
12 13 - **Message Injection**: Pass context between agents via `noReply: true`
13 14 - **Structured Output**: Automatic JSON schema validation with retries
117 118 ##
Retry Policies 119 -Steps support configurable retry behavior. When a step fails, Chef automatically retries with exponential backoff before marking the step as failed.
120 +Steps support configurable retry behavior. When a step fails, Chef automatically
121 +retries with exponential backoff before marking the step as failed.
121 123 ###
Configuration 140 -| Field | Type | Default | Description |
142 -| `maxAttempts` | `number` | `1` | Maximum number of attempts (including the first run) |
143 -| `backoffMs` | `number` | `1000` | Base delay in milliseconds before the first retry |
144 -| `retryOn` | `string[] \| undefined` | `undefined` | Error types that trigger a retry |
142 +| Field | Type | Default | Description |
143 +| ------------- | ----------------------- | ----------- | ---------------------------------------------------- |
144 +| `maxAttempts` | `number` | `1` | Maximum number of attempts (including the first run) |
145 +| `backoffMs` | `number` | `1000` | Base delay in milliseconds before the first retry |
146 +| `retryOn` | `string[] \| undefined` | `undefined` | Error types that trigger a retry |
146 148 ###
Backoff Behavior 148 -Delays use exponential backoff: `backoffMs * 2^attempt`. For `backoffMs: 2000` with 3 attempts:
150 +Delays use exponential backoff: `backoffMs * 2^attempt`. For `backoffMs: 2000`
150 153 - Attempt 1: immediate
151 154 - Attempt 2: waits 2000ms
164 167 ###
Retry Feedback 166 -On retry, Chef injects the previous error message into the agent's context so it can correct its behavior:
169 +On retry, Chef injects the previous error message into the agent's context so it
170 +can correct its behavior:
169 173 Previous attempt failed with: Step "implement" timed out after 30000ms.
173 177 ##
Timeout Handling 175 -Steps support a `timeout` option (in milliseconds) that limits how long an agent can run. If the agent exceeds the deadline, the step fails with an `AgentTimeoutError`.
179 +Steps support a `timeout` option (in milliseconds) that limits how long an agent
180 +can run. If the agent exceeds the deadline, the step fails with an
181 +`AgentTimeoutError`.
214 220 ##
Reusable Fragments 216 -Fragments let you define reusable sequences of steps that can be included in multiple pipelines. This avoids duplicating common step definitions.
222 +Fragments let you define reusable sequences of steps that can be included in
223 +multiple pipelines. This avoids duplicating common step definitions.
218 225 ###
Defining a Fragment 248 255 ###
Including a Fragment 250 -Use the `.use()` method on a pipeline builder to include all steps from a fragment:
257 +Use the `.use()` method on a pipeline builder to include all steps from a
253 261 export default pipeline(
"feature")
260 -The `.use()` method adds each step from the fragment as an individual phase in the pipeline, preserving their order.
268 +The `.use()` method adds each step from the fragment as an individual phase in
269 +the pipeline, preserving their order.
262 271 ## Pipeline Validation
264 -Chef validates pipeline definitions at startup when pipelines are loaded from disk. This catches configuration errors early, before any execution begins.
273 +Chef validates pipeline definitions at startup when pipelines are loaded from
274 +disk. This catches configuration errors early, before any execution begins.
268 -When the plugin loads pipeline files, it calls the builder's `validate()` method automatically. Validation warnings appear in the console:
278 +When the plugin loads pipeline files, it calls the builder's `validate()` method
279 +automatically. Validation warnings appear in the console:
271 282 Chef: Pipeline "feature" has validation errors:
294 305 ###
What Gets Validated 296 -| Check | Description |
298 -| Output schema | Each step must have a valid Zod schema (`parse` is a function) |
299 -| Agent name | Each step must have a non-empty string agent |
300 -| Gate expect schema | Each gate must have a valid Zod schema for `expect` |
301 -| Gate `onFail` target | If set, must reference a step that exists earlier in the pipeline |
302 -| `when` loop target | If set, must reference a step that exists in the pipeline |
303 -| `when` condition | Must be a function |
304 -| Parallel step schemas | Each parallel sub-step must have valid output and agent |
307 +| Check | Description |
308 +| --------------------- | ----------------------------------------------------------------- |
309 +| Output schema | Each step must have a valid Zod schema (`parse` is a function) |
310 +| Agent name | Each step must have a non-empty string agent |
311 +| Gate expect schema | Each gate must have a valid Zod schema for `expect` |
312 +| Gate `onFail` target | If set, must reference a step that exists earlier in the pipeline |
313 +| `when` loop target | If set, must reference a step that exists in the pipeline |
314 +| `when` condition | Must be a function |
315 +| Parallel step schemas | Each parallel sub-step must have valid output and agent |
306 317 ###
Agent Name Checks 308 -In addition to structural validation, Chef checks that referenced agent names exist at startup. Unknown agents produce warnings:
319 +In addition to structural validation, Chef checks that referenced agent names
320 +exist at startup. Unknown agents produce warnings:
311 323 Chef: Pipeline "feature" step "research" references unknown agent "unknown_agent"
314 326 ##
Error Handling 316 -Chef classifies errors into a taxonomy so that retry policies and debugging can target specific failure modes.
328 +Chef classifies errors into a taxonomy so that retry policies and debugging can
329 +target specific failure modes.
320 -| Error Class | Type String | Cause |
322 -| `AgentTimeoutError` | `agent_timeout` | Step exceeded its `timeout` deadline |
323 -| `AgentError` | `agent_error` | Agent returned an error during execution |
324 -| `GateFailureError` | `gate_failure` | Gate validation or agent evaluation failed |
325 -| `SchemaValidationError` | `schema_validation` | Agent output did not match the Zod schema |
333 +| Error Class | Type String | Cause |
334 +| -------------------- | ---------------- | --------------------------------------------------------- |
335 +| `AgentTimeoutError` | `agent_timeout` | Step exceeded its `timeout` deadline |
336 +| `AgentError` | `agent_error` | Agent returned an error during execution |
337 +| `GateFailureError` | `gate_failure` | Gate validation or agent evaluation failed |
326 338 | `MaxIterationsError` | `max_iterations` | A loop exceeded the maximum iteration count (default: 10) |
328 -All errors extend `ChefError`, which carries a `type` string for programmatic handling.
340 +All errors extend `ChefError`, which carries a `type` string for programmatic
332 345 1. A step, gate, or parallel phase throws an error during execution
333 346 2. The executor catches the error and records it in the phase state
334 -3. If the step has a retry policy and the error type matches `retryOn`, the step is retried
347 +3. If the step has a retry policy and the error type matches `retryOn`, the step
335 349 4. If all retries are exhausted, the step is marked as `failed`
336 350 5. The pipeline status is updated to `failed`
338 352 ###
Loop Iteration Guard 340 -Loops (via `.when()` / `.loop()` or gate `onFail`) are bounded by a maximum iteration count (default: 10). If a loop exceeds this limit, the pipeline fails with a `MaxIterationsError` to prevent infinite cycles.
354 +Loops (via `.when()` / `.loop()` or gate `onFail`) are bounded by a maximum
355 +iteration count (default: 10). If a loop exceeds this limit, the pipeline fails
356 +with a `MaxIterationsError` to prevent infinite cycles.
344 -Gates support an `onFail` option that creates a loop-back when the gate fails. Instead of failing the entire pipeline, execution jumps back to the specified step.
360 +Gates support an `onFail` option that creates a loop-back when the gate fails.
361 +Instead of failing the entire pipeline, execution jumps back to the specified
366 384 ###
Combining with `.when()` / `.loop()` 368 -The `onFail` option and `.when()` / `.loop()` can be used together or independently:
386 +The `onFail` option and `.when()` / `.loop()` can be used together or
383 -The `onFail` handles gate evaluation failures (e.g., the agent returns `{ approved: false }`). The `.when()` / `.loop()` handles the conditional branch after a successful gate evaluation that returns a negative result.
402 +The `onFail` handles gate evaluation failures (e.g., the agent returns
403 +`{ approved: false }`). The `.when()` / `.loop()` handles the conditional branch
404 +after a successful gate evaluation that returns a negative result.
387 -The `onFail` target is validated at startup. If the target step does not exist in the pipeline, a validation error is reported.
408 +The `onFail` target is validated at startup. If the target step does not exist
409 +in the pipeline, a validation error is reported.
393 415 Start a new pipeline execution.
396 419 - `name` (string): Pipeline name
397 420 - `input` (any, optional): Input data
402 426 "pipeline_id":
"uuid",
410 434 Check pipeline status.
413 438 - `id` (string, optional): Pipeline ID (defaults to all running)
415 440 ###
pipeline.continue 417 442 Continue after `needs_input` status.
420 446 - `id` (string): Pipeline ID
421 447 - `input` (any): Input data for next phase
425 451 Cancel a running pipeline.
428 455 - `id` (string): Pipeline ID
430 457 ###
pipeline.list 451 478 Retry/Timeout → exponential backoff + Promise.race
453 480 State Persistence → SQLite (store.ts)
481 + ↳ schema_version (version tracking)
482 + ↳ pipeline_instance
486 +## Schema Migrations
488 +Chef uses a versioned migration system to manage database schema changes. The
489 +`schema_version` table tracks which migrations have been applied.
491 +- Migrations run automatically on startup
492 +- Each migration has a version number, description, and array of SQL statements
493 +- Only migrations newer than the current version are applied
494 +- Applied migrations are logged:
495 + `Chef: Applied schema migration v2: Remove unused step_state table`
497 +Current schema version: **2** (removed unused `step_state` table from initial
456 500 ## Example Pipeline
458 502 See `pipelines/feature.ts` for a complete example with:
461 506 - Approval gate with `onFail` loop-back to "plan"
462 507 - Conditional loop via `.when()` / `.loop()`
463 -- Implementation phase with retry policy (3 attempts, filtered to `agent_error` and `agent_timeout`)
508 +- Implementation phase with retry policy (3 attempts, filtered to `agent_error`
509 + and `agent_timeout`)
464 510 - Reusable review fragment via `fragment()` and `.use()`
465 511 - Per-step timeouts on review steps