owenloop 0.3.1 → 0.4.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 +32 -0
- package/README.md +53 -1
- package/dist/add.d.ts +12 -40
- package/dist/add.js +11 -176
- package/dist/cli.d.ts +52 -7
- package/dist/cli.js +1072 -382
- package/dist/credentials.d.ts +274 -0
- package/dist/credentials.js +695 -0
- package/dist/defs.js +23 -0
- package/dist/engine.js +15 -6
- package/dist/hub.d.ts +363 -6
- package/dist/hub.js +551 -4
- package/dist/index.d.ts +4 -1
- package/dist/index.js +2 -1
- package/dist/lock.d.ts +80 -0
- package/dist/lock.js +217 -0
- package/dist/mcp/serve.d.ts +84 -0
- package/dist/mcp/serve.js +565 -0
- package/dist/mcp/server.d.ts +135 -0
- package/dist/mcp/server.js +330 -0
- package/dist/model.d.ts +59 -4
- package/dist/model.js +148 -21
- package/dist/owenwork.d.ts +57 -0
- package/dist/owenwork.js +84 -0
- package/dist/types.d.ts +48 -6
- package/dist/util.d.ts +24 -0
- package/dist/util.js +25 -0
- package/docs/authoring.md +9 -0
- package/docs/cli.md +411 -15
- package/docs/design.md +86 -12
- package/docs/embedding.md +58 -0
- package/package.json +1 -1
package/dist/model.js
CHANGED
|
@@ -391,8 +391,14 @@ function idleEligible(step, arts, time) {
|
|
|
391
391
|
* output to discharge. This is the scheduling gate (§11.4): necessary, not
|
|
392
392
|
* sufficient; the commit fingerprint (§12.2) is the correctness boundary.
|
|
393
393
|
* Assumes `pendingOwed` has already been materialized into `arts`.
|
|
394
|
+
*
|
|
395
|
+
* `opts.ignoreFreeze` (used by `modelCheck`'s stall-vs-true-deadlock
|
|
396
|
+
* recompute): when true, treat every `frozen()` guard as false — i.e.
|
|
397
|
+
* "what would be eligible if every maxAttempts/maxSchemaFailures/held brake
|
|
398
|
+
* were lifted (a human `retry` = unlimited attempts)". It ONLY lifts the
|
|
399
|
+
* freeze; group-exclusivity, input-green gates, and `isDebt` are untouched.
|
|
394
400
|
*/
|
|
395
|
-
export function eligibleFirings(def, arts, time) {
|
|
401
|
+
export function eligibleFirings(def, arts, time, opts) {
|
|
396
402
|
const firings = [];
|
|
397
403
|
for (const step of def.steps) {
|
|
398
404
|
// M2: calls: steps are machine-handled (the engine spawns the child); never emit a worker firing.
|
|
@@ -436,7 +442,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
436
442
|
if (plainSatisfied) {
|
|
437
443
|
const outs = plainOutputs(step).filter((p) => {
|
|
438
444
|
const a = arts.get(p);
|
|
439
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
445
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
440
446
|
});
|
|
441
447
|
if (outs.length) {
|
|
442
448
|
firings.push({ step: step.name, key: '', inputs: plainPaths, outputs: outs });
|
|
@@ -463,7 +469,9 @@ export function eligibleFirings(def, arts, time) {
|
|
|
463
469
|
// never be a group member today — this check is defensive, not reachable,
|
|
464
470
|
// and exists so a future relaxation of the singleton-only restriction can't
|
|
465
471
|
// silently reopen the eligibility/commit-check gap this file fixes.
|
|
466
|
-
if (!isDebt(outArt) ||
|
|
472
|
+
if (!isDebt(outArt) ||
|
|
473
|
+
(!opts?.ignoreFreeze && frozen(outArt, step)) ||
|
|
474
|
+
groupBlockingWinner(def, arts, outPath) !== undefined)
|
|
467
475
|
continue;
|
|
468
476
|
firings.push({
|
|
469
477
|
step: step.name,
|
|
@@ -494,7 +502,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
494
502
|
.map((p) => p.stem)
|
|
495
503
|
.filter((p) => {
|
|
496
504
|
const a = arts.get(p);
|
|
497
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
505
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
498
506
|
});
|
|
499
507
|
if (outs.length) {
|
|
500
508
|
firings.push({
|
|
@@ -519,7 +527,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
519
527
|
// Workflow IS all-green. Check if the evaluator still has a debt to discharge.
|
|
520
528
|
const outs = plainOutputs(step).filter((p) => {
|
|
521
529
|
const a = arts.get(p);
|
|
522
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
530
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
523
531
|
});
|
|
524
532
|
if (outs.length > 0) {
|
|
525
533
|
firings.push({
|
|
@@ -536,7 +544,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
536
544
|
if (idleEligible(step, arts, time)) {
|
|
537
545
|
const outs = plainOutputs(step).filter((p) => {
|
|
538
546
|
const a = arts.get(p);
|
|
539
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
547
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
540
548
|
});
|
|
541
549
|
if (outs.length > 0) {
|
|
542
550
|
firings.push({
|
|
@@ -561,6 +569,77 @@ function plainOutputs(step) {
|
|
|
561
569
|
out.push(sealPath(p.stem));
|
|
562
570
|
return out;
|
|
563
571
|
}
|
|
572
|
+
/**
|
|
573
|
+
* Forward stem-reachability fixpoint from the seeded workflow inputs: a step's
|
|
574
|
+
* produced stems become reachable once every one of its consumed stems is
|
|
575
|
+
* reachable. Intentionally duplicates defs.ts's `reachabilityErrors` fixpoint
|
|
576
|
+
* rather than importing it — defs.ts does not import model.ts and model.ts
|
|
577
|
+
* does not import defs.ts; canEverFire's discharge-set logic (below) depends
|
|
578
|
+
* on model.ts's own mode helpers, so importing across the boundary either way
|
|
579
|
+
* would create a cycle. This local copy keeps the import graph acyclic.
|
|
580
|
+
*/
|
|
581
|
+
function reachableStems(def) {
|
|
582
|
+
const reachable = new Set(def.inputs.map((i) => i.name));
|
|
583
|
+
let changed = true;
|
|
584
|
+
while (changed) {
|
|
585
|
+
changed = false;
|
|
586
|
+
for (const step of def.steps) {
|
|
587
|
+
if (!step.consumes.every((c) => reachable.has(c.stem)))
|
|
588
|
+
continue;
|
|
589
|
+
for (const p of step.produces) {
|
|
590
|
+
if (!reachable.has(p.stem)) {
|
|
591
|
+
reachable.add(p.stem);
|
|
592
|
+
changed = true;
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
return reachable;
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Pure static predicate: can `step` EVER fire, under ANY search bounds?
|
|
601
|
+
*
|
|
602
|
+
* A SOUND detector of deadness: returns false ONLY when we are CERTAIN no
|
|
603
|
+
* firing can ever be pushed for this step, mirroring the discharge-set logic
|
|
604
|
+
* `eligibleFirings` (above) actually uses. When uncertain, returns true (the
|
|
605
|
+
* safe, non-failing default) — a false "structurally dead" would wrongly make
|
|
606
|
+
* `check` exit nonzero, so soundness is biased toward under-reporting.
|
|
607
|
+
*
|
|
608
|
+
* - Reachability: if any consumed stem is not reachable from the workflow
|
|
609
|
+
* inputs (see `reachableStems`), the step can never fire. Belt-and-suspenders
|
|
610
|
+
* — `validateDef`'s `reachabilityErrors` already turns this into a hard error
|
|
611
|
+
* before `modelCheck` ever runs, so this arm is defensive, not the live path.
|
|
612
|
+
* - Judge step (`step.judges`): fires against the judged stem, not a produces
|
|
613
|
+
* set; can-fire iff the judged stem is reachable (already implied by the
|
|
614
|
+
* reachability arm above, since a judge step consumes the judged stem — kept
|
|
615
|
+
* explicit for clarity and to stay correct if judge-step synthesis changes).
|
|
616
|
+
* - reduce: the discharge set is `singletonProduces(step)` only (see the
|
|
617
|
+
* reduce branch of `eligibleFirings`) — zero singleton produces means no
|
|
618
|
+
* firing is ever pushed, regardless of bounds.
|
|
619
|
+
* - map: needs both a map-consume and a map-produce to bind an element.
|
|
620
|
+
* - plain (inputsGreen / allGreen / idle): the discharge set is `plainOutputs`
|
|
621
|
+
* (singleton produces + collection seals) — empty means no firing ever.
|
|
622
|
+
*
|
|
623
|
+
* `reachable` may be precomputed once by the caller and passed in (modelCheck
|
|
624
|
+
* calls this per dead step and must not recompute the fixpoint each time).
|
|
625
|
+
*/
|
|
626
|
+
export function canEverFire(step, def, reachable) {
|
|
627
|
+
const reach = reachable ?? reachableStems(def);
|
|
628
|
+
if (!step.consumes.every((c) => reach.has(c.stem)))
|
|
629
|
+
return false;
|
|
630
|
+
if (step.judges)
|
|
631
|
+
return reach.has(step.judges);
|
|
632
|
+
switch (stepMode(step)) {
|
|
633
|
+
case 'reduce':
|
|
634
|
+
return singletonProduces(step).length > 0;
|
|
635
|
+
case 'map':
|
|
636
|
+
return !!mapProduce(step) && !!mapConsume(step);
|
|
637
|
+
case 'plain':
|
|
638
|
+
return plainOutputs(step).length > 0;
|
|
639
|
+
default:
|
|
640
|
+
return true; // not certain of deadness — default to can-fire (soundness bias)
|
|
641
|
+
}
|
|
642
|
+
}
|
|
564
643
|
// ---- level-triggered maintenance (§11.8, §12.3) -----------------------------
|
|
565
644
|
/**
|
|
566
645
|
* The standing guard: re-derive the invariant "an artifact is green only while
|
|
@@ -1525,6 +1604,9 @@ function seedArts(def, assumeProvided = false) {
|
|
|
1525
1604
|
// seedOwed=false → seed green (version 1); seedOwed=true → seed owed (version 0)
|
|
1526
1605
|
// The checker has no runtime `provide` values, so seedOwed inputs start owed —
|
|
1527
1606
|
// unless assumeProvided, which models "the operator ran `provide` at create".
|
|
1607
|
+
// This function's own default stays false; the `owenloop check` CLI command
|
|
1608
|
+
// now passes assumeProvided: true by default (its `--strict-inputs` flag
|
|
1609
|
+
// passes false to restore this owed-start behavior) — see CheckOptions.
|
|
1528
1610
|
const seedGreen = !input.seedOwed || assumeProvided;
|
|
1529
1611
|
arts.set(input.name, {
|
|
1530
1612
|
workflow: '',
|
|
@@ -1857,10 +1939,29 @@ function canonicalKey(def, arts) {
|
|
|
1857
1939
|
* Bounded reachability / liveness checker over a workflow definition.
|
|
1858
1940
|
*
|
|
1859
1941
|
* Explores the full (or depth/state-bounded) state space via BFS to find:
|
|
1860
|
-
* -
|
|
1861
|
-
*
|
|
1942
|
+
* - a non-done, zero-eligible-firings state is split into exactly ONE of two
|
|
1943
|
+
* mutually exclusive buckets by recomputing eligibility with every freeze
|
|
1944
|
+
* lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
|
|
1945
|
+
* - stall states: the recompute yields >= 1 firing — the state's only
|
|
1946
|
+
* blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
|
|
1947
|
+
* held). A by-design human-escalation brake. EXPECTED, never a defect.
|
|
1948
|
+
* - true deadlocks: the recompute STILL yields zero firings — a genuine
|
|
1949
|
+
* structural dead-end with no path to completion even at unlimited
|
|
1950
|
+
* attempts. A real defect.
|
|
1951
|
+
* - stuck states: reachable states that have a stalled debt but STILL have
|
|
1952
|
+
* >= 1 eligible firing elsewhere (a brake tripped on one branch while the
|
|
1953
|
+
* line moves on another). Informational only; a no-moves state is never
|
|
1954
|
+
* listed here — it lands in `stallStates` or `deadlocks` instead, so no
|
|
1955
|
+
* state is ever double-listed.
|
|
1862
1956
|
* - completability: whether any reachable state is done (with an example path)
|
|
1863
|
-
* - dead steps: steps whose name never appears as a firing in any explored
|
|
1957
|
+
* - dead steps: steps whose name never appears as a firing in any explored
|
|
1958
|
+
* transition. Split into two categories by the static `canEverFire` check
|
|
1959
|
+
* (independent of search bounds):
|
|
1960
|
+
* - structurally-dead: `canEverFire` is false — the step can NEVER fire
|
|
1961
|
+
* regardless of `--max-depth`/`--max-states`. A genuine wiring defect.
|
|
1962
|
+
* - unreached-within-bounds: `canEverFire` is true — the step CAN fire in
|
|
1963
|
+
* principle but the bounded search didn't reach it. A bounds artifact,
|
|
1964
|
+
* not a defect; raising `--max-states`/`--max-depth` may surface it.
|
|
1864
1965
|
*
|
|
1865
1966
|
* Pure — no store, no engine, no IO.
|
|
1866
1967
|
*/
|
|
@@ -1878,10 +1979,12 @@ export function modelCheck(def, opts = {}) {
|
|
|
1878
1979
|
bounded: false,
|
|
1879
1980
|
boundsHit: [],
|
|
1880
1981
|
deadlocks: [],
|
|
1982
|
+
stallStates: [],
|
|
1881
1983
|
stuck: [],
|
|
1882
1984
|
completable: false,
|
|
1883
1985
|
completePath: undefined,
|
|
1884
|
-
|
|
1986
|
+
structurallyDeadSteps: [],
|
|
1987
|
+
unreachedSteps: [],
|
|
1885
1988
|
invariantViolations: [],
|
|
1886
1989
|
stats: { statesExplored: 0, depthReached: 0 },
|
|
1887
1990
|
};
|
|
@@ -1926,17 +2029,29 @@ export function modelCheck(def, opts = {}) {
|
|
|
1926
2029
|
}
|
|
1927
2030
|
continue; // done states have no successors
|
|
1928
2031
|
}
|
|
1929
|
-
// Check stuck (any debt.stalled)
|
|
1930
|
-
if (status.debts.some((d) => d.stalled)) {
|
|
1931
|
-
report.stuck.push({ path: node.path });
|
|
1932
|
-
// continue exploring (there may be other paths)
|
|
1933
|
-
}
|
|
1934
2032
|
const firings = status.eligible;
|
|
1935
|
-
//
|
|
2033
|
+
// Non-done state with no eligible firings: classify by recomputing eligibility
|
|
2034
|
+
// as if every freeze/stall were lifted (unlimited attempts). If a producer
|
|
2035
|
+
// would re-arm → an EXPECTED stall state (a by-design brake). If not → a
|
|
2036
|
+
// TRUE deadlock (a structural dead-end with no path to completion even at
|
|
2037
|
+
// unlimited attempts).
|
|
1936
2038
|
if (firings.length === 0 && !status.done) {
|
|
1937
|
-
|
|
2039
|
+
const lifted = eligibleFirings(def, node.arts, undefined, { ignoreFreeze: true });
|
|
2040
|
+
if (lifted.length > 0) {
|
|
2041
|
+
report.stallStates.push({ path: node.path });
|
|
2042
|
+
}
|
|
2043
|
+
else {
|
|
2044
|
+
report.deadlocks.push({ path: node.path });
|
|
2045
|
+
}
|
|
1938
2046
|
continue;
|
|
1939
2047
|
}
|
|
2048
|
+
// The state HAS eligible firings (the line can still move). If a brake tripped
|
|
2049
|
+
// on some *other* branch, record it as an informational stuck state. A no-moves
|
|
2050
|
+
// stall state never reaches here (it `continue`d above), so no state is ever
|
|
2051
|
+
// listed in both `stuck` and `stallStates`/`deadlocks`.
|
|
2052
|
+
if (status.debts.some((d) => d.stalled)) {
|
|
2053
|
+
report.stuck.push({ path: node.path });
|
|
2054
|
+
}
|
|
1940
2055
|
// Respect maxDepth
|
|
1941
2056
|
if (node.depth >= maxDepth) {
|
|
1942
2057
|
boundsHit.add('maxDepth');
|
|
@@ -1970,9 +2085,21 @@ export function modelCheck(def, opts = {}) {
|
|
|
1970
2085
|
report.stats.depthReached = depthReached;
|
|
1971
2086
|
report.boundsHit = [...boundsHit];
|
|
1972
2087
|
report.bounded = boundsHit.size > 0;
|
|
1973
|
-
// Dead steps: steps in the def that never appeared as a firing.step
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
2088
|
+
// Dead steps: steps in the def that never appeared as a firing.step, split
|
|
2089
|
+
// by the static canEverFire check into structurally-dead (a real wiring
|
|
2090
|
+
// defect — can never fire regardless of bounds) vs unreached-within-bounds
|
|
2091
|
+
// (can fire in principle; the bounded search just didn't reach it).
|
|
2092
|
+
// Compute the reachability fixpoint once, not per dead step.
|
|
2093
|
+
const reachable = reachableStems(def);
|
|
2094
|
+
for (const l of def.steps) {
|
|
2095
|
+
if (firedSteps.has(l.name))
|
|
2096
|
+
continue;
|
|
2097
|
+
if (canEverFire(l, def, reachable)) {
|
|
2098
|
+
report.unreachedSteps.push(l.name);
|
|
2099
|
+
}
|
|
2100
|
+
else {
|
|
2101
|
+
report.structurallyDeadSteps.push(l.name);
|
|
2102
|
+
}
|
|
2103
|
+
}
|
|
1977
2104
|
return report;
|
|
1978
2105
|
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* owenwork settings file writer — the ONE place the owenloop CLI writes into a
|
|
3
|
+
* sibling tool's config.
|
|
4
|
+
*
|
|
5
|
+
* `owenwork` (the wiring that runs orders) reads its settings from
|
|
6
|
+
* `$XDG_CONFIG_HOME/owenwork/settings.json` (else `$HOME/.config/owenwork/
|
|
7
|
+
* settings.json`) and, by design, NEVER writes them — the owenloop CLI's `setup`
|
|
8
|
+
* command is the writer, so a fresh `owenloop setup` can point owenwork at the
|
|
9
|
+
* hub it just authenticated against.
|
|
10
|
+
*
|
|
11
|
+
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
+
* key byte-for-byte (forward-compat with owenwork's own `cacheDir`, `agentsDir`,
|
|
13
|
+
* `stateDir`, `dispatchCap`, `commandRouting`, and any future/unknown key). It
|
|
14
|
+
* never writes a secret: nothing secret is in scope here by construction (the
|
|
15
|
+
* hub ORIGIN is public).
|
|
16
|
+
*
|
|
17
|
+
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
|
+
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
+
* it cannot safely merge into. That mirrors owenwork's own validator wording
|
|
20
|
+
* family ("not an object").
|
|
21
|
+
*
|
|
22
|
+
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
|
+
* util.ts — no CLI/engine closure.
|
|
24
|
+
*/
|
|
25
|
+
/**
|
|
26
|
+
* The owenwork settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
27
|
+
* set and non-blank) wins over `HOME`, matching owenwork's own resolution and
|
|
28
|
+
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
29
|
+
*/
|
|
30
|
+
export declare function owenworkSettingsPath(env: Record<string, string | undefined>): string;
|
|
31
|
+
/**
|
|
32
|
+
* Read and parse the owenwork settings file at `path`.
|
|
33
|
+
*
|
|
34
|
+
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
35
|
+
* creates one).
|
|
36
|
+
* - Present and parses to a JSON OBJECT → that object (a `Record`).
|
|
37
|
+
* - Present but not valid JSON, or valid JSON that is NOT an object (an array,
|
|
38
|
+
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
39
|
+
* must never clobber a file it cannot merge into.
|
|
40
|
+
*/
|
|
41
|
+
export declare function readOwenworkSettingsRaw(path: string): Record<string, unknown> | null;
|
|
42
|
+
/** The outcome of a `writeOwenworkHubOrigin` call — the path written and the
|
|
43
|
+
* previous `hubOrigin` value (`undefined` when the key was absent or the file
|
|
44
|
+
* did not exist), so a caller can report an old→new transition. */
|
|
45
|
+
export interface OwenworkWriteResult {
|
|
46
|
+
path: string;
|
|
47
|
+
previous: string | undefined;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Set ONLY the `hubOrigin` key in the owenwork settings file to `origin`,
|
|
51
|
+
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
52
|
+
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
53
|
+
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
54
|
+
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
55
|
+
* previous `hubOrigin` (if any).
|
|
56
|
+
*/
|
|
57
|
+
export declare function writeOwenworkHubOrigin(env: Record<string, string | undefined>, origin: string): OwenworkWriteResult;
|
package/dist/owenwork.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* owenwork settings file writer — the ONE place the owenloop CLI writes into a
|
|
3
|
+
* sibling tool's config.
|
|
4
|
+
*
|
|
5
|
+
* `owenwork` (the wiring that runs orders) reads its settings from
|
|
6
|
+
* `$XDG_CONFIG_HOME/owenwork/settings.json` (else `$HOME/.config/owenwork/
|
|
7
|
+
* settings.json`) and, by design, NEVER writes them — the owenloop CLI's `setup`
|
|
8
|
+
* command is the writer, so a fresh `owenloop setup` can point owenwork at the
|
|
9
|
+
* hub it just authenticated against.
|
|
10
|
+
*
|
|
11
|
+
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
+
* key byte-for-byte (forward-compat with owenwork's own `cacheDir`, `agentsDir`,
|
|
13
|
+
* `stateDir`, `dispatchCap`, `commandRouting`, and any future/unknown key). It
|
|
14
|
+
* never writes a secret: nothing secret is in scope here by construction (the
|
|
15
|
+
* hub ORIGIN is public).
|
|
16
|
+
*
|
|
17
|
+
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
|
+
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
+
* it cannot safely merge into. That mirrors owenwork's own validator wording
|
|
20
|
+
* family ("not an object").
|
|
21
|
+
*
|
|
22
|
+
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
|
+
* util.ts — no CLI/engine closure.
|
|
24
|
+
*/
|
|
25
|
+
import { existsSync, mkdirSync, readFileSync } from 'node:fs';
|
|
26
|
+
import { dirname, join } from 'node:path';
|
|
27
|
+
import { writeFileAtomic } from "./hub.js";
|
|
28
|
+
import { CliError } from "./util.js";
|
|
29
|
+
/**
|
|
30
|
+
* The owenwork settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
31
|
+
* set and non-blank) wins over `HOME`, matching owenwork's own resolution and
|
|
32
|
+
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
33
|
+
*/
|
|
34
|
+
export function owenworkSettingsPath(env) {
|
|
35
|
+
const xdg = env.XDG_CONFIG_HOME;
|
|
36
|
+
if (xdg && xdg.trim() !== '')
|
|
37
|
+
return join(xdg, 'owenwork', 'settings.json');
|
|
38
|
+
const home = env.HOME;
|
|
39
|
+
if (home && home.trim() !== '')
|
|
40
|
+
return join(home, '.config', 'owenwork', 'settings.json');
|
|
41
|
+
throw new CliError('cannot locate a config directory for owenwork settings: set HOME or XDG_CONFIG_HOME');
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Read and parse the owenwork settings file at `path`.
|
|
45
|
+
*
|
|
46
|
+
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
47
|
+
* creates one).
|
|
48
|
+
* - Present and parses to a JSON OBJECT → that object (a `Record`).
|
|
49
|
+
* - Present but not valid JSON, or valid JSON that is NOT an object (an array,
|
|
50
|
+
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
51
|
+
* must never clobber a file it cannot merge into.
|
|
52
|
+
*/
|
|
53
|
+
export function readOwenworkSettingsRaw(path) {
|
|
54
|
+
if (!existsSync(path))
|
|
55
|
+
return null;
|
|
56
|
+
let parsed;
|
|
57
|
+
try {
|
|
58
|
+
parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
throw new CliError(`owenwork settings file at ${path} is not valid JSON — fix or remove it before running setup`);
|
|
62
|
+
}
|
|
63
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
64
|
+
throw new CliError(`owenwork settings file at ${path} is not a JSON object — fix or remove it before running setup`);
|
|
65
|
+
}
|
|
66
|
+
return parsed;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Set ONLY the `hubOrigin` key in the owenwork settings file to `origin`,
|
|
70
|
+
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
71
|
+
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
72
|
+
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
73
|
+
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
74
|
+
* previous `hubOrigin` (if any).
|
|
75
|
+
*/
|
|
76
|
+
export function writeOwenworkHubOrigin(env, origin) {
|
|
77
|
+
const path = owenworkSettingsPath(env);
|
|
78
|
+
const existing = readOwenworkSettingsRaw(path);
|
|
79
|
+
const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
|
|
80
|
+
const merged = { ...(existing ?? {}), hubOrigin: origin };
|
|
81
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
82
|
+
writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`);
|
|
83
|
+
return { path, previous };
|
|
84
|
+
}
|
package/dist/types.d.ts
CHANGED
|
@@ -556,7 +556,12 @@ export interface CheckOptions {
|
|
|
556
556
|
* Seed `seedOwed: true` inputs green, as if `provide` already ran. The checker
|
|
557
557
|
* has no runtime provide values, so without this every seedOwed input starts
|
|
558
558
|
* owed with no transition that can green it — a def whose inputs the operator
|
|
559
|
-
* supplies at create time reports a false depth-0 deadlock. Default
|
|
559
|
+
* supplies at create time reports a false depth-0 deadlock. Default (this
|
|
560
|
+
* field, when calling `modelCheck` directly) is false — that library default
|
|
561
|
+
* is unchanged. The `owenloop check` CLI command, however, now defaults this
|
|
562
|
+
* to true (seedOwed inputs are assumed provided by default, modeling the
|
|
563
|
+
* operator's `provide` at create); its `--strict-inputs` flag opts back out
|
|
564
|
+
* to false, restoring the seedOwed-starts-owed behavior described above.
|
|
560
565
|
*/
|
|
561
566
|
assumeProvided?: boolean;
|
|
562
567
|
}
|
|
@@ -567,18 +572,55 @@ export interface CheckReport {
|
|
|
567
572
|
bounded: boolean;
|
|
568
573
|
/** Which bounds were hit, for honest reporting. */
|
|
569
574
|
boundsHit: ('maxDepth' | 'maxStates')[];
|
|
570
|
-
/**
|
|
575
|
+
/**
|
|
576
|
+
* Reachable non-done states with zero eligible firings that have NO path to
|
|
577
|
+
* completion even at unlimited attempts — i.e. recomputing eligibility with
|
|
578
|
+
* all freezes lifted (a human `retry` = unlimited attempts) STILL yields
|
|
579
|
+
* zero firings. A genuine structural dead-end (TRUE deadlock). A definite
|
|
580
|
+
* defect only when the search was exhaustive (`!bounded`) — the
|
|
581
|
+
* maxCollectionSize cap can otherwise manufacture a spurious no-moves
|
|
582
|
+
* state. Always present ([] when none).
|
|
583
|
+
*/
|
|
571
584
|
deadlocks: CheckFinding[];
|
|
572
|
-
/**
|
|
585
|
+
/**
|
|
586
|
+
* Reachable non-done states with zero eligible firings whose ONLY blocker
|
|
587
|
+
* is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held).
|
|
588
|
+
* Recomputing eligibility with all freezes lifted (a human `retry` =
|
|
589
|
+
* unlimited attempts) yields >= 1 firing, so a producer would re-arm and
|
|
590
|
+
* the line could move. These are the DESIGNED human-escalation brakes —
|
|
591
|
+
* EXPECTED, never a defect; they do not affect the exit code. Always
|
|
592
|
+
* present ([] when none).
|
|
593
|
+
*/
|
|
594
|
+
stallStates: CheckFinding[];
|
|
595
|
+
/**
|
|
596
|
+
* Reachable states that have a stalled debt (maxAttempts/maxSchemaFailures/
|
|
597
|
+
* held) BUT still have >= 1 eligible firing — a brake tripped on one branch
|
|
598
|
+
* while the line can still move on another. Informational; NOT a defect on
|
|
599
|
+
* its own. A no-moves state whose only blocker is a frozen debt is recorded
|
|
600
|
+
* under `stallStates` instead, never here — so no state appears in both
|
|
601
|
+
* `stuck` and `stallStates`/`deadlocks`.
|
|
602
|
+
*/
|
|
573
603
|
stuck: CheckFinding[];
|
|
574
604
|
/** Whether any explored state is done, and (when true) one example path to it. */
|
|
575
605
|
completable: boolean;
|
|
576
606
|
completePath?: CheckStep[];
|
|
577
607
|
/**
|
|
578
|
-
* Step names that never appear as the firing step in any explored transition
|
|
579
|
-
*
|
|
608
|
+
* Step names that never appear as the firing step in any explored transition,
|
|
609
|
+
* AND a static "can this step ever fire?" check (independent of bounds) is
|
|
610
|
+
* CERTAIN no firing can ever be pushed for it (see model.ts `canEverFire`).
|
|
611
|
+
* A genuine wiring defect — always present ([] when none), and (unlike
|
|
612
|
+
* `unreachedSteps`) ALWAYS a definite finding regardless of `bounded`,
|
|
613
|
+
* because the check needs no search bounds to be certain.
|
|
614
|
+
*/
|
|
615
|
+
structurallyDeadSteps: string[];
|
|
616
|
+
/**
|
|
617
|
+
* Step names that never appear as the firing step in any explored transition,
|
|
618
|
+
* but the static `canEverFire` check says they COULD fire in principle — the
|
|
619
|
+
* bounded search just didn't reach them before exhausting `--max-states`/
|
|
620
|
+
* `--max-depth`. Informational only, NOT a defect: a bounds artifact. Raising
|
|
621
|
+
* the search bounds may make the step fire. Always present ([] when none).
|
|
580
622
|
*/
|
|
581
|
-
|
|
623
|
+
unreachedSteps: string[];
|
|
582
624
|
/**
|
|
583
625
|
* Invariants that are violated in some reachable state. Always present ([]
|
|
584
626
|
* when no invariants declared or none violated). Each entry is deduplicated by
|
package/dist/util.d.ts
CHANGED
|
@@ -1,4 +1,28 @@
|
|
|
1
1
|
/** Small dependency-light helpers. */
|
|
2
|
+
/**
|
|
3
|
+
* A user-facing CLI/library error whose `message` is printed as-is (no stack
|
|
4
|
+
* trace) — the "expected, explained" failure class, distinct from a programming
|
|
5
|
+
* bug. Homed here in `util.ts` (which has no project-internal imports) so it can
|
|
6
|
+
* be shared by `cli.ts` (where `RateLimitError extends CliError`) and
|
|
7
|
+
* `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
|
|
8
|
+
* cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
|
|
9
|
+
* NOT re-exported from the package barrel (`src/index.ts`): it was module-private
|
|
10
|
+
* before, and the credential-write PR does not widen the public API beyond the
|
|
11
|
+
* functions the proposal names.
|
|
12
|
+
*
|
|
13
|
+
* `exitCode` lets a specific failure map to a distinct process exit status
|
|
14
|
+
* (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
|
|
15
|
+
* every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
|
|
16
|
+
* which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
|
|
17
|
+
* non-default codes today are `agent new`'s exit 2 (hub unresolvable) and exit 3
|
|
18
|
+
* (human credential absent/irrecoverable).
|
|
19
|
+
*/
|
|
20
|
+
export declare class CliError extends Error {
|
|
21
|
+
readonly exitCode: number;
|
|
22
|
+
constructor(message: string, opts?: {
|
|
23
|
+
exitCode?: number;
|
|
24
|
+
});
|
|
25
|
+
}
|
|
2
26
|
/**
|
|
3
27
|
* `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
|
|
4
28
|
* create it through a symlinked component (SEC-3, parent-directory half).
|
package/dist/util.js
CHANGED
|
@@ -1,6 +1,31 @@
|
|
|
1
1
|
/** Small dependency-light helpers. */
|
|
2
2
|
import { createHash, randomBytes } from 'node:crypto';
|
|
3
3
|
import { lstatSync, mkdirSync } from 'node:fs';
|
|
4
|
+
/**
|
|
5
|
+
* A user-facing CLI/library error whose `message` is printed as-is (no stack
|
|
6
|
+
* trace) — the "expected, explained" failure class, distinct from a programming
|
|
7
|
+
* bug. Homed here in `util.ts` (which has no project-internal imports) so it can
|
|
8
|
+
* be shared by `cli.ts` (where `RateLimitError extends CliError`) and
|
|
9
|
+
* `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
|
|
10
|
+
* cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
|
|
11
|
+
* NOT re-exported from the package barrel (`src/index.ts`): it was module-private
|
|
12
|
+
* before, and the credential-write PR does not widen the public API beyond the
|
|
13
|
+
* functions the proposal names.
|
|
14
|
+
*
|
|
15
|
+
* `exitCode` lets a specific failure map to a distinct process exit status
|
|
16
|
+
* (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
|
|
17
|
+
* every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
|
|
18
|
+
* which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
|
|
19
|
+
* non-default codes today are `agent new`'s exit 2 (hub unresolvable) and exit 3
|
|
20
|
+
* (human credential absent/irrecoverable).
|
|
21
|
+
*/
|
|
22
|
+
export class CliError extends Error {
|
|
23
|
+
exitCode;
|
|
24
|
+
constructor(message, opts) {
|
|
25
|
+
super(message);
|
|
26
|
+
this.exitCode = opts?.exitCode ?? 1;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
4
29
|
/**
|
|
5
30
|
* `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
|
|
6
31
|
* create it through a symlinked component (SEC-3, parent-directory half).
|
package/docs/authoring.md
CHANGED
|
@@ -441,6 +441,11 @@ By default a step fires when its consumed inputs are all green (`inputsGreen`).
|
|
|
441
441
|
# order.cause is 'allGreen' when done, 'idle' when stuck past 30m
|
|
442
442
|
```
|
|
443
443
|
|
|
444
|
+
An `allGreen`/`idle` step must not also declare `consumes:` — both firing kinds
|
|
445
|
+
carry an empty input fingerprint, so a commit can never satisfy it, and
|
|
446
|
+
`owenloop lint` hard-errors on it. Declare the step's output under
|
|
447
|
+
`produces:`/`generates:` only.
|
|
448
|
+
|
|
444
449
|
**Alarms.** A worker that needs a heartbeat or a deadline can call
|
|
445
450
|
`engine.setAlarm(workflow, step, at)` with an absolute timestamp — it overrides the
|
|
446
451
|
relative `idleAfter` window and survives a process restart.
|
|
@@ -460,6 +465,10 @@ relative `idleAfter` window and survives a process restart.
|
|
|
460
465
|
A step consumes in exactly one mode — plain, a single map, or a single reduce. The
|
|
461
466
|
validator enforces this at load time, so you don't hit it as a runtime surprise.
|
|
462
467
|
|
|
468
|
+
A reduce step needs at least one singleton produce (via `produces:` or `generates:`)
|
|
469
|
+
to discharge into — reducing into collection produces only leaves nothing for the
|
|
470
|
+
step to fire, and `owenloop lint` hard-errors on it.
|
|
471
|
+
|
|
463
472
|
Collections add fan-out/fan-in on top of the base grammar: a step emits N
|
|
464
473
|
items, a `map` runs once per item, a `reduce` runs once they're all in, and a
|
|
465
474
|
suffixed reduce (`src[*].child`) can fan in on a map's per-element output
|