owenloop 0.2.0 → 0.3.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/dist/defs.d.ts CHANGED
@@ -93,6 +93,39 @@ export declare function loadDefFile(file: string): WorkflowDef;
93
93
  * defs in the same directory (M1-SITE).
94
94
  */
95
95
  export declare function loadDefs(dir: string): Map<string, WorkflowDef>;
96
+ /**
97
+ * Phase 1 of def loading: scan `dir` and build every workflow def UN-finalized
98
+ * (includes not yet expanded, no cross-def / cycle validation). Loads each
99
+ * top-level `*.yaml` / `*.yml` file (excluding a top-level `workflow.yaml`) and
100
+ * each immediate subdirectory's `workflow.yaml`. Throws `DefError` on a
101
+ * duplicate name WITHIN this dir. This is a pure extraction of what used to live
102
+ * inline in `loadDefs` — `loadDefs(dir)` is exactly `finalizeDefs(loadDefsUnfinalized(dir))`.
103
+ *
104
+ * Exported so a caller can merge the raw maps of several dirs and run a single
105
+ * `finalizeDefs` over the union (giving correct include-expansion and cross-def
106
+ * `calls:` resolution across the merged boundary). This function stays a pure
107
+ * dir-scanner: it holds NO ledger / `installed.json` knowledge (that composition
108
+ * lives at the CLI layer where cwd and defsDir are both known).
109
+ */
110
+ export declare function loadDefsUnfinalized(dir: string): Map<string, WorkflowDef>;
111
+ /**
112
+ * Phase 2/3 of def loading, factored out so it is the ONE validator every
113
+ * public construction path shares — the filesystem `loadDefs` above AND the
114
+ * in-memory `createEngine({ defs })` factory path (REL-4). Given a raw def map
115
+ * (each def possibly still carrying `_includes`), it: expands each def's
116
+ * includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
117
+ * key validity, exactly-one child output); runs `validateDef` per expanded def;
118
+ * and finally `detectCallsCycles` over the whole expanded map. Returns the
119
+ * expanded, validated map. Throws `DefError` on the first problem — the same
120
+ * messages, in the same order, the filesystem loader has always produced (this
121
+ * is a pure extraction of what used to live inline in `loadDefs`).
122
+ *
123
+ * A host wiring an `Engine` by hand with its own set can call this to get the
124
+ * same validation the factory and the loader apply. `expandIncludes` is a no-op
125
+ * for a def without `_includes` (the normal in-memory case), so passing a plain
126
+ * def map through is cheap and only adds the cross-def + cycle checks.
127
+ */
128
+ export declare function finalizeDefs(raw: Map<string, WorkflowDef>): Map<string, WorkflowDef>;
96
129
  /** One file that `loadDefsRaw` could not turn into a def (malformed YAML, bad shape, duplicate name). */
97
130
  export interface DefLoadFailure {
98
131
  file: string;
package/dist/defs.js CHANGED
@@ -20,8 +20,8 @@
20
20
  * Draft a plan for ${WORKFLOW}.
21
21
  */
22
22
  import { createHash } from 'node:crypto';
23
- import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
24
- import { basename, dirname, join } from 'node:path';
23
+ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
24
+ import { basename, dirname, isAbsolute, join, sep } from 'node:path';
25
25
  import { parse as parseYaml } from 'yaml';
26
26
  import { parseConsume, parseProduce } from "./paths.js";
27
27
  import { parseDurationMs, parseDurationSecs } from "./util.js";
@@ -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', 'labels', 'maxLease', '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',
@@ -160,6 +160,60 @@ function assertNoUnknownKeys(obj, allowed, ctx) {
160
160
  throw new DefError(`${ctx}: unknown key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `'${k}'`).join(', ')}`);
161
161
  }
162
162
  }
