owenloop 0.4.0 → 0.5.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.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
package/docs/design.md
CHANGED
|
@@ -663,7 +663,7 @@ The `M2B-REARM` branch (§23.6.1 step 7 — child un-greened while parent stays
|
|
|
663
663
|
- **Aggregation.** Child orders are concatenated onto the parent's; `reaped` sums; `dueAt` takes the minimum across the tree so the caller's next-wake is the earliest across all levels. Each folded `DeferredFiring` carries a `workflow` field naming the instance it belongs to — **absent means the ticked root, present means a descendant** — so a caller can still tell which instance a deferral came from. The single `now` is threaded through the whole descent, so a reap TTL that trips at the parent's clock trips consistently for children in the same sweep.
|
|
664
664
|
- **Opt-out.** `tick(parentWf, { deep: false })` (CLI `--shallow`) ticks only that one instance — no descent, orders all carry the root's `workflow`. Use it to drive a single instance deliberately (tests, targeted retries); the default deep tick is what production drivers want.
|
|
665
665
|
|
|
666
|
-
**Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a
|
|
666
|
+
**Status child-summary.** `status(parentWf)` enriches each `calls:`-debt entry with a `child: ChildStatusSummary` (`{ workflow, def, done, stalled, debts }`) when a child has been spawned for that step. `stalled` is true when the child (or, recursively, a grandchild on an unpaid `calls:` path) has any stalled debt — a worker that hit `maxAttempts` with no green outcome. This lets a Shift see, from the parent alone, that a `calls:` debt is blocked on a stuck child without separately walking into the child's own `status`. Like `failedRuns`/`attempts`, the field is engine-populated cross-instance state; `model.ts`'s pure single-instance `workflowStatus` never sets it.
|
|
667
667
|
|
|
668
668
|
**Discovering children directly.** A driver can still enumerate children itself — `store.listChildrenByParent`/`findChildByParent` give the reverse index from a parent id — and a propagated reject remains visible via the CHILD's own `status(childWf).debts` (the rejected outcome artifact appears there with `acceptance: 'rejected'`). But with deep tick as the default, a driver that sweeps only roots already reaches all live descendants; explicit child enumeration is for inspection and for the `--shallow` single-instance path, not a requirement for liveness.
|
|
669
669
|
|
|
@@ -875,7 +875,7 @@ steps:
|
|
|
875
875
|
```
|
|
876
876
|
|
|
877
877
|
- `name:` — required; keys the sign-off ledger and the audit trail.
|
|
878
|
-
- `body:` / `bodyFile:` — the judge
|
|
878
|
+
- `body:` / `bodyFile:` — the judge Step Agent's prompt (exactly one required,
|
|
879
879
|
mutually exclusive, same rule as step bodies). `bodyFile` is resolved
|
|
880
880
|
against the workflow's base directory and read eagerly at def-load.
|
|
881
881
|
- `model:` — optional model override for that judge's order. Opaque to the
|
|
@@ -919,12 +919,12 @@ left as a known, accepted limitation — see the doc comment on `reject()` in
|
|
|
919
919
|
`src/engine.ts`.
|
|
920
920
|
|
|
921
921
|
**Mitigations, for operators running judges with slow or expensive verdict
|
|
922
|
-
|
|
922
|
+
Step Agents:**
|
|
923
923
|
|
|
924
924
|
- Keep `judges: <judgedStem>` steps at `parallel: 1` (the default) so there
|
|
925
925
|
is only ever one live run of a given judge step at a time. This alone
|
|
926
926
|
removes the "two different runs" precondition for the race.
|
|
927
|
-
- Set a generous `reapTtl:` on judge steps whose verdict
|
|
927
|
+
- Set a generous `reapTtl:` on judge steps whose verdict Step Agent is slow —
|
|
928
928
|
reaping is what creates the zombie in the first place (§24.5); a judge
|
|
929
929
|
that is legitimately still working should not be reaped out from under
|
|
930
930
|
itself. A TTL sized to the judge's real worst-case latency, rather than
|
|
@@ -933,10 +933,71 @@ agents:**
|
|
|
933
933
|
## §25 The model checker (`owenloop check`) — scope
|
|
934
934
|
|
|
935
935
|
`owenloop check <def>` (see `cli.ts` usage) runs a bounded reachability
|
|
936
|
-
search over `applyOutcome` transitions in `model.ts`, looking for
|
|
937
|
-
deadlocks, stuck artifacts, dead steps, and violations of any
|
|
938
|
-
invariants. It is a static analysis of a workflow definition's
|
|
939
|
-
simulation of a running instance.
|
|
936
|
+
search over `applyOutcome` transitions in `model.ts`, looking for stall
|
|
937
|
+
states, true deadlocks, stuck artifacts, dead steps, and violations of any
|
|
938
|
+
declared invariants. It is a static analysis of a workflow definition's
|
|
939
|
+
shape, not a simulation of a running instance.
|
|
940
|
+
|
|
941
|
+
**Stall states vs true deadlocks.** A reachable, non-done state with zero
|
|
942
|
+
eligible firings is classified into exactly ONE of two mutually exclusive
|
|
943
|
+
buckets, by recomputing eligibility as if every freeze were lifted
|
|
944
|
+
(`eligibleFirings(def, arts, undefined, { ignoreFreeze: true })` — "unlimited
|
|
945
|
+
attempts," i.e. what a human `retry` grants):
|
|
946
|
+
- **stall state** (`report.stallStates`) — the recompute yields >= 1 firing:
|
|
947
|
+
the state's ONLY blocker is a frozen/stalled debt — `maxAttempts` reached
|
|
948
|
+
(`isStalled`, §6), `maxSchemaFailures` reached (`isSchemaStalled`, §6/§18),
|
|
949
|
+
or held (`isHeld`, §20). Lifting the freeze re-arms a producer, so the
|
|
950
|
+
line COULD move. This is a by-design human-escalation brake — EXPECTED,
|
|
951
|
+
never a defect, and it never affects the exit code.
|
|
952
|
+
- **true deadlock** (`report.deadlocks`) — the recompute STILL yields zero
|
|
953
|
+
firings: no producer would re-arm even at unlimited attempts. A genuine
|
|
954
|
+
structural dead-end (e.g. a `group:`-blocked or ungreen-input state, or an
|
|
955
|
+
owed input with no producer). This is folded into `hasDefiniteDefect` and
|
|
956
|
+
makes `check` exit nonzero — but only when the search was exhaustive
|
|
957
|
+
(`!report.bounded`), since a tight `--max-collection`/`--max-states` cap
|
|
958
|
+
can otherwise manufacture a spurious no-moves state.
|
|
959
|
+
|
|
960
|
+
The freeze-lift recompute ONLY lifts the `frozen()` guard — it does not
|
|
961
|
+
bypass group-exclusivity (`groupBlockingWinner`), input-green gates, or
|
|
962
|
+
`isDebt`. A state blocked by a group winner or an ungreen input classifies as
|
|
963
|
+
a true deadlock, not a stall state, even if some artifact elsewhere also
|
|
964
|
+
happens to be frozen.
|
|
965
|
+
|
|
966
|
+
Separately, `report.stuck` records reachable states that have a stalled
|
|
967
|
+
debt (`maxAttempts`/`maxSchemaFailures`/held) BUT still have >= 1 eligible
|
|
968
|
+
firing — a brake tripped on one branch while the line can still move on
|
|
969
|
+
another. This is informational only, never a defect on its own, and a
|
|
970
|
+
no-moves state is never listed here (it lands in `stallStates` or
|
|
971
|
+
`deadlocks` instead) — so no single state is ever double-listed across
|
|
972
|
+
`stuck`, `stallStates`, and `deadlocks`.
|
|
973
|
+
|
|
974
|
+
Dead steps — a step name that never appears as a firing in any explored
|
|
975
|
+
transition — are split into two categories with different severity, via a
|
|
976
|
+
static `canEverFire(step, def)` check (`model.ts`) that needs no search
|
|
977
|
+
bounds at all:
|
|
978
|
+
- **structurally dead** (`report.structurallyDeadSteps`) — `canEverFire` is
|
|
979
|
+
false: the step can NEVER fire, regardless of `--max-depth`/
|
|
980
|
+
`--max-states`. This is a genuine wiring defect (e.g. a reduce-mode step
|
|
981
|
+
with no singleton produce to discharge). It is always a *definite*
|
|
982
|
+
finding — bounds-independent by construction — so it is folded into
|
|
983
|
+
`hasDefiniteDefect` and makes `check` exit nonzero, the same way an
|
|
984
|
+
invariant violation does.
|
|
985
|
+
- **unreached within bounds** (`report.unreachedSteps`) — `canEverFire` is
|
|
986
|
+
true: the step CAN fire in principle, but the bounded search didn't reach
|
|
987
|
+
it before exhausting `--max-states`/`--max-depth`. This is informational
|
|
988
|
+
only, a bounds artifact — it does NOT affect the exit code. Raising the
|
|
989
|
+
search bounds may surface the step firing.
|
|
990
|
+
|
|
991
|
+
`canEverFire` is a sound detector of deadness: it only reports a step as
|
|
992
|
+
structurally dead when certain no firing can ever be pushed for it (mirrors
|
|
993
|
+
`eligibleFirings`'s discharge-set logic per step mode); when uncertain it
|
|
994
|
+
defaults to "can fire," so a step is never wrongly flagged as a wiring
|
|
995
|
+
defect. Most structurally-dead shapes are already caught earlier as hard
|
|
996
|
+
errors by `validateDef` (which `check` runs first and throws on) — the
|
|
997
|
+
residual case `canEverFire` exists to catch is a reduce-mode step whose
|
|
998
|
+
`produces:` has zero singleton entries (and no collection produce either,
|
|
999
|
+
so `validateDef`'s reduce check doesn't trip), which reaches `modelCheck`
|
|
1000
|
+
silently dead.
|
|
940
1001
|
|
|
941
1002
|
Two things it deliberately does not model, and why: **born-rejected
|
|
942
1003
|
commits** — a stale-CAS refusal (§12.2, §24.4) is a refusal, not a state
|
|
@@ -950,14 +1011,27 @@ either of these — it answers "is this graph structurally sound," not "can a
|
|
|
950
1011
|
human or a stale commit route around a stall." See README's Testing section
|
|
951
1012
|
for how `owenloop check` fits alongside the test suite.
|
|
952
1013
|
|
|
953
|
-
The checker also has no runtime `provide` values, so
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
always supplies via `provide`
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
1014
|
+
The checker also has no runtime `provide` values, so a `seedOwed: true`
|
|
1015
|
+
input has no transition that can green it on its own — without seeding it
|
|
1016
|
+
green some other way, it starts owed and can manufacture a false depth-0
|
|
1017
|
+
deadlock for a def whose inputs the operator always supplies via `provide`
|
|
1018
|
+
at `create` time. `CheckOptions.assumeProvided` (library level, when calling
|
|
1019
|
+
`modelCheck` directly) controls this and **defaults to `false`** — that
|
|
1020
|
+
library default is unchanged by the CLI change below, and is what the
|
|
1021
|
+
`modelCheck` unit tests calling it directly still rely on.
|
|
1022
|
+
|
|
1023
|
+
`owenloop check` (the CLI command), however, now defaults to
|
|
1024
|
+
`assumeProvided: true` — seedOwed inputs are seeded green by default,
|
|
1025
|
+
modeling "the operator already ran `provide` at `create`." This dissolves
|
|
1026
|
+
the false depth-0 deadlock for the common case without the flag. Pass
|
|
1027
|
+
`--strict-inputs` to opt back out to the seedOwed-starts-owed behavior; when
|
|
1028
|
+
that's the *sole* reason for an initial-state deadlock, `owenloop check`
|
|
1029
|
+
also prints a one-line hint naming the responsible seedOwed input(s) and
|
|
1030
|
+
pointing at re-running without `--strict-inputs`. `--assume-provided` is
|
|
1031
|
+
still accepted (never errors) but is now redundant with the default; if both
|
|
1032
|
+
`--strict-inputs` and `--assume-provided` are passed, `--strict-inputs` wins.
|
|
1033
|
+
In all cases, seeding only affects the initial seed — a genuine deadlock
|
|
1034
|
+
reachable past the inputs is still reported.
|
|
961
1035
|
|
|
962
1036
|
## §26 Declarative exclusive produce-groups (`group:`)
|
|
963
1037
|
|
|
@@ -1243,39 +1317,39 @@ prefixing untouched (there are no stems inside `x:` to rewrite — it's
|
|
|
1243
1317
|
opaque); a child definition's own top-level `x:` stays on the child def and
|
|
1244
1318
|
is not merged into the parent's.
|
|
1245
1319
|
|
|
1246
|
-
### §27.4 `
|
|
1320
|
+
### §27.4 `executor:`/`command:`/`spec:` — declaring the executor
|
|
1247
1321
|
|
|
1248
1322
|
`x:` (§27.3) is a namespaced escape hatch for arbitrary external vocabulary.
|
|
1249
|
-
`
|
|
1323
|
+
`executor:` is a narrower, purpose-built field for one specific job: telling
|
|
1250
1324
|
whatever dispatches orders *which kind* of executor a step's order is for. It
|
|
1251
1325
|
follows the same opaque-passthrough contract as `model` — the engine never
|
|
1252
1326
|
interprets it, only carries it — but unlike `model` (a free-form quality
|
|
1253
|
-
hint) and unlike `x:` (fully unvalidated contents), `
|
|
1254
|
-
hard-coded shape rules, because the two most common
|
|
1327
|
+
hint) and unlike `x:` (fully unvalidated contents), `executor:` gets two narrow,
|
|
1328
|
+
hard-coded shape rules, because the two most common executor types have a
|
|
1255
1329
|
structural precondition the engine can cheaply catch at load time instead of
|
|
1256
1330
|
letting it surface as a confusing runtime stall.
|
|
1257
1331
|
|
|
1258
1332
|
**The contract, four clauses:**
|
|
1259
1333
|
|
|
1260
1334
|
1. **Default is `'agent'`, and that default is silent.** A step (or judge)
|
|
1261
|
-
that omits `
|
|
1262
|
-
feature existed — every def in this repo predating `
|
|
1335
|
+
that omits `executor:` entirely behaves exactly as it did before this
|
|
1336
|
+
feature existed — every def in this repo predating `executor:` is
|
|
1263
1337
|
unaffected, byte for byte. The default is applied at validation and
|
|
1264
1338
|
engine-order-building time, never written back into the parsed def.
|
|
1265
|
-
2. **`
|
|
1266
|
-
effective
|
|
1267
|
-
`DefError`: `` step '<name>' has
|
|
1268
|
-
other
|
|
1269
|
-
validated when the
|
|
1270
|
-
3. **`
|
|
1271
|
-
deliberately scoped to an *explicit* `
|
|
1272
|
-
value — i.e. `validateDef` checks `l.
|
|
1273
|
-
`(l.
|
|
1339
|
+
2. **`executor: command` requires `command:`.** A step (or judge) whose
|
|
1340
|
+
effective executor is `'command'` and carries no `command:` is a load-time
|
|
1341
|
+
`DefError`: `` step '<name>' has executor 'command' but no command: ``. Any
|
|
1342
|
+
other executor string has no such requirement — `command:` is only ever
|
|
1343
|
+
validated when the executor is literally `'command'`.
|
|
1344
|
+
3. **`executor: agent` (explicit) requires a non-empty `body:`.** This check is
|
|
1345
|
+
deliberately scoped to an *explicit* `executor: agent`, not the *defaulted*
|
|
1346
|
+
value — i.e. `validateDef` checks `l.executor === 'agent'`, never
|
|
1347
|
+
`(l.executor ?? 'agent') === 'agent'`. That distinction matters: plenty of
|
|
1274
1348
|
existing fixtures and generator-only steps rely on `buildStep`'s
|
|
1275
|
-
empty-body default and never write `
|
|
1349
|
+
empty-body default and never write `executor:` at all. Checking the
|
|
1276
1350
|
defaulted value would retroactively break every one of them. Checking
|
|
1277
1351
|
only the explicit form catches the actual mistake this rule exists for —
|
|
1278
|
-
someone opts into `
|
|
1352
|
+
someone opts into `executor: agent` on purpose and forgets the prompt —
|
|
1279
1353
|
without touching a single pre-existing def.
|
|
1280
1354
|
4. **`command:` and `spec:` are otherwise opaque.** `command` is
|
|
1281
1355
|
shape-checked as a string (`asString`); `spec` is shape-checked as a plain
|
|
@@ -1287,37 +1361,37 @@ letting it surface as a confusing runtime stall.
|
|
|
1287
1361
|
contents" philosophy as `x:`, just scoped to one step instead of the
|
|
1288
1362
|
whole def.
|
|
1289
1363
|
|
|
1290
|
-
**The optional `
|
|
1364
|
+
**The optional `executors:` allow-list.** A definition can declare `executors:
|
|
1291
1365
|
[agent, command, …]` at the top level — a typo guard, nothing more. When
|
|
1292
|
-
present, `validateDef` rejects any step or judge whose *effective*
|
|
1366
|
+
present, `validateDef` rejects any step or judge whose *effective* executor
|
|
1293
1367
|
(after the `?? 'agent'` default is applied) isn't in the list. This runs
|
|
1294
|
-
**after** the default, deliberately: a def that declares `
|
|
1295
|
-
(excluding `'agent'` on purpose) still fails a step that omits `
|
|
1296
|
-
entirely, because that step's effective
|
|
1368
|
+
**after** the default, deliberately: a def that declares `executors: [command]`
|
|
1369
|
+
(excluding `'agent'` on purpose) still fails a step that omits `executor:`
|
|
1370
|
+
entirely, because that step's effective executor is `'agent'` and `'agent'`
|
|
1297
1371
|
isn't in the list. This is the intended behavior — once a def opts into the
|
|
1298
1372
|
allow-list, it's exhaustive, and a step relying on the silent default doesn't
|
|
1299
|
-
get a free pass around it. A def with no `
|
|
1300
|
-
string; there is no engine-wide registry of valid
|
|
1373
|
+
get a free pass around it. A def with no `executors:` key accepts any executor
|
|
1374
|
+
string; there is no engine-wide registry of valid executor types to check
|
|
1301
1375
|
against.
|
|
1302
1376
|
|
|
1303
|
-
**Pass-through.** `
|
|
1304
|
-
the emitted `Order` untouched — `Order.
|
|
1377
|
+
**Pass-through.** `executor`, `command`, and `spec` all ride `buildOrder` onto
|
|
1378
|
+
the emitted `Order` untouched — `Order.executor`, `Order.command`, `Order.spec`
|
|
1305
1379
|
— the same pass-through contract as `Order.model` and `Order.x`. A step that
|
|
1306
1380
|
never sets them emits an order with all three fields absent, identical to
|
|
1307
1381
|
before this feature existed.
|
|
1308
1382
|
|
|
1309
1383
|
**Judges get the same fields, for free.** §24's `synthesizeJudgeSteps` turns
|
|
1310
1384
|
each `judges:` entry into an ordinary `StepDef` — so a judge entry accepting
|
|
1311
|
-
`
|
|
1385
|
+
`executor:`/`command:`/`spec:` and having the exact same `validateDef` rules
|
|
1312
1386
|
apply to it isn't a separate code path, it's the same rules running against
|
|
1313
1387
|
an already-existing synthesized step. A judge can therefore be a
|
|
1314
1388
|
deterministic check (a script's exit code) instead of an LLM verdict, without
|
|
1315
1389
|
any new validation logic. Note the pre-existing, orthogonal judge
|
|
1316
1390
|
requirement — every judge needs `body:` or `bodyFile:` regardless of
|
|
1317
|
-
`
|
|
1391
|
+
`executor:` — still applies; a `executor: command` judge still declares a
|
|
1318
1392
|
`body:`, it's simply unread by a non-agent dispatcher.
|
|
1319
1393
|
|
|
1320
|
-
**Scope notes**, mirroring §27.3's: `
|
|
1394
|
+
**Scope notes**, mirroring §27.3's: `executor`/`command`/`spec` are additive
|
|
1321
1395
|
and inert — a definition that never sets any of the three is unchanged in
|
|
1322
1396
|
behavior and in `hashDef` terms. They live on the same two authored,
|
|
1323
1397
|
engine-fired shapes as `x:` (a normal step, and — new here — a judge entry),
|
package/docs/embedding.md
CHANGED
|
@@ -6,8 +6,9 @@ on an `Engine` and prints the results as JSON. Everything it does, a host
|
|
|
6
6
|
process can do **in-process** — and get the lifecycle back as typed objects
|
|
7
7
|
rather than JSON on stdout.
|
|
8
8
|
|
|
9
|
-
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
-
|
|
9
|
+
This document covers the in-process API: the one-call factory, the worker step
|
|
10
|
+
(the loop a Step Agent — or your own host code — runs), in-memory definitions,
|
|
11
|
+
lifecycle/concurrency, and **push-style events** so a host
|
|
11
12
|
can react the instant the graph advances instead of polling.
|
|
12
13
|
|
|
13
14
|
## The one-call factory
|
|
@@ -83,7 +84,7 @@ const status = engine.status(wf); // { done, debts, eligible, blocked, inFligh
|
|
|
83
84
|
Each `order` is self-contained: `workflow` (the instance it belongs to — see
|
|
84
85
|
deep tick below), `prompt`, `consumes` (the captured green inputs), `owes` (the
|
|
85
86
|
owed outputs + their accumulated reason threads), plus
|
|
86
|
-
`inputs`/`outputs`/`model`/`
|
|
87
|
+
`inputs`/`outputs`/`model`/`executor`/`command`/`spec`. A consumer rejecting an
|
|
87
88
|
upstream artifact is just `engine.reject(wf, path, by, text)`; the forward
|
|
88
89
|
cascade and stall liveness behave exactly as they do under the CLI, because
|
|
89
90
|
it's the same engine.
|
|
@@ -110,28 +111,28 @@ one `TickResult` belongs to the instance you ticked; each order carries its own
|
|
|
110
111
|
(CLI `--shallow`) stays the deliberate single-instance escape hatch when you
|
|
111
112
|
want exactly the old behavior.
|
|
112
113
|
|
|
113
|
-
`order.
|
|
114
|
+
`order.executor` is where dispatch-by-executor-type earns its keep in an
|
|
114
115
|
embedder: rather than every order going to the same LLM-driving `runYourWorker`,
|
|
115
116
|
branch on it before deciding how to run the order.
|
|
116
117
|
|
|
117
118
|
```ts
|
|
118
119
|
for (const order of orders) {
|
|
119
120
|
const result =
|
|
120
|
-
order.
|
|
121
|
+
order.executor === 'command'
|
|
121
122
|
? await runCommand(order.command!, order.spec) // order.command is opaque — never shelled out by owenloop itself
|
|
122
|
-
: await runYourAgent(order); // default /
|
|
123
|
+
: await runYourAgent(order); // default / executor: 'agent' / anything else you handle the same way
|
|
123
124
|
|
|
124
125
|
const commit = engine.green(wf, order.run, order.outputs[0], result);
|
|
125
126
|
engine.close(wf, order.run);
|
|
126
127
|
}
|
|
127
128
|
```
|
|
128
129
|
|
|
129
|
-
`
|
|
130
|
+
`executor`/`command`/`spec` are all optional and opaque — the engine only
|
|
130
131
|
shape-checks them at load time (`command` a string, `spec` a plain map) and
|
|
131
|
-
never reads their contents itself. `order.
|
|
132
|
+
never reads their contents itself. `order.executor` is `undefined` when the
|
|
132
133
|
step never set it (today's default, unaffected by this feature). See
|
|
133
134
|
[`docs/design.md` §27.4](design.md) for the full contract and
|
|
134
|
-
[`docs/authoring.md`](authoring.md#
|
|
135
|
+
[`docs/authoring.md`](authoring.md#executor--declaring-the-executor) for how to
|
|
135
136
|
declare it on a step.
|
|
136
137
|
|
|
137
138
|
A runnable version of this lives at [`examples/embed.ts`](../examples/embed.ts):
|
|
@@ -262,9 +263,10 @@ all the shared types (`Order`, `CommitResult`, `WorkflowStatus`, `WorkflowDef`,
|
|
|
262
263
|
`EngineEvent`, `EngineListener`, …). For most hosts, `createEngine` + the engine methods + the `Order` /
|
|
263
264
|
`CommitResult` / `WorkflowStatus` types are the whole surface you need.
|
|
264
265
|
|
|
265
|
-
The index also exports a **
|
|
266
|
-
|
|
267
|
-
duplicating it
|
|
266
|
+
The index also exports a **credential surface** for hosts that need to read,
|
|
267
|
+
write, or refresh a stored hub credential through owenloop's own store logic
|
|
268
|
+
instead of duplicating it. The read entry is `readStoredCredential(origin, opts)`,
|
|
269
|
+
which returns the `Credential`
|
|
268
270
|
for a hub origin **and slot** (or `null` if none is stored), using the same
|
|
269
271
|
backend selection as the CLI — macOS Keychain, or the `0600` credentials file
|
|
270
272
|
elsewhere / with `OWENLOOP_NO_KEYCHAIN=1` (see
|
|
@@ -284,8 +286,31 @@ an invalid account name) and `keychainServiceFor` (normalized origin → the
|
|
|
284
286
|
keychain service name) let a host address the same slots the CLI does without
|
|
285
287
|
re-deriving the keying. Slots never fall back to one another: an empty
|
|
286
288
|
`agent:ci` reads as `null` even when `human` is populated. The function never
|
|
287
|
-
logs or echoes the secret
|
|
288
|
-
|
|
289
|
+
logs or echoes the secret.
|
|
290
|
+
|
|
291
|
+
The write entries let a host store or refresh a credential the same way the CLI
|
|
292
|
+
does, addressing the same slots. All three are **async** and take a `CredentialIO`
|
|
293
|
+
(`{ env, keychain?, fetch? }` — a strict subset of the CLI's own io, so the CLI
|
|
294
|
+
passes its `io` unchanged):
|
|
295
|
+
|
|
296
|
+
- `storeCredential(io, origin, slot, credential)` — writes a credential into a
|
|
297
|
+
slot, merging with the other slots on the same origin (the file backend keeps
|
|
298
|
+
`human` when you write `agent:ci`).
|
|
299
|
+
- `deleteCredential(io, origin, slot)` — removes one slot.
|
|
300
|
+
- `ensureFreshOAuth(io, origin, slot, credential)` — returns the credential if
|
|
301
|
+
it is still fresh (more than 60s from expiry), otherwise refreshes the OAuth
|
|
302
|
+
token over the network and persists the rotated result, returning it.
|
|
303
|
+
|
|
304
|
+
`storeCredential`, `deleteCredential`, and the persist inside `ensureFreshOAuth`
|
|
305
|
+
serialize through the `credentials.lock` file described in
|
|
306
|
+
[where the credential lands](cli.md#hub-login--connect--push--logout): a
|
|
307
|
+
concurrent refresh adopts a token another process already rotated rather than
|
|
308
|
+
double-refreshing and clobbering it. When `OWENLOOP_CREDENTIAL_COMMAND` is set,
|
|
309
|
+
that command owns the credential lifecycle — `storeCredential`/`deleteCredential`
|
|
310
|
+
refuse to write, and `ensureFreshOAuth` refreshes over the network without
|
|
311
|
+
persisting. `login`/`logout` are still the CLI's way to store or remove a
|
|
312
|
+
credential; these exports are the programmatic equivalent for a host embedding
|
|
313
|
+
the engine.
|
|
289
314
|
|
|
290
315
|
One behaviour to handle: when the user has set `OWENLOOP_CREDENTIAL_COMMAND` (an
|
|
291
316
|
external command that supplies the credential, ahead of both stores — see
|
|
@@ -1,27 +1,27 @@
|
|
|
1
|
-
# Declarative executor dispatch — demonstrates `
|
|
1
|
+
# Declarative executor dispatch — demonstrates `executor:`/`command:`/`spec:`
|
|
2
2
|
# (§27.4 of docs/design.md).
|
|
3
3
|
#
|
|
4
|
-
# The engine never executes anything; `
|
|
4
|
+
# The engine never executes anything; `executor:` declares which kind of
|
|
5
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 `
|
|
6
|
+
# with a deterministic, non-LLM one. `planner` omits `executor:` entirely (the
|
|
7
7
|
# default, unaffected `'agent'` path — every existing def in this repo stays
|
|
8
|
-
# exactly like this). `tester` declares `
|
|
9
|
-
# `command:` — a
|
|
8
|
+
# exactly like this). `tester` declares `executor: command` with a real
|
|
9
|
+
# `command:` — a Worker dispatching this order runs the command instead of an
|
|
10
10
|
# agent, no judgment involved. `tester`'s `result` produce is gated by a
|
|
11
11
|
# command judge (`ci-gate`): judges can be deterministic too, not just
|
|
12
12
|
# LLM-based — this one runs a check script and approves/rejects on exit status.
|
|
13
13
|
#
|
|
14
14
|
# Drive it:
|
|
15
|
-
# wf=$(owenloop create command-
|
|
16
|
-
# owenloop tick $wf # -> order for `planner` (
|
|
15
|
+
# wf=$(owenloop create command-executor --provide plan='{"text":"add a cache layer"}' | jq -r .workflow)
|
|
16
|
+
# owenloop tick $wf # -> order for `planner` (executor: agent, default)
|
|
17
17
|
# owenloop green $wf <run> reviewed_plan --value '{"approved":true}'
|
|
18
|
-
# owenloop tick $wf # -> order for `tester` (
|
|
18
|
+
# owenloop tick $wf # -> order for `tester` (executor: command)
|
|
19
19
|
# owenloop green $wf <run> result --value '{"exitCode":0}'
|
|
20
|
-
# owenloop tick $wf # -> order for the `ci-gate` judge (
|
|
20
|
+
# owenloop tick $wf # -> order for the `ci-gate` judge (executor: command)
|
|
21
21
|
# owenloop green $wf <judge-run> result --value '{}' # judge approves -> result goes green
|
|
22
22
|
|
|
23
|
-
name: command-
|
|
24
|
-
title: Command-dispatched
|
|
23
|
+
name: command-executor
|
|
24
|
+
title: Command-dispatched executor step
|
|
25
25
|
description: Mixes an agent step with a deterministic command step and a command judge.
|
|
26
26
|
|
|
27
27
|
inputs:
|
|
@@ -32,7 +32,7 @@ steps:
|
|
|
32
32
|
- name: planner
|
|
33
33
|
consumes: [plan]
|
|
34
34
|
produces: [reviewed_plan]
|
|
35
|
-
#
|
|
35
|
+
# executor: omitted here on purpose — the default/common case, completely
|
|
36
36
|
# unaffected by this feature. This step dispatches to an agent exactly
|
|
37
37
|
# like every step in every other bundled example.
|
|
38
38
|
body: |
|
|
@@ -46,11 +46,11 @@ steps:
|
|
|
46
46
|
judges:
|
|
47
47
|
- name: ci-gate
|
|
48
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
|
-
|
|
49
|
+
executor: command # deterministic — no judgment, just run the script
|
|
50
50
|
command: scripts/ci-gate.sh # exit 0 approves, non-zero rejects with its output
|
|
51
|
-
|
|
51
|
+
executor: command # deterministic — no judgment, just run the script
|
|
52
52
|
command: npm test # opaque to the engine; the dispatcher runs this
|
|
53
53
|
spec: # opaque config for the dispatcher; engine never reads it
|
|
54
54
|
timeout: 300
|
|
55
55
|
workdir: .
|
|
56
|
-
body: "" # not required for
|
|
56
|
+
body: "" # not required for executor: command (no agent prompt)
|