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/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,17 @@ All notable changes to this project are documented here. The format is based on
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
|
|
5
5
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.2.1](https://github.com/typicalday/owenloop/compare/v0.2.0...v0.2.1) (2026-07-04)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### Bug Fixes
|
|
11
|
+
|
|
12
|
+
* auto-skip submitted group siblings to prevent permanent wedge ([#15](https://github.com/typicalday/owenloop/issues/15)) ([484aea2](https://github.com/typicalday/owenloop/commit/484aea20d682196574b5c8c7da35bfd3e10619d3))
|
|
13
|
+
* catch child schema refusals as debts and version-pin the calls: mirror ([#16](https://github.com/typicalday/owenloop/issues/16)) ([500cce7](https://github.com/typicalday/owenloop/commit/500cce7152023391c19393ee5dcb18d802a6b2e8))
|
|
14
|
+
* close three commit-side verb guard gaps (F3, F5, F7) ([#11](https://github.com/typicalday/owenloop/issues/11)) ([fbcc777](https://github.com/typicalday/owenloop/commit/fbcc77700fefcf66f287e5e903ad7c03e9b59b64))
|
|
15
|
+
* refuse emit after the collection seal has greened (§11.1, F6) ([#17](https://github.com/typicalday/owenloop/issues/17)) ([cd963cf](https://github.com/typicalday/owenloop/commit/cd963cf9296504dc0278f9fa68d097a60e318c0f))
|
|
16
|
+
* ship src/ in the npm files allowlist ([#13](https://github.com/typicalday/owenloop/issues/13)) ([20ffcea](https://github.com/typicalday/owenloop/commit/20ffcea9132610203ef9da3cfa147990ad157ca9))
|
|
17
|
+
|
|
7
18
|
## [0.2.0](https://github.com/typicalday/owenloop/compare/v0.1.1...v0.2.0) (2026-07-04)
|
|
8
19
|
|
|
9
20
|
|
package/README.md
CHANGED
|
@@ -158,6 +158,10 @@ Two things make this more than running steps in dependency order:
|
|
|
158
158
|
*width* — a producer can emit any number of elements — but the wiring graph
|
|
159
159
|
itself (which steps exist, what each consumes and produces) is fixed when
|
|
160
160
|
the definition loads, not mutable while an instance runs.
|
|
161
|
+
- **Not a command runner.** `worker:`/`command:` label which kind of
|
|
162
|
+
executor an order is for and carry a command string through untouched —
|
|
163
|
+
the engine never shells out, executes, or interprets it. Actually running
|
|
164
|
+
anything is always the dispatcher's job, on the other side of `tick`.
|
|
161
165
|
|
|
162
166
|
---
|
|
163
167
|
|
|
@@ -250,6 +254,20 @@ opt-in `strongest` tier is for, reserved for the rare step where nothing less
|
|
|
250
254
|
will do. See
|
|
251
255
|
[`docs/authoring.md`](docs/authoring.md#model--quality-tiers-not-vendor-ids).
|
|
252
256
|
|
|
257
|
+
### Worker dispatch
|
|
258
|
+
|
|
259
|
+
`worker: agent | command | …` declares which kind of executor a step's order
|
|
260
|
+
is for — the default (`agent`, silent when omitted) is unaffected; every
|
|
261
|
+
def written before this feature stays byte for byte the same. Opt a step
|
|
262
|
+
into `worker: command` and give it a `command:` string to switch it to a
|
|
263
|
+
deterministic executor instead of an LLM — the engine never runs it, only
|
|
264
|
+
carries it through on the order for your dispatcher to branch on. An
|
|
265
|
+
optional `spec:` map carries further opaque config (a timeout, a working
|
|
266
|
+
directory), and a judge entry accepts the same fields, so a quality gate can
|
|
267
|
+
be a script's exit code instead of a verdict. See
|
|
268
|
+
[`docs/authoring.md`](docs/authoring.md#worker--declaring-the-executor) and
|
|
269
|
+
[`command-worker.yaml`](examples/workflows/command-worker.yaml).
|
|
270
|
+
|
|
253
271
|
### Event subscription — for embedding
|
|
254
272
|
|
|
255
273
|
Driving the engine in-process doesn't require polling: `engine.subscribe(...)`
|
package/dist/defs.js
CHANGED
|
@@ -35,13 +35,13 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
|
|
|
35
35
|
* fields, so it gets its own allowlist rather than folding into
|
|
36
36
|
* RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
|
|
37
37
|
const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
|
|
38
|
-
const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay'];
|
|
38
|
+
const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'worker', 'command', 'spec'];
|
|
39
39
|
/** Keys valid on a normal (non-calls:, non-include:) step entry. */
|
|
40
40
|
const RAW_STEP_KEYS = [
|
|
41
41
|
'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
|
|
42
42
|
'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
|
|
43
43
|
'workdir', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
|
|
44
|
-
'calls', 'reapTtl', 'x',
|
|
44
|
+
'calls', 'reapTtl', 'x', 'worker', 'command', 'spec',
|
|
45
45
|
];
|
|
46
46
|
/** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
|
|
47
47
|
* the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
|
|
@@ -49,7 +49,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
|
|
|
49
49
|
/** Keys valid on an include: directive entry — the `include:` key is the
|
|
50
50
|
* discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
|
|
51
51
|
const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
|
|
52
|
-
const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x'];
|
|
52
|
+
const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'workers'];
|
|
53
53
|
// ---- defaults ----------------------------------------------------------------
|
|
54
54
|
const DEFAULTS = {
|
|
55
55
|
cadence: '0s',
|
|
@@ -215,6 +215,12 @@ function parseJudges(v, ctx, baseDir) {
|
|
|
215
215
|
if (raw.maxRunsPerDay !== undefined) {
|
|
216
216
|
judge.maxRunsPerDay = asNumber(raw.maxRunsPerDay, DEFAULTS.maxRunsPerDay, `judge '${name}'.maxRunsPerDay`);
|
|
217
217
|
}
|
|
218
|
+
if (raw.worker !== undefined)
|
|
219
|
+
judge.worker = asString(raw.worker, `judge '${name}'.worker`);
|
|
220
|
+
if (raw.command !== undefined)
|
|
221
|
+
judge.command = asString(raw.command, `judge '${name}'.command`);
|
|
222
|
+
if (raw.spec !== undefined)
|
|
223
|
+
judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
|
|
218
224
|
return judge;
|
|
219
225
|
});
|
|
220
226
|
}
|
|
@@ -520,6 +526,8 @@ export function buildDef(raw, source, baseDir) {
|
|
|
520
526
|
}
|
|
521
527
|
if (r.x !== undefined)
|
|
522
528
|
def.x = asExtension(r.x, `workflow '${name}'.x`);
|
|
529
|
+
if (r.workers !== undefined)
|
|
530
|
+
def.workers = asStringArray(r.workers, `workflow '${name}'.workers`);
|
|
523
531
|
return def;
|
|
524
532
|
}
|
|
525
533
|
// ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
|
|
@@ -724,6 +732,12 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
|
|
|
724
732
|
};
|
|
725
733
|
if (j.model !== undefined)
|
|
726
734
|
step.model = j.model;
|
|
735
|
+
if (j.worker !== undefined)
|
|
736
|
+
step.worker = j.worker;
|
|
737
|
+
if (j.command !== undefined)
|
|
738
|
+
step.command = j.command;
|
|
739
|
+
if (j.spec !== undefined)
|
|
740
|
+
step.spec = j.spec;
|
|
727
741
|
return step;
|
|
728
742
|
});
|
|
729
743
|
}
|
|
@@ -823,6 +837,12 @@ function buildStep(rl, i, baseDir) {
|
|
|
823
837
|
step.workdir = asString(rl.workdir, `step '${name}'.workdir`);
|
|
824
838
|
if (rl.model !== undefined)
|
|
825
839
|
step.model = asString(rl.model, `step '${name}'.model`);
|
|
840
|
+
if (rl.worker !== undefined)
|
|
841
|
+
step.worker = asString(rl.worker, `step '${name}'.worker`);
|
|
842
|
+
if (rl.command !== undefined)
|
|
843
|
+
step.command = asString(rl.command, `step '${name}'.command`);
|
|
844
|
+
if (rl.spec !== undefined)
|
|
845
|
+
step.spec = asExtension(rl.spec, `step '${name}'.spec`);
|
|
826
846
|
if (rl.x !== undefined)
|
|
827
847
|
step.x = asExtension(rl.x, `step '${name}'.x`);
|
|
828
848
|
if (asBool(rl.terminal, false, `step '${name}'.terminal`))
|
|
@@ -1013,6 +1033,43 @@ export function validateDef(def) {
|
|
|
1013
1033
|
}
|
|
1014
1034
|
}
|
|
1015
1035
|
}
|
|
1036
|
+
// W1-VALIDATE: worker:/command: shape rules (declarative executor dispatch).
|
|
1037
|
+
// Only two hard requirements; any other worker value is fully opaque.
|
|
1038
|
+
for (const l of def.steps) {
|
|
1039
|
+
const worker = l.worker ?? 'agent';
|
|
1040
|
+
// Deliberately `l.worker === 'agent'` (explicit opt-in), NOT
|
|
1041
|
+
// `(l.worker ?? 'agent') === 'agent'` — that stricter form would also
|
|
1042
|
+
// catch every default-agent step that already gets away with an empty
|
|
1043
|
+
// body today (e.g. calls:-adjacent or generator-only fixtures), breaking
|
|
1044
|
+
// existing defs that never write `worker:` at all. Scoping the check to
|
|
1045
|
+
// an EXPLICIT `worker: agent` keeps every pre-existing def byte-for-byte
|
|
1046
|
+
// unaffected while still catching "someone opted into the agent worker
|
|
1047
|
+
// type and forgot a body".
|
|
1048
|
+
if (l.worker === 'agent' && l.body.trim() === '') {
|
|
1049
|
+
errors.push(`step '${l.name}' has worker 'agent' but no body: (an agent step needs a prompt)`);
|
|
1050
|
+
}
|
|
1051
|
+
else if (worker === 'command') {
|
|
1052
|
+
if (l.command === undefined) {
|
|
1053
|
+
errors.push(`step '${l.name}' has worker 'command' but no command:`);
|
|
1054
|
+
}
|
|
1055
|
+
}
|
|
1056
|
+
// any other worker value: opaque, no body/command requirement
|
|
1057
|
+
}
|
|
1058
|
+
// W1-VALIDATE: workers: def-level allow-list typo guard. Applied AFTER the
|
|
1059
|
+
// per-step `worker` default (?? 'agent') — a def declaring `workers:
|
|
1060
|
+
// [command]` (deliberately excluding 'agent') still fails a step that omits
|
|
1061
|
+
// `worker:` entirely, since its effective worker is 'agent'. This is
|
|
1062
|
+
// intended (the list is exhaustive once declared), documented in
|
|
1063
|
+
// docs/authoring.md.
|
|
1064
|
+
if (def.workers && def.workers.length > 0) {
|
|
1065
|
+
const allowed = new Set(def.workers);
|
|
1066
|
+
for (const l of def.steps) {
|
|
1067
|
+
const worker = l.worker ?? 'agent';
|
|
1068
|
+
if (!allowed.has(worker)) {
|
|
1069
|
+
errors.push(`step '${l.name}' has worker '${worker}' but workflow '${def.name}'.workers does not list it`);
|
|
1070
|
+
}
|
|
1071
|
+
}
|
|
1072
|
+
}
|
|
1016
1073
|
// on: token validation — belt-and-suspenders over buildStep's throw
|
|
1017
1074
|
for (const l of def.steps) {
|
|
1018
1075
|
if (!l.on)
|
package/dist/engine.d.ts
CHANGED
|
@@ -13,6 +13,19 @@ import type { WorkflowStatus } from './model.ts';
|
|
|
13
13
|
import type { SchemaIssue } from './schema.ts';
|
|
14
14
|
import type { Store } from './store.ts';
|
|
15
15
|
import type { Author, FiringTrigger, ReasonEntry, WorkflowDef } from './types.ts';
|
|
16
|
+
/**
|
|
17
|
+
* F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
|
|
18
|
+
* by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
|
|
19
|
+
* `Error` so callers that need to distinguish "this value doesn't fit the
|
|
20
|
+
* schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
|
|
21
|
+
* turn a CHILD's schema refusal into a debt on the parent rather than crash
|
|
22
|
+
* the parent's tick) can catch narrowly instead of blanket-catching.
|
|
23
|
+
*/
|
|
24
|
+
export declare class SchemaRefusalError extends Error {
|
|
25
|
+
readonly inputName: string;
|
|
26
|
+
readonly issues: SchemaIssue[];
|
|
27
|
+
constructor(inputName: string, issues: SchemaIssue[]);
|
|
28
|
+
}
|
|
16
29
|
/** A self-contained unit of work emitted by a tick. */
|
|
17
30
|
export interface Order {
|
|
18
31
|
run: string;
|
|
@@ -24,6 +37,16 @@ export interface Order {
|
|
|
24
37
|
outputs: string[];
|
|
25
38
|
workdir?: string;
|
|
26
39
|
model?: string;
|
|
40
|
+
/** Declares which kind of executor this order is for. Absent = 'agent'
|
|
41
|
+
* (today's behavior). Opaque to the engine; carried through verbatim from
|
|
42
|
+
* the step definition, same pass-through contract as `model`/`x`. */
|
|
43
|
+
worker?: string;
|
|
44
|
+
/** The command string for a `worker: command` order. Opaque to the engine
|
|
45
|
+
* — never parsed, never shelled out. */
|
|
46
|
+
command?: string;
|
|
47
|
+
/** Opaque config object for a non-agent/non-command worker type (or
|
|
48
|
+
* alongside `command`). Carried through untouched, contents never read. */
|
|
49
|
+
spec?: Record<string, unknown>;
|
|
27
50
|
/** §27.3: the step's opaque `x:` extension map, carried through untouched
|
|
28
51
|
* (same pass-through contract as `model`). The engine never reads it —
|
|
29
52
|
* it exists for the external runner/tooling consuming this order. */
|
|
@@ -96,7 +119,7 @@ export interface CommitResult {
|
|
|
96
119
|
}
|
|
97
120
|
/** The outcome of an `emit` (collection accretion) — possibly schema-refused. */
|
|
98
121
|
export interface EmitResult {
|
|
99
|
-
outcome: 'emitted' | 'born-rejected' | 'schema-rejected';
|
|
122
|
+
outcome: 'emitted' | 'born-rejected' | 'schema-rejected' | 'sealed-rejected';
|
|
100
123
|
/** the element paths created (empty unless `emitted`) */
|
|
101
124
|
created: string[];
|
|
102
125
|
reason?: string;
|
|
@@ -192,6 +215,36 @@ export declare class Engine {
|
|
|
192
215
|
defHash: string;
|
|
193
216
|
previousHash?: string;
|
|
194
217
|
};
|
|
218
|
+
/**
|
|
219
|
+
* F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
|
|
220
|
+
* fingerprint to the child outcome's version. A calls: step declares
|
|
221
|
+
* `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
|
|
222
|
+
* see the child outcome (which lives in another instance entirely) — this
|
|
223
|
+
* key is how that pin rides inside the same `Fingerprint` map alongside the
|
|
224
|
+
* gate stems, without colliding with any real parent artifact path (gate
|
|
225
|
+
* stems are bare names; this key is namespaced and reserved).
|
|
226
|
+
*/
|
|
227
|
+
private static readonly CHILD_OUTCOME_PIN_KEY;
|
|
228
|
+
/**
|
|
229
|
+
* F4: the single place that computes "what child-outcome version is this
|
|
230
|
+
* calls: artifact currently resting on" — used both when machine-greening
|
|
231
|
+
* (STEP 6) and when stamping the pin at verdict time (reject propagation,
|
|
232
|
+
* human skip). Returns undefined if no child has ever been spawned (nothing
|
|
233
|
+
* to pin to).
|
|
234
|
+
*/
|
|
235
|
+
private childOutcomePin;
|
|
236
|
+
/**
|
|
237
|
+
* F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
|
|
238
|
+
* re-provide) as a debt on the PARENT calls artifact — same shape as
|
|
239
|
+
* green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
|
|
240
|
+
* a 'validation' reasons entry naming the child input and the schema
|
|
241
|
+
* issues) — so the tick can proceed instead of throwing, and the parent
|
|
242
|
+
* calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
|
|
243
|
+
* Stamps the current gate fingerprint on the rejected artifact so the
|
|
244
|
+
* STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
|
|
245
|
+
* worth retrying" on the next tick.
|
|
246
|
+
*/
|
|
247
|
+
private recordCallsSchemaReject;
|
|
195
248
|
/**
|
|
196
249
|
* M2B: Maintain all `calls:` steps for a parent workflow.
|
|
197
250
|
* Called at the top of tick (outside any tx) and as cascade-up prompt.
|
|
@@ -287,6 +340,20 @@ export declare class Engine {
|
|
|
287
340
|
outcome: 'rejected' | 'born-rejected';
|
|
288
341
|
reason?: string;
|
|
289
342
|
};
|
|
343
|
+
/**
|
|
344
|
+
* F4: forward a reject on a `calls:`-produced artifact to the CHILD's
|
|
345
|
+
* outcome artifact, then reopen the parent calls artifact to `owed` pinned
|
|
346
|
+
* (via `childOutcomePin`) to the just-rejected child outcome version, so
|
|
347
|
+
* STEP 6's mirror only fires again once the child has actually rebuilt past
|
|
348
|
+
* this verdict (§ F4 settled design).
|
|
349
|
+
*
|
|
350
|
+
* The forward is engine-internal: authority was already checked against the
|
|
351
|
+
* PARENT def by `assertAuthority` in `reject()` above, so the child's own
|
|
352
|
+
* `assertAuthority` is not consulted — the author recorded on the child's
|
|
353
|
+
* reasons entry is `parent:<by>` to make the indirection visible in its
|
|
354
|
+
* audit thread.
|
|
355
|
+
*/
|
|
356
|
+
private rejectCallsArtifact;
|
|
290
357
|
/** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
|
|
291
358
|
retract(workflow: string, path: string, by: Author, text: string): void;
|
|
292
359
|
/** A producer skips its own owed output on a dead branch (§16.1 routing). */
|