163
+ /**
164
+ * Read a step/judge `bodyFile`, enforcing that it resolves to a regular file
165
+ * contained within `baseDir` (the def file's own directory). Closes SEC-1: an
166
+ * unchecked `join()` + `readFileSync()` let a remote definition with enough
167
+ * `../` components read arbitrary local files during `owenloop add`, and that
168
+ * content then flowed into emitted orders.
169
+ *
170
+ * `ctx` is the caller's error prefix (e.g. `step 'planner'` / `judge 'rigor'`);
171
+ * every failure throws `DefError`. A missing target keeps the historical
172
+ * "could not be read (resolved to '...')" message shape so anything matching
173
+ * /could not be read/ stays green.
174
+ *
175
+ * The containment root is `baseDir` itself. For an installed package `baseDir`
176
+ * is always at or below `<defsDir>/<owner>-<repo>/`, so this is strictly
177
+ * stronger than package-root containment and needs no extra plumbing.
178
+ */
179
+ function readBodyFileContained(baseDir, rel, ctx) {
180
+ if (rel === '' || rel.includes('\0')) {
181
+ throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path with no '.' or '..' components`);
182
+ }
183
+ // Reject absolute paths: POSIX/Windows leading separators and drive prefixes.
184
+ if (isAbsolute(rel) || /^[\\/]/.test(rel) || /^[A-Za-z]:/.test(rel)) {
185
+ throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path, not absolute`);
186
+ }
187
+ // Reject any '.' or '..' segment (split on both separators — catches
188
+ // doubled separators and backslash tricks). The proposal asks to reject '.'
189
+ // too, not just '..'.
190
+ const segments = rel.split(/[\\/]+/);
191
+ if (segments.some((s) => s === '.' || s === '..')) {
192
+ throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path with no '.' or '..' components`);
193
+ }
194
+ const resolvedPath = join(baseDir, rel);
195
+ let realBase;
196
+ let realTarget;
197
+ try {
198
+ // Compare realpath-to-realpath so a symlinked temp dir (macOS /var ->
199
+ // /private/var) doesn't spuriously fail containment, and so a symlink
200
+ // INSIDE the package pointing outside resolves — and is caught — below.
201
+ realBase = realpathSync(baseDir);
202
+ realTarget = realpathSync(resolvedPath);
203
+ }
204
+ catch (e) {
205
+ throw new DefError(`${ctx}: bodyFile '${rel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
206
+ }
207
+ // The `+ sep` is load-bearing: without it '/pkg-evil' would pass containment
208
+ // for base '/pkg'. A regular-file target can never equal realBase itself.
209
+ if (!realTarget.startsWith(realBase + sep)) {
210
+ throw new DefError(`${ctx}: bodyFile '${rel}' resolves outside the workflow's directory`);
211
+ }
212
+ if (!statSync(realTarget).isFile()) {
213
+ throw new DefError(`${ctx}: bodyFile '${rel}' does not resolve to a regular file`);
214
+ }
215
+ return readFileSync(realTarget, 'utf8');
216
+ }
163
217
  /**
164
218
  * Parse a `judges:` list hanging off a produce entry (§24 YAML surface). Each
165
219
  * entry's `bodyFile` (if present) is resolved against `baseDir` and read
@@ -194,13 +248,7 @@ function parseJudges(v, ctx, baseDir) {
194
248
  if (baseDir === undefined) {
195
249
  throw new DefError(`judge '${name}': bodyFile requires a workflow loaded from disk (no base directory to resolve '${bodyFileRel}' against)`);
196
250
  }
197
- const resolvedPath = join(baseDir, bodyFileRel);
198
- try {
199
- body = readFileSync(resolvedPath, 'utf8');
200
- }
201
- catch (e) {
202
- throw new DefError(`judge '${name}': bodyFile '${bodyFileRel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
203
- }
251
+ body = readBodyFileContained(baseDir, bodyFileRel, `judge '${name}'`);
204
252
  }
205
253
  else {
206
254
  body = asString(raw.body, `judge '${name}'.body`);
@@ -215,6 +263,12 @@ function parseJudges(v, ctx, baseDir) {
215
263
  if (raw.maxRunsPerDay !== undefined) {
216
264
  judge.maxRunsPerDay = asNumber(raw.maxRunsPerDay, DEFAULTS.maxRunsPerDay, `judge '${name}'.maxRunsPerDay`);
217
265
  }
266
+ if (raw.worker !== undefined)
267
+ judge.worker = asString(raw.worker, `judge '${name}'.worker`);
268
+ if (raw.command !== undefined)
269
+ judge.command = asString(raw.command, `judge '${name}'.command`);
270
+ if (raw.spec !== undefined)
271
+ judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
218
272
  return judge;
219
273
  });
220
274
  }
@@ -520,6 +574,8 @@ export function buildDef(raw, source, baseDir) {
520
574
  }
521
575
  if (r.x !== undefined)
522
576
  def.x = asExtension(r.x, `workflow '${name}'.x`);
577
+ if (r.workers !== undefined)
578
+ def.workers = asStringArray(r.workers, `workflow '${name}'.workers`);
523
579
  return def;
524
580
  }
525
581
  // ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
@@ -724,6 +780,12 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
724
780
  };
725
781
  if (j.model !== undefined)
726
782
  step.model = j.model;
783
+ if (j.worker !== undefined)
784
+ step.worker = j.worker;
785
+ if (j.command !== undefined)
786
+ step.command = j.command;
787
+ if (j.spec !== undefined)
788
+ step.spec = j.spec;
727
789
  return step;
728
790
  });
729
791
  }
@@ -793,13 +855,7 @@ function buildStep(rl, i, baseDir) {
793
855
  if (baseDir === undefined) {
794
856
  throw new DefError(`step '${name}': bodyFile requires a workflow loaded from disk (no base directory to resolve '${bodyFileRel}' against)`);
795
857
  }
796
- const resolvedPath = join(baseDir, bodyFileRel);
797
- try {
798
- body = readFileSync(resolvedPath, 'utf8');
799
- }
800
- catch (e) {
801
- throw new DefError(`step '${name}': bodyFile '${bodyFileRel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
802
- }
858
+ body = readBodyFileContained(baseDir, bodyFileRel, `step '${name}'`);
803
859
  }
804
860
  else {
805
861
  body = hasBody ? asString(rl.body, `step '${name}'.body`) : '';
@@ -823,6 +879,12 @@ function buildStep(rl, i, baseDir) {
823
879
  step.workdir = asString(rl.workdir, `step '${name}'.workdir`);
824
880
  if (rl.model !== undefined)
825
881
  step.model = asString(rl.model, `step '${name}'.model`);
882
+ if (rl.worker !== undefined)
883
+ step.worker = asString(rl.worker, `step '${name}'.worker`);
884
+ if (rl.command !== undefined)
885
+ step.command = asString(rl.command, `step '${name}'.command`);
886
+ if (rl.spec !== undefined)
887
+ step.spec = asExtension(rl.spec, `step '${name}'.spec`);
826
888
  if (rl.x !== undefined)
827
889
  step.x = asExtension(rl.x, `step '${name}'.x`);
828
890
  if (asBool(rl.terminal, false, `step '${name}'.terminal`))
@@ -867,6 +929,17 @@ function buildStep(rl, i, baseDir) {
867
929
  const reapTtlStr = asString(rl.reapTtl, `step '${name}'.reapTtl`);
868
930
  step.reapTtlMs = parseDurationMs(reapTtlStr);
869
931
  }
932
+ // A2: opaque routing labels. Empty list normalizes to absent (claimable by
933
+ // any caller), mirroring the groups.length > 0 pattern below.
934
+ if (rl.labels !== undefined) {
935
+ const ls = asStringArray(rl.labels, `step '${name}'.labels`);
936
+ if (ls.length > 0)
937
+ step.labels = ls;
938
+ }
939
+ // A3: per-step max total lease lifetime (duration string, same as reapTtl).
940
+ if (rl.maxLease !== undefined) {
941
+ step.maxLeaseMs = parseDurationMs(asString(rl.maxLease, `step '${name}'.maxLease`));
942
+ }
870
943
  // generates: entries may not declare judges: (they are lint-exempt side outputs,
871
944
  // not part of the step's primary contract) — hard error mirrors the calls: check above.
872
945
  for (const p of generatesPatterns) {
@@ -1013,6 +1086,43 @@ export function validateDef(def) {
1013
1086
  }
1014
1087
  }
1015
1088
  }
1089
+ // W1-VALIDATE: worker:/command: shape rules (declarative executor dispatch).
1090
+ // Only two hard requirements; any other worker value is fully opaque.
1091
+ for (const l of def.steps) {
1092
+ const worker = l.worker ?? 'agent';
1093
+ // Deliberately `l.worker === 'agent'` (explicit opt-in), NOT
1094
+ // `(l.worker ?? 'agent') === 'agent'` — that stricter form would also
1095
+ // catch every default-agent step that already gets away with an empty
1096
+ // body today (e.g. calls:-adjacent or generator-only fixtures), breaking
1097
+ // existing defs that never write `worker:` at all. Scoping the check to
1098
+ // an EXPLICIT `worker: agent` keeps every pre-existing def byte-for-byte
1099
+ // unaffected while still catching "someone opted into the agent worker
1100
+ // type and forgot a body".
1101
+ if (l.worker === 'agent' && l.body.trim() === '') {
1102
+ errors.push(`step '${l.name}' has worker 'agent' but no body: (an agent step needs a prompt)`);
1103
+ }
1104
+ else if (worker === 'command') {
1105
+ if (l.command === undefined) {
1106
+ errors.push(`step '${l.name}' has worker 'command' but no command:`);
1107
+ }
1108
+ }
1109
+ // any other worker value: opaque, no body/command requirement
1110
+ }
1111
+ // W1-VALIDATE: workers: def-level allow-list typo guard. Applied AFTER the
1112
+ // per-step `worker` default (?? 'agent') — a def declaring `workers:
1113
+ // [command]` (deliberately excluding 'agent') still fails a step that omits
1114
+ // `worker:` entirely, since its effective worker is 'agent'. This is
1115
+ // intended (the list is exhaustive once declared), documented in
1116
+ // docs/authoring.md.
1117
+ if (def.workers && def.workers.length > 0) {
1118
+ const allowed = new Set(def.workers);
1119
+ for (const l of def.steps) {
1120
+ const worker = l.worker ?? 'agent';
1121
+ if (!allowed.has(worker)) {
1122
+ errors.push(`step '${l.name}' has worker '${worker}' but workflow '${def.name}'.workers does not list it`);
1123
+ }
1124
+ }
1125
+ }
1016
1126
  // on: token validation — belt-and-suspenders over buildStep's throw
1017
1127
  for (const l of def.steps) {
1018
1128
  if (!l.on)
@@ -1373,7 +1483,28 @@ function buildDefFile(file) {
1373
1483
  * defs in the same directory (M1-SITE).
1374
1484
  */
