owenloop 0.2.0 → 0.2.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.
- package/CHANGELOG.md +11 -0
- package/README.md +18 -0
- package/dist/defs.js +60 -3
- package/dist/engine.d.ts +68 -1
- package/dist/engine.js +308 -9
- package/dist/model.js +20 -9
- package/dist/store.js +16 -14
- package/dist/types.d.ts +28 -0
- package/docs/authoring.md +70 -0
- package/docs/design.md +193 -29
- package/docs/embedding.md +28 -3
- package/examples/workflows/command-worker.yaml +56 -0
- package/package.json +1 -1
package/docs/authoring.md
CHANGED
|
@@ -70,6 +70,10 @@ steps:
|
|
|
70
70
|
# to the engine, passed through on the order
|
|
71
71
|
# (see below)
|
|
72
72
|
workdir: … # opaque hint passed through on the order; omitted when unset
|
|
73
|
+
worker: agent # opaque executor label (default: agent); see below
|
|
74
|
+
command: … # required when worker: command; opaque, never shelled out
|
|
75
|
+
spec: # optional opaque config map, shape-checked like x: (a plain map)
|
|
76
|
+
anything: goes # contents never read by the engine; see below
|
|
73
77
|
x: # optional; opaque extension map, passed through
|
|
74
78
|
anything: goes # untouched onto the order (Order.x); see design.md §27.3
|
|
75
79
|
```
|
|
@@ -98,6 +102,59 @@ a literal model id. Pin an exact model when you need reproducibility — just
|
|
|
98
102
|
know the def is now host-specific, on purpose. Omit `model:` entirely and the
|
|
99
103
|
dispatcher uses its default.
|
|
100
104
|
|
|
105
|
+
## `worker:` — declaring the executor
|
|
106
|
+
|
|
107
|
+
Every step in every def written before this feature dispatches to an LLM
|
|
108
|
+
agent — that's still the default, and omitting `worker:` entirely leaves a
|
|
109
|
+
def byte-for-byte unchanged. `worker:` lets a step opt into a *different*
|
|
110
|
+
kind of executor instead: a shell command, a webhook, a browser-automation
|
|
111
|
+
runner, anything a dispatcher on the other end of `tick` knows how to run.
|
|
112
|
+
The engine never executes anything itself — `worker:` is an opaque label
|
|
113
|
+
that rides the order (same pass-through contract as `model`) for whatever
|
|
114
|
+
drives your workers to switch on.
|
|
115
|
+
|
|
116
|
+
```yaml
|
|
117
|
+
steps:
|
|
118
|
+
- name: tester
|
|
119
|
+
consumes: [reviewed_plan]
|
|
120
|
+
produces: [result]
|
|
121
|
+
worker: command # opaque to the engine; default is 'agent'
|
|
122
|
+
command: npm test # required when worker: command; never parsed or shelled out
|
|
123
|
+
spec: # optional opaque config for the dispatcher
|
|
124
|
+
timeout: 300
|
|
125
|
+
workdir: .
|
|
126
|
+
body: "" # not required for worker: command
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Two shape rules, both enforced at load time, everything else opaque:
|
|
130
|
+
|
|
131
|
+
- **`worker: command` requires `command:`.** A `command`-worker step with no
|
|
132
|
+
`command:` is a load-time `DefError` — the dispatcher would have nothing to
|
|
133
|
+
run.
|
|
134
|
+
- **`worker: agent` (explicit) requires a real `body:`.** Omitting `worker:`
|
|
135
|
+
still defaults to `'agent'` and still needs no body-shape check beyond
|
|
136
|
+
today's behavior — this rule only fires when a step *explicitly* writes
|
|
137
|
+
`worker: agent` and leaves `body:` empty, which is almost certainly a
|
|
138
|
+
mistake (an agent step with no prompt).
|
|
139
|
+
|
|
140
|
+
Any other `worker` value (`browser-automation`, `webhook`, your own label) is
|
|
141
|
+
fully opaque — no `body:`/`command:` requirement at all. A definition can
|
|
142
|
+
optionally declare `workers: [agent, command]` at the top level as a typo
|
|
143
|
+
guard; when present, `validateDef` rejects any step (or judge — see below)
|
|
144
|
+
whose effective worker (after the `agent` default) isn't in the list:
|
|
145
|
+
|
|
146
|
+
```yaml
|
|
147
|
+
name: my-workflow
|
|
148
|
+
workers: [agent, command] # optional allow-list; absent = any worker string accepted
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`command:` and `spec:` are opaque the same way `x:` is: `command` is
|
|
152
|
+
shape-checked as a string, `spec` as a plain map, and neither is ever read or
|
|
153
|
+
interpreted by the engine beyond that. All three (`worker`, `command`,
|
|
154
|
+
`spec`) ride through `buildOrder` onto the emitted `Order` untouched, exactly
|
|
155
|
+
like `model` and `workdir`. See [`docs/design.md` §27.4](design.md) for the
|
|
156
|
+
full contract.
|
|
157
|
+
|
|
101
158
|
## `produces:` vs `generates:`
|
|
102
159
|
|
|
103
160
|
A stem under `produces:` is expected to be consumed downstream — owenloop's lint warns
|
|
@@ -137,11 +194,24 @@ steps:
|
|
|
137
194
|
model: strong # optional, per-judge model tier
|
|
138
195
|
inputs: true # optional, default false — judge also
|
|
139
196
|
# reads the producer's inputs (question)
|
|
197
|
+
- name: ci-gate
|
|
198
|
+
body: "unused by a command judge, but still a required field" # every
|
|
199
|
+
# judge needs body/bodyFile regardless of worker
|
|
200
|
+
worker: command # judges can be deterministic too — same
|
|
201
|
+
command: scripts/ci-gate.sh # worker:/command: contract as a normal step
|
|
140
202
|
maxAttempts: 5 # producer's cap (default for every produce on this step)
|
|
141
203
|
# — also bounds judge-reject → rebuild loops; `report`
|
|
142
204
|
# above could set its own maxAttempts: to override it
|
|
143
205
|
```
|
|
144
206
|
|
|
207
|
+
A judge entry accepts the same `worker:`/`command:`/`spec:` fields as a
|
|
208
|
+
normal step (see [`worker:` above](#worker--declaring-the-executor)) — a
|
|
209
|
+
judge can be a deterministic check (a script's exit status) instead of an
|
|
210
|
+
LLM verdict. Note `body:`/`bodyFile:` is still required on every judge
|
|
211
|
+
regardless of `worker:` — that requirement is orthogonal to this feature and
|
|
212
|
+
applies even to a `worker: command` judge (the field just goes unread by a
|
|
213
|
+
non-agent dispatcher).
|
|
214
|
+
|
|
145
215
|
Each judge is a real step under the hood — it fires its own worker order
|
|
146
216
|
through the normal pipeline, with its own throttles (`cadence:`,
|
|
147
217
|
`maxRunsPerDay:`) and retry/timeout behavior. When `researcher` commits
|
package/docs/design.md
CHANGED
|
@@ -127,13 +127,26 @@ Held artifacts (`isHeld`, §20) also surface as `stalled: true` in
|
|
|
127
127
|
irreversible side effect and must not silently re-fire; a human must `retry` or
|
|
128
128
|
fix the upstream cause.
|
|
129
129
|
|
|
130
|
+
A `reject()` (judgment verdict) requires the target to already be a *built*
|
|
131
|
+
version — `green` or `submitted` — and refuses otherwise (a thrown Error): an
|
|
132
|
+
`owed` artifact has no build to render a verdict on (rejecting it would burn a
|
|
133
|
+
`judgmentRejects` toward the cap above with zero build attempts, a silent
|
|
134
|
+
freeze), and a `retracted` collection member is terminal (§11.3) — no firing
|
|
135
|
+
shape can ever rebuild it, so flipping it back to a live `rejected` debt would
|
|
136
|
+
wedge the instance.
|
|
137
|
+
|
|
130
138
|
Clearing a stall:
|
|
131
139
|
- **`retry`** — reset *both* counters to 0 and re-owe the artifact (optionally
|
|
132
140
|
with fresh guidance appended as a `retry` reason). The only path that resets
|
|
133
141
|
the counters. Also clears the held condition: a `retry` appends a `'retry'`
|
|
134
142
|
reason entry, so the last entry's `kind` is no longer `'invalidated-irreversible'`
|
|
135
|
-
and `isHeld` returns false.
|
|
136
|
-
|
|
143
|
+
and `isHeld` returns false. Requires the same consume-edge authority as
|
|
144
|
+
`reject`/`retract` (§4.1), and refuses a `retracted` target — retract is
|
|
145
|
+
final, and a bare collection element has no producer firing that could ever
|
|
146
|
+
rebuild it.
|
|
147
|
+
- **`retract`** — drop the member (collection elements), terminally. Requires
|
|
148
|
+
the same consume-edge authority as `reject` (§4.1): only a step that
|
|
149
|
+
consumes the member's stem (or human/engine) may retract it.
|
|
137
150
|
|
|
138
151
|
## §7 The forward cascade (level-triggered)
|
|
139
152
|
|
|
@@ -155,7 +168,10 @@ order-independent — re-running `settle()` on a healthy graph yields no ops.
|
|
|
155
168
|
|
|
156
169
|
- **§11.1 produce `src[]`** — the producer `emit`s an unknown number of bare
|
|
157
170
|
elements (`src[0]`, `src[1]`, …), then `seal`s. The seal is itself an artifact
|
|
158
|
-
(`sealOf = src`); the collection is "complete" when the seal is green.
|
|
171
|
+
(`sealOf = src`); the collection is "complete" when the seal is green. Once
|
|
172
|
+
the seal is green, a further `emit` on the same open lease is refused
|
|
173
|
+
(`sealed-rejected`) rather than silently growing a "complete" set; the lease
|
|
174
|
+
stays open so the run can still close.
|
|
159
175
|
- **§11.2 map `src[$i]`** — fan-out: one firing per element, `${INDEX}` bound.
|
|
160
176
|
- **§11.x reduce `src[*]`** — fan-in: see §3.
|
|
161
177
|
- **§11.x reduce with suffix `src[*].child`** — fan-in one level deeper: the
|
|
@@ -531,12 +547,12 @@ The engine ships `maintainCalls` in `engine.ts` — the engine-internal method t
|
|
|
531
547
|
Called at the top of every parent `tick` (outside any transaction), after `provideInput` on the parent (so a newly-supplied human input is immediately re-provided to any mapped child), and as a cascade-up prompt after child progress. For each `calls:` step in the parent def:
|
|
532
548
|
|
|
533
549
|
1. **Gate check**: `gateStems = Object.values(callsInputs)` (parent artifact names wired to child inputs). Gate is ready when every gate stem is green.
|
|
534
|
-
2. **Re-attach guard**: `findChildByParent(parentWf, callsPath)` — spawn only when no child exists (`undefined`). This prevents duplicate children across crashes and re-ticks.
|
|
535
|
-
3. **Spawn**: if gate is ready and no child, `createInstance(step.calls, { producedBy, provide: gateValues })`. The parent calls: artifact stays `owed`.
|
|
550
|
+
2. **Re-attach guard**: `findChildByParent(parentWf, callsPath)` — spawn only when no child exists (`undefined`). This prevents duplicate children across crashes and re-ticks. A second guard sits alongside it (§23.6.7 F2): if no child exists AND the parent calls artifact is already `rejected` on a schema refusal, skip the spawn attempt entirely while the gate stems' fingerprint is unchanged from the one stamped at refusal time — a moved gate is the only thing worth retrying against.
|
|
551
|
+
3. **Spawn**: if gate is ready and no child, `createInstance(step.calls, { producedBy, provide: gateValues })`. The parent calls: artifact stays `owed`. §23.6.7 (F2): a child input-schema refusal here is caught narrowly (`SchemaRefusalError` only — a genuine bug still throws) and recorded as a debt on the parent calls artifact instead of crashing the tick.
|
|
536
552
|
4. **Outcome read**: read the child's declared `outputs:` artifact (exactly one, validated at load time). If it is green, machine-green the parent's calls: artifact.
|
|
537
|
-
5. **Re-provide**: for each `callsInputs` mapping, if the parent's value differs (deep-equal) from what the child holds, `provideInput(child, inputName, newValue)`. The child re-runs internally.
|
|
538
|
-
6. **Machine-green**: set parent calls: artifact to `acceptance: 'green'`, `version + 1`, `value = child outcome value`, `fingerprint = computeFingerprint(parentArts, gateStems)
|
|
539
|
-
7. **Re-arm on child working**: if the child's outcome is no longer green (e.g. re-provide re-armed it) but the parent calls: artifact is green, re-arm the parent calls: artifact to `owed`. This handles gate re-arm correctly even though `deliver` step has `consumes: []` (the pure cascade cannot detect fingerprint mismatch for calls: steps).
|
|
553
|
+
5. **Re-provide**: for each `callsInputs` mapping, if the parent's value differs (deep-equal) from what the child holds, `provideInput(child, inputName, newValue)`. The child re-runs internally. §23.6.7 (F2): same narrow schema-refusal handling as spawn — a child-illegal re-provided value becomes a debt on the parent calls artifact, not a thrown cascade.
|
|
554
|
+
6. **Machine-green**: set parent calls: artifact to `acceptance: 'green'`, `version + 1`, `value = child outcome value`, `fingerprint = computeFingerprint(parentArts, gateStems) plus the child-outcome version pin` (§23.6.8, F4) — but only when the child outcome's version has moved past whatever version is currently pinned on the parent artifact. Then `settle(parentWf)` so downstream (teardown) fires. Do NOT set `terminal` — the calls: artifact must be re-armable if gate inputs move.
|
|
555
|
+
7. **Re-arm on child working**: if the child's outcome is no longer green (e.g. re-provide re-armed it) but the parent calls: artifact is green, re-arm the parent calls: artifact to `owed`. This handles gate re-arm correctly even though `deliver` step has `consumes: []` (the pure cascade cannot detect fingerprint mismatch for calls: steps). This re-arm is unconditional on the pin — the pin only gates re-greening, never gates reopening to `owed`.
|
|
540
556
|
|
|
541
557
|
#### §23.6.2 Cascade-up prompt
|
|
542
558
|
|
|
@@ -552,12 +568,50 @@ A child that greens its declared outcome with a status-bearing value (e.g. `{sta
|
|
|
552
568
|
|
|
553
569
|
#### §23.6.5 Gate fingerprint and re-arm
|
|
554
570
|
|
|
555
|
-
The machine-green fingerprint covers
|
|
571
|
+
The machine-green fingerprint covers `gateStems` (the parent artifacts wired into the child via `callsInputs`) plus, as of F4 (§23.6.8), a reserved `__child_outcome_version__` key pinning the child outcome's version. The child-outcome re-green trigger itself is still handled by `maintainCalls` value comparison (`deepEqual`), not by the pure forward cascade (`fingerprintMatches`) — `eligibleFirings`/`settle`'s cascade never looks at a calls: artifact's fingerprint to decide re-arming, since a calls: step declares `consumes: []`.
|
|
556
572
|
|
|
557
573
|
#### §23.6.6 Transaction composition
|
|
558
574
|
|
|
559
575
|
`maintainCalls` runs OUTSIDE any open `store.tx()`. Each mutating action (spawn via `createInstance`, re-provide via `provideInput`, machine-green) opens its own `store.tx()`. No nested transactions — node:sqlite does not support nested `BEGIN IMMEDIATE`.
|
|
560
576
|
|
|
577
|
+
#### §23.6.7 F2 — child input-schema refusal is a debt, not a thrown tick
|
|
578
|
+
|
|
579
|
+
A `calls:` step wires parent artifact values into the child's inputs (`callsInputs`), but the parent's own schema for that artifact (if any) can be looser than — or entirely absent from — the child's declared input schema. Before this fix, `createInstance`'s seed-provide validation and `provideInput`'s validation threw a bare `Error` on a schema mismatch; because `maintainCalls` runs at the top of every `tick()` with no catch, one such value made every subsequent `tick(parent)` throw — a permanent crash loop with no debt or stall visible in `status()`.
|
|
580
|
+
|
|
581
|
+
The fix: `createInstance`/`provideInput` now throw a dedicated `SchemaRefusalError` (carrying the offending input name and schema issues) instead of a bare `Error` on a schema mismatch. `maintainCalls`'s STEP 3 (spawn) and STEP 5 (re-provide) each catch `SchemaRefusalError` narrowly — any other error still propagates, since that's a genuine bug, not an expected refusal. On catch, the parent calls artifact is recorded as a debt with the same shape `green()` uses for its own schema-reject branch: `acceptance: 'rejected'`, `schemaRejects + 1`, a `validation`-kind reasons entry naming the child input and the schema issues. The tick then proceeds instead of throwing.
|
|
582
|
+
|
|
583
|
+
While the parent calls artifact sits `rejected` on a schema refusal and the gate stems' fingerprint (stamped at refusal time) is unchanged, `maintainCalls` does not re-attempt the spawn (STEP 2's guard) nor re-green from a rejected state (STEP 6 short-circuits on `acceptance === 'rejected'`) — re-trying the same illegal value every tick would just refuse again. A human `retry` clears the counter and re-arms to `owed`; once the parent value is fixed (the gate's fingerprint moves), the next tick spawns/re-provides normally.
|
|
584
|
+
|
|
585
|
+
The human's own `provideInput` call on the PARENT's own input artifact is unaffected — that validation happens against the PARENT's own schema, inside `provideInput`'s own transaction, before the calls: cascade (which runs `provideInput` again, this time against the CHILD) is ever reached. A parent-illegal value is refused (as before); a parent-legal-but-child-illegal value commits at the parent and surfaces as a debt on the calls: artifact per this section.
|
|
586
|
+
|
|
587
|
+
#### §23.6.8 F4 — reject on a calls artifact propagates to the child; the mirror is version-pinned
|
|
588
|
+
|
|
589
|
+
Before this fix, a consumer's `reject()` (or a human `skip()`) on a `calls:`-produced artifact was silently reversed on the very next tick: `maintainCalls`'s STEP 6 re-greens whenever the child outcome is green and the parent isn't already green-with-the-same-value, with no awareness that a verdict had landed in between. A deterministic consumer reject would inflate `judgmentRejects` on the parent artifact forever without ever reaching the child that actually needs to change — a livelock.
|
|
590
|
+
|
|
591
|
+
**Reject propagation.** `reject(parentWf, callsPath, by, text)` detects a `calls:`-produced artifact (the producing step declares `calls:`) and forwards the verdict instead of running the normal producer-invalidation path:
|
|
592
|
+
|
|
593
|
+
- Resolve the child via `store.findChildByParent(parentWf, callsPath)`. If no child was ever spawned, refuse the reject (`cannot reject '<path>': no child instance has been spawned yet`) — consistent with the existing verb-guard rule that a verdict needs a built version.
|
|
594
|
+
- The CHILD's declared outcome artifact goes `acceptance: 'rejected'`, `judgmentRejects + 1`, with a reasons entry carrying the verdict text and `by: 'parent:<by>'` — the `parent:` prefix marks the entry as an engine-forwarded verdict, not a direct one, in the child's own audit thread. The forward is engine-internal: authority was already checked against the PARENT def (`assertAuthority` runs before the calls-detection branch); the child's own `assertAuthority` is never consulted for this call.
|
|
595
|
+
- The PARENT calls artifact is reopened to `owed` (never left `rejected`) with a `reopen`/`structural` reasons entry, and its fingerprint is stamped with the rejected child outcome's version (the pin — §below). "Owed, waiting on the child to rebuild" is the honest status, and it lets STEP 6's existing mirror logic pick the new value up unmodified once the child recovers.
|
|
596
|
+
- The child's own producer re-arms on the normal knock-back loop — the verdict text rides the child producer's `owes` thread on its next firing, exactly like any other rejected artifact. Driving that re-arm requires ticking the CHILD instance (see the sweeping note below); `rejectCallsArtifact` also prompts `maintainCalls(parentWf)` so the parent's own `owed`/pin state is visible immediately, but it does not — and cannot, from the parent side alone — cause the child's producer step to fire.
|
|
597
|
+
- If the child keeps failing, `judgmentRejects` accrues on the CHILD artifact and the child stalls at its own `maxAttempts` — the liveness bound lands on the instance actually doing the work, not on the parent's pass-through artifact.
|
|
598
|
+
|
|
599
|
+
**Version-pinned mirror.** A `calls:` step declares `consumes: []`, so the parent artifact's own fingerprint machinery never sees its real input — the child outcome, which lives in another instance entirely. The fix threads a synthetic key, `Engine.CHILD_OUTCOME_PIN_KEY` (`'__child_outcome_version__'`), through the parent calls artifact's `fingerprint` map alongside the gate stems, holding the child outcome version the parent artifact currently rests on:
|
|
600
|
+
|
|
601
|
+
- STEP 6 stamps this pin whenever it machine-greens (to the child outcome's version at that moment), and only machine-greens at all when the child outcome's version has moved **past** the currently-stamped pin (or no pin is stamped yet).
|
|
602
|
+
- The reject-propagation path above stamps the same pin (to the just-rejected child outcome's version) when it reopens the parent to `owed`.
|
|
603
|
+
- `skip()` stamps the same pin when skipping a `calls:`-produced artifact (detected the same way as `reject()`, by checking `producingStep.calls`) — since `skip`'s normal fingerprint (`requiredInputs`-driven) is `consumes: []`-empty here too.
|
|
604
|
+
- All three sites compute "what child-outcome version does this rest on" through one helper, `Engine.childOutcomePin(parentWf, callsPath)`, so the pin logic lives in exactly one place.
|
|
605
|
+
|
|
606
|
+
This gives the two orderings the settled design calls for:
|
|
607
|
+
|
|
608
|
+
- **Order A** — a human skips the green calls artifact having seen child result v3; the child stays at v3. The pin (v3) matches the child's current version, so `pastPin` is false and STEP 6 never re-greens: the skip survives arbitrary ticks. The machine never overrides a decision made on current evidence.
|
|
609
|
+
- **Order B** — the same skip is pinned to v3, but the gate later moves, the child is re-provided, and it rebuilds to v4. Now `childOutcomeArt.version (4) > pinnedVersion (3)`, so `pastPin` is true: STEP 6 re-arms and mirrors the v4 value. A stale, months-old skip cannot permanently gag a fresh child result.
|
|
610
|
+
|
|
611
|
+
The `M2B-REARM` branch (§23.6.1 step 7 — child un-greened while parent stays green) is unaffected by the pin: it only checks `isGreen(childOutcomeArt)`, so it still reopens the parent to `owed` regardless of what's pinned. The pin governs only the re-green transition (`owed`/`rejected` → `green`), never the green → `owed` reopen.
|
|
612
|
+
|
|
613
|
+
**Sweeping note.** A propagated reject re-arms work in the CHILD instance, not the parent — `tick(parentWf)` re-runs `maintainCalls` (the mirror), but the child's own re-firing needs `tick(childWf)`. A driver/conductor that only ticks parents (never sweeping children) will see the parent sit `owed` indefinitely with no order ever appearing, because the actual work order is a child-instance concern. Drivers are expected to sweep every live instance (parent and child alike) — `store.listChildrenByParent`/`findChildByParent` give the reverse index needed to discover children from a parent id. The propagated reject is visible for such a sweep via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`), independent of whether the sweep follows `producedBy` links or just iterates every known workflow id.
|
|
614
|
+
|
|
561
615
|
## §24 Artifact judges (`judges:`)
|
|
562
616
|
|
|
563
617
|
A `produces` entry can declare one or more **judges**: deterministic
|
|
@@ -690,6 +744,13 @@ verbs with no new CLI surface:
|
|
|
690
744
|
so a human clearing a judge-reject stall doesn't leave a stale partial
|
|
691
745
|
ledger for the rebuild to inherit.
|
|
692
746
|
|
|
747
|
+
A human bypass's scope is deliberately narrow: it skips the judge ledger and
|
|
748
|
+
the lease/CAS machinery, but not the artifact's declared output schema — a
|
|
749
|
+
human `green` on a produce with a `schema:` is validated exactly like a
|
|
750
|
+
producer commit (§18), refused with a thrown Error (no version bump, no
|
|
751
|
+
schemaRejects bump — there is no retry loop to protect on this path) rather
|
|
752
|
+
than silently landing a value downstream consumers assume is schema-valid.
|
|
753
|
+
|
|
693
754
|
### §24.7 `CommitResult['outcome']` — three success outcomes, two failure
|
|
694
755
|
|
|
695
756
|
`green()`'s result vocabulary grows by two, both **successes**:
|
|
@@ -887,21 +948,39 @@ sibling's auto-skip.
|
|
|
887
948
|
Auto-skip is implemented purely inside `maintainDecisions` (model.ts) — the
|
|
888
949
|
same pure, level-triggered fixpoint function §11.8/§12.3 already uses for
|
|
889
950
|
reject/retract/skip/rearm/pin/arm. For every `exactlyOne`/`atMostOne` group
|
|
890
|
-
with exactly one `green` member, every `owed
|
|
891
|
-
op with `rejectKind: 'exclusive'` (a new `RejectKind`,
|
|
892
|
-
`structural` / `validation` / `invalidated-irreversible`
|
|
893
|
-
accounting category, distinct from the skip's `ReasonAction`,
|
|
894
|
-
`'skip'`). Because `Engine.settle()` runs this cascade to a full
|
|
895
|
-
synchronously at the end of every `green()` call, the auto-skip is
|
|
896
|
-
visible by the time the winning `green()` call returns — a caller
|
|
897
|
-
observes an intermediate state where the winner is green but the loser
|
|
898
|
-
still `owed`.
|
|
951
|
+
with exactly one `green` member, every `owed`, `rejected`, **or `submitted`**
|
|
952
|
+
sibling gets a `skip` op with `rejectKind: 'exclusive'` (a new `RejectKind`,
|
|
953
|
+
alongside `judgment` / `structural` / `validation` / `invalidated-irreversible`
|
|
954
|
+
— a liveness-accounting category, distinct from the skip's `ReasonAction`,
|
|
955
|
+
which stays `'skip'`). Because `Engine.settle()` runs this cascade to a full
|
|
956
|
+
fixpoint synchronously at the end of every `green()` call, the auto-skip is
|
|
957
|
+
already visible by the time the winning `green()` call returns — a caller
|
|
958
|
+
never observes an intermediate state where the winner is green but the loser
|
|
959
|
+
is still `owed` or `submitted`.
|
|
960
|
+
|
|
961
|
+
A `submitted` sibling is an OUTSTANDING state (§15): left uncovered by this
|
|
962
|
+
cascade, a judged group member that submits before its sibling wins can never
|
|
963
|
+
be settled — its judge order is correctly suppressed by §26.5's eligibility
|
|
964
|
+
pre-filter, but the artifact itself just sits `submitted` forever, wedging the
|
|
965
|
+
instance out of `done: true` permanently. Covering `submitted` here closes
|
|
966
|
+
that gap. Skipping a `submitted` sibling also **clears its `approvals`
|
|
967
|
+
ledger** (mirrors the cascade-reject approvals-clear, §24 §4.3): a partial
|
|
968
|
+
judge sign-off recorded before the skip must never leak onto a later
|
|
969
|
+
resubmission if the winning sibling is later un-greened and the branch
|
|
970
|
+
revives — `Engine.applyOp`'s `'skip'` branch and its pure in-memory twin,
|
|
971
|
+
`applyOpInMemory`'s `'skip'` branch (the checker's own reimplementation, since
|
|
972
|
+
`settleInMemory` calls `maintainDecisions` directly and inherits the cascade
|
|
973
|
+
fix for free, but `applyOpInMemory` mirrors the engine's mutation 1:1 and
|
|
974
|
+
needs the same approvals-clear applied independently), both clear `approvals`
|
|
975
|
+
on the skipped artifact whenever its prior acceptance was `submitted`.
|
|
899
976
|
|
|
900
977
|
Re-arming an auto-skipped sibling needs zero group-specific code: it goes
|
|
901
978
|
through the exact same generic skip-re-arm mechanism (fingerprint-keyed,
|
|
902
979
|
§7) that already re-arms a manually-skipped branch when its upstream inputs
|
|
903
980
|
move. `rejectKind: 'exclusive'` only changes how the artifact is
|
|
904
|
-
*classified* for liveness accounting; it does not change how it re-arms
|
|
981
|
+
*classified* for liveness accounting; it does not change how it re-arms — and
|
|
982
|
+
the cleared approvals ledger travels with it, so a re-armed (or freshly
|
|
983
|
+
re-produced) sibling always starts its judge ledger from empty.
|
|
905
984
|
|
|
906
985
|
### §26.3 Grammar and validation
|
|
907
986
|
|
|
@@ -946,16 +1025,19 @@ sibling in this stem's group already sit green?" Every WORKER-firing branch
|
|
|
946
1025
|
output path that is currently group-blocked, so the automatic sweep (`tick`)
|
|
947
1026
|
never dispatches an order — in particular, never spawns a judge order for a
|
|
948
1027
|
`submitted` sibling — that `groupCasCheck` is guaranteed to refuse the moment
|
|
949
|
-
it tries to land green.
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
firing
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
1028
|
+
it tries to land green. Historically this pre-filter was the only defense for
|
|
1029
|
+
a `submitted` group loser: §26.2's cascade covered only `owed`/`rejected`
|
|
1030
|
+
siblings, so a `submitted` member just sat there — its judge order suppressed
|
|
1031
|
+
from firing again, but the artifact itself never settled, wedging the
|
|
1032
|
+
instance out of `done: true` forever (a liveness bug, not merely wasted
|
|
1033
|
+
spawns). §26.2 now also auto-skips a `submitted` loser in the same settle as
|
|
1034
|
+
the winner's commit, so this eligibility pre-filter and that cascade converge:
|
|
1035
|
+
a `submitted` sibling is skipped essentially as soon as it stops being newly
|
|
1036
|
+
eligible (`test/groups.test.ts` scenario (f3)). `groupCasCheck` itself stays
|
|
1037
|
+
load-bearing for a judge order that was already claimed (in flight) before the
|
|
1038
|
+
winner landed — the pre-filter and the cascade both only act going forward, so
|
|
1039
|
+
scenario (f) still exercises the commit-time refusal against that in-flight
|
|
1040
|
+
race.
|
|
959
1041
|
|
|
960
1042
|
Suppression applies to the automatic sweep only. A human `retry` re-arms the
|
|
961
1043
|
named artifact directly and does not itself run `eligibleFirings` — but the
|
|
@@ -1098,6 +1180,88 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
|
|
|
1098
1180
|
opaque); a child definition's own top-level `x:` stays on the child def and
|
|
1099
1181
|
is not merged into the parent's.
|
|
1100
1182
|
|
|
1183
|
+
### §27.4 `worker:`/`command:`/`spec:` — declaring the executor
|
|
1184
|
+
|
|
1185
|
+
`x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
|
|
1186
|
+
`worker:` is a narrower, purpose-built field for one specific job: telling
|
|
1187
|
+
whatever dispatches orders *which kind* of executor a step's order is for. It
|
|
1188
|
+
follows the same opaque-passthrough contract as `model` — the engine never
|
|
1189
|
+
interprets it, only carries it — but unlike `model` (a free-form quality
|
|
1190
|
+
hint) and unlike `x:` (fully unvalidated contents), `worker:` gets two narrow,
|
|
1191
|
+
hard-coded shape rules, because the two most common worker types have a
|
|
1192
|
+
structural precondition the engine can cheaply catch at load time instead of
|
|
1193
|
+
letting it surface as a confusing runtime stall.
|
|
1194
|
+
|
|
1195
|
+
**The contract, four clauses:**
|
|
1196
|
+
|
|
1197
|
+
1. **Default is `'agent'`, and that default is silent.** A step (or judge)
|
|
1198
|
+
that omits `worker:` entirely behaves exactly as it did before this
|
|
1199
|
+
feature existed — every def in this repo predating `worker:` is
|
|
1200
|
+
unaffected, byte for byte. The default is applied at validation and
|
|
1201
|
+
engine-order-building time, never written back into the parsed def.
|
|
1202
|
+
2. **`worker: command` requires `command:`.** A step (or judge) whose
|
|
1203
|
+
effective worker is `'command'` and carries no `command:` is a load-time
|
|
1204
|
+
`DefError`: `` step '<name>' has worker 'command' but no command: ``. Any
|
|
1205
|
+
other worker string has no such requirement — `command:` is only ever
|
|
1206
|
+
validated when the worker is literally `'command'`.
|
|
1207
|
+
3. **`worker: agent` (explicit) requires a non-empty `body:`.** This check is
|
|
1208
|
+
deliberately scoped to an *explicit* `worker: agent`, not the *defaulted*
|
|
1209
|
+
value — i.e. `validateDef` checks `l.worker === 'agent'`, never
|
|
1210
|
+
`(l.worker ?? 'agent') === 'agent'`. That distinction matters: plenty of
|
|
1211
|
+
existing fixtures and generator-only steps rely on `buildStep`'s
|
|
1212
|
+
empty-body default and never write `worker:` at all. Checking the
|
|
1213
|
+
defaulted value would retroactively break every one of them. Checking
|
|
1214
|
+
only the explicit form catches the actual mistake this rule exists for —
|
|
1215
|
+
someone opts into `worker: agent` on purpose and forgets the prompt —
|
|
1216
|
+
without touching a single pre-existing def.
|
|
1217
|
+
4. **`command:` and `spec:` are otherwise opaque.** `command` is
|
|
1218
|
+
shape-checked as a string (`asString`); `spec` is shape-checked as a plain
|
|
1219
|
+
map (`asExtension` — the same helper `x:` uses, reused verbatim, no new
|
|
1220
|
+
helper). Neither's *contents* are read, parsed, or interpreted by the
|
|
1221
|
+
engine. `spec` exists for cases where `command` alone isn't enough
|
|
1222
|
+
configuration (a timeout, a working directory hint, environment
|
|
1223
|
+
overrides) without inventing a new field per knob — the same "shape, not
|
|
1224
|
+
contents" philosophy as `x:`, just scoped to one step instead of the
|
|
1225
|
+
whole def.
|
|
1226
|
+
|
|
1227
|
+
**The optional `workers:` allow-list.** A definition can declare `workers:
|
|
1228
|
+
[agent, command, …]` at the top level — a typo guard, nothing more. When
|
|
1229
|
+
present, `validateDef` rejects any step or judge whose *effective* worker
|
|
1230
|
+
(after the `?? 'agent'` default is applied) isn't in the list. This runs
|
|
1231
|
+
**after** the default, deliberately: a def that declares `workers: [command]`
|
|
1232
|
+
(excluding `'agent'` on purpose) still fails a step that omits `worker:`
|
|
1233
|
+
entirely, because that step's effective worker is `'agent'` and `'agent'`
|
|
1234
|
+
isn't in the list. This is the intended behavior — once a def opts into the
|
|
1235
|
+
allow-list, it's exhaustive, and a step relying on the silent default doesn't
|
|
1236
|
+
get a free pass around it. A def with no `workers:` key accepts any worker
|
|
1237
|
+
string; there is no engine-wide registry of valid worker types to check
|
|
1238
|
+
against.
|
|
1239
|
+
|
|
1240
|
+
**Pass-through.** `worker`, `command`, and `spec` all ride `buildOrder` onto
|
|
1241
|
+
the emitted `Order` untouched — `Order.worker`, `Order.command`, `Order.spec`
|
|
1242
|
+
— the same pass-through contract as `Order.model` and `Order.x`. A step that
|
|
1243
|
+
never sets them emits an order with all three fields absent, identical to
|
|
1244
|
+
before this feature existed.
|
|
1245
|
+
|
|
1246
|
+
**Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
|
|
1247
|
+
each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
|
|
1248
|
+
`worker:`/`command:`/`spec:` and having the exact same `validateDef` rules
|
|
1249
|
+
apply to it isn't a separate code path, it's the same rules running against
|
|
1250
|
+
an already-existing synthesized step. A judge can therefore be a
|
|
1251
|
+
deterministic check (a script's exit code) instead of an LLM verdict, without
|
|
1252
|
+
any new validation logic. Note the pre-existing, orthogonal judge
|
|
1253
|
+
requirement — every judge needs `body:` or `bodyFile:` regardless of
|
|
1254
|
+
`worker:` — still applies; a `worker: command` judge still declares a
|
|
1255
|
+
`body:`, it's simply unread by a non-agent dispatcher.
|
|
1256
|
+
|
|
1257
|
+
**Scope notes**, mirroring §27.3's: `worker`/`command`/`spec` are additive
|
|
1258
|
+
and inert — a definition that never sets any of the three is unchanged in
|
|
1259
|
+
behavior and in `hashDef` terms. They live on the same two authored,
|
|
1260
|
+
engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
|
|
1261
|
+
participate in §28 pinning the same way (snapshotted at `createInstance`,
|
|
1262
|
+
and a later edit is real `hashDef` drift), and pass through `expandIncludes`
|
|
1263
|
+
prefixing untouched (there are no stems inside them to rewrite).
|
|
1264
|
+
|
|
1101
1265
|
## §28 Instance-to-definition pinning
|
|
1102
1266
|
|
|
1103
1267
|
Every prior section treats a workflow *definition* as the stable thing and a
|
package/docs/embedding.md
CHANGED
|
@@ -75,9 +75,34 @@ const status = engine.status(wf); // { done, debts, eligible, blocked, inFligh
|
|
|
75
75
|
|
|
76
76
|
Each `order` is self-contained: `prompt`, `consumes` (the captured green
|
|
77
77
|
inputs), `owes` (the owed outputs + their accumulated reason threads), plus
|
|
78
|
-
`inputs`/`outputs`/`model`. A consumer rejecting an
|
|
79
|
-
`engine.reject(wf, path, by, text)`; the forward
|
|
80
|
-
behave exactly as they do under the CLI, because
|
|
78
|
+
`inputs`/`outputs`/`model`/`worker`/`command`/`spec`. A consumer rejecting an
|
|
79
|
+
upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
|
|
80
|
+
cascade and stall liveness behave exactly as they do under the CLI, because
|
|
81
|
+
it's the same engine.
|
|
82
|
+
|
|
83
|
+
`order.worker` is where dispatch-by-executor-type earns its keep in an
|
|
84
|
+
embedder: rather than every order going to the same LLM-driving `runYourWorker`,
|
|
85
|
+
branch on it before deciding how to run the order.
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
for (const order of orders) {
|
|
89
|
+
const result =
|
|
90
|
+
order.worker === 'command'
|
|
91
|
+
? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
|
|
92
|
+
: await runYourAgent(order); // default / worker: 'agent' / anything else you handle the same way
|
|
93
|
+
|
|
94
|
+
const commit = engine.green(wf, order.run, order.outputs[0], result);
|
|
95
|
+
engine.close(wf, order.run);
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`worker`/`command`/`spec` are all optional and opaque — the engine only
|
|
100
|
+
shape-checks them at load time (`command` a string, `spec` a plain map) and
|
|
101
|
+
never reads their contents itself. `order.worker` is `undefined` when the
|
|
102
|
+
step never set it (today's default, unaffected by this feature). See
|
|
103
|
+
[`docs/design.md` §27.4](design.md) for the full contract and
|
|
104
|
+
[`docs/authoring.md`](authoring.md#worker--declaring-the-executor) for how to
|
|
105
|
+
declare it on a step.
|
|
81
106
|
|
|
82
107
|
A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
|
|
83
108
|
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Declarative executor dispatch — demonstrates `worker:`/`command:`/`spec:`
|
|
2
|
+
# (§27.4 of docs/design.md).
|
|
3
|
+
#
|
|
4
|
+
# The engine never executes anything; `worker:` just labels which kind of
|
|
5
|
+
# executor a step's order is for, so the same def can mix an LLM-driven step
|
|
6
|
+
# with a deterministic, non-LLM one. `planner` omits `worker:` entirely (the
|
|
7
|
+
# default, unaffected `'agent'` path — every existing def in this repo stays
|
|
8
|
+
# exactly like this). `tester` declares `worker: command` with a real
|
|
9
|
+
# `command:` — a runner dispatching this order runs the command instead of an
|
|
10
|
+
# agent, no judgment involved. `tester`'s `result` produce is gated by a
|
|
11
|
+
# command judge (`ci-gate`): judges can be deterministic too, not just
|
|
12
|
+
# LLM-based — this one runs a check script and approves/rejects on exit status.
|
|
13
|
+
#
|
|
14
|
+
# Drive it:
|
|
15
|
+
# wf=$(owenloop create command-worker --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
|
|
16
|
+
# owenloop tick $wf # -> order for `planner` (worker: agent, default)
|
|
17
|
+
# owenloop green $wf <run> reviewed_plan --value '{"approved":true}'
|
|
18
|
+
# owenloop tick $wf # -> order for `tester` (worker: command)
|
|
19
|
+
# owenloop green $wf <run> result --value '{"exitCode":0}'
|
|
20
|
+
# owenloop tick $wf # -> order for the `ci-gate` judge (worker: command)
|
|
21
|
+
# owenloop green $wf <judge-run> result --value '{}' # judge approves -> result goes green
|
|
22
|
+
|
|
23
|
+
name: command-worker
|
|
24
|
+
title: Command-dispatched worker step
|
|
25
|
+
description: Mixes an agent step with a deterministic command step and a command judge.
|
|
26
|
+
|
|
27
|
+
inputs:
|
|
28
|
+
- name: plan
|
|
29
|
+
seedOwed: true # required: supply with --provide or `owenloop provide`
|
|
30
|
+
|
|
31
|
+
steps:
|
|
32
|
+
- name: planner
|
|
33
|
+
consumes: [plan]
|
|
34
|
+
produces: [reviewed_plan]
|
|
35
|
+
# worker: omitted here on purpose — the default/common case, completely
|
|
36
|
+
# unaffected by this feature. This step dispatches to an agent exactly
|
|
37
|
+
# like every step in every other bundled example.
|
|
38
|
+
body: |
|
|
39
|
+
Workflow ${WORKFLOW}, run ${RUN}.
|
|
40
|
+
Read `plan` and sanity-check it. Green `reviewed_plan` with your call.
|
|
41
|
+
|
|
42
|
+
- name: tester
|
|
43
|
+
consumes: [reviewed_plan]
|
|
44
|
+
produces:
|
|
45
|
+
- name: result
|
|
46
|
+
judges:
|
|
47
|
+
- name: ci-gate
|
|
48
|
+
body: "unused by a command judge, but still a required field (§24)" # not read; a command judge acts on exit status, not a prompt
|
|
49
|
+
worker: command # deterministic — no judgment, just run the script
|
|
50
|
+
command: scripts/ci-gate.sh # exit 0 approves, non-zero rejects with its output
|
|
51
|
+
worker: command # deterministic — no judgment, just run the script
|
|
52
|
+
command: npm test # opaque to the engine; the dispatcher runs this
|
|
53
|
+
spec: # opaque config for the dispatcher; engine never reads it
|
|
54
|
+
timeout: 300
|
|
55
|
+
workdir: .
|
|
56
|
+
body: "" # not required for worker: command (no agent prompt)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "owenloop",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "typicalday",
|