1375
1485
  export function loadDefs(dir) {
1376
- // Phase 1: build all defs (un-expanded) from disk.
1486
+ // Phase 1 (scan) then Phase 2/3 (finalize). The two phases are split so a
1487
+ // caller that needs to MERGE raw maps from several dirs before validating
1488
+ // (e.g. the CLI's installed-defs fold-in, which must let a base def `calls:`
1489
+ // an installed def across the boundary) can run one finalize over the merged
1490
+ // raw map. For a single dir this is exactly the old inline body.
1491
+ return finalizeDefs(loadDefsUnfinalized(dir));
1492
+ }
1493
+ /**
1494
+ * Phase 1 of def loading: scan `dir` and build every workflow def UN-finalized
1495
+ * (includes not yet expanded, no cross-def / cycle validation). Loads each
1496
+ * top-level `*.yaml` / `*.yml` file (excluding a top-level `workflow.yaml`) and
1497
+ * each immediate subdirectory's `workflow.yaml`. Throws `DefError` on a
1498
+ * duplicate name WITHIN this dir. This is a pure extraction of what used to live
1499
+ * inline in `loadDefs` — `loadDefs(dir)` is exactly `finalizeDefs(loadDefsUnfinalized(dir))`.
1500
+ *
1501
+ * Exported so a caller can merge the raw maps of several dirs and run a single
1502
+ * `finalizeDefs` over the union (giving correct include-expansion and cross-def
1503
+ * `calls:` resolution across the merged boundary). This function stays a pure
1504
+ * dir-scanner: it holds NO ledger / `installed.json` knowledge (that composition
1505
+ * lives at the CLI layer where cwd and defsDir are both known).
1506
+ */
1507
+ export function loadDefsUnfinalized(dir) {
1377
1508
  const raw = new Map();
1378
1509
  const addRaw = (def, file) => {
1379
1510
  if (raw.has(def.name))
@@ -1394,7 +1525,26 @@ export function loadDefs(dir) {
1394
1525
  addRaw(buildDefFile(full), full);
1395
1526
  }
1396
1527
  }
1397
- // Phase 2: expand includes, run per-def validation, and cross-def calls: checks.
1528
+ return raw;
1529
+ }
1530
+ /**
1531
+ * Phase 2/3 of def loading, factored out so it is the ONE validator every
1532
+ * public construction path shares — the filesystem `loadDefs` above AND the
1533
+ * in-memory `createEngine({ defs })` factory path (REL-4). Given a raw def map
1534
+ * (each def possibly still carrying `_includes`), it: expands each def's
1535
+ * includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
1536
+ * key validity, exactly-one child output); runs `validateDef` per expanded def;
1537
+ * and finally `detectCallsCycles` over the whole expanded map. Returns the
1538
+ * expanded, validated map. Throws `DefError` on the first problem — the same
1539
+ * messages, in the same order, the filesystem loader has always produced (this
1540
+ * is a pure extraction of what used to live inline in `loadDefs`).
1541
+ *
1542
+ * A host wiring an `Engine` by hand with its own set can call this to get the
1543
+ * same validation the factory and the loader apply. `expandIncludes` is a no-op
1544
+ * for a def without `_includes` (the normal in-memory case), so passing a plain
1545
+ * def map through is cheap and only adds the cross-def + cycle checks.
1546
+ */
1547
+ export function finalizeDefs(raw) {
1398
1548
  const out = new Map();
1399
1549
  const resolver = (name) => raw.get(name);
1400
1550
  for (const [name, def] of raw) {