owenloop 0.5.3 → 0.5.5
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 +25 -0
- package/README.md +6 -2
- package/dist/packages/work/src/agent/brief.d.ts +6 -0
- package/dist/packages/work/src/agent/brief.js +102 -2
- package/dist/packages/work/src/agent/loop.d.ts +10 -1
- package/dist/packages/work/src/agent/loop.js +28 -0
- package/dist/packages/work/src/agent/workdir.d.ts +22 -0
- package/dist/packages/work/src/agent/workdir.js +80 -0
- package/dist/packages/work/src/exec/loop.d.ts +13 -1
- package/dist/packages/work/src/exec/loop.js +184 -9
- package/dist/packages/work/src/harness/child-env.js +8 -0
- package/dist/packages/work/src/harness/claude.js +25 -6
- package/dist/packages/work/src/harness/codex.js +7 -0
- package/dist/packages/work/src/harness/contract.d.ts +22 -3
- package/dist/packages/work/src/harness/contract.js +22 -3
- package/dist/packages/work/src/hold/mcp.d.ts +11 -2
- package/dist/packages/work/src/hold/mcp.js +69 -2
- package/dist/packages/work/src/hub/client.d.ts +8 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +29 -0
- package/dist/packages/work/src/roles/agent-run.js +9 -1
- package/dist/packages/work/src/roles/exec.js +9 -0
- package/dist/packages/work/src/roles/shift.js +9 -1
- package/dist/packages/work/src/settings/settings.d.ts +32 -5
- package/dist/packages/work/src/settings/settings.js +37 -12
- package/dist/packages/work/src/shift/runtime.d.ts +7 -0
- package/dist/packages/work/src/shift/runtime.js +29 -4
- package/dist/packages/work/src/shift/spawn.d.ts +12 -2
- package/dist/packages/work/src/shift/spawn.js +16 -3
- package/dist/src/cli.js +257 -7
- package/dist/src/config-dir.d.ts +62 -0
- package/dist/src/config-dir.js +87 -0
- package/dist/src/crypto/trust-roots.d.ts +8 -4
- package/dist/src/crypto/trust-roots.js +18 -12
- package/dist/src/defs.js +57 -16
- package/dist/src/engine.d.ts +46 -1
- package/dist/src/engine.js +97 -3
- package/dist/src/hub.d.ts +5 -1
- package/dist/src/hub.js +7 -8
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/model.d.ts +29 -5
- package/dist/src/model.js +63 -14
- package/dist/src/paths.d.ts +47 -4
- package/dist/src/paths.js +36 -5
- package/dist/src/types.d.ts +8 -2
- package/dist/src/work-settings.d.ts +8 -5
- package/dist/src/work-settings.js +15 -12
- package/docs/authoring.md +40 -13
- package/docs/bundles.md +9 -0
- package/docs/cli.md +155 -24
- package/docs/crypto.md +8 -8
- package/docs/design.md +20 -2
- package/docs/embedding.md +5 -4
- package/docs/wire-contracts.md +3 -2
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Resolution of the local SSHSIG trust root used for workflow publications.
|
|
3
3
|
*
|
|
4
|
-
* The path is derived only from injected environment state
|
|
5
|
-
*
|
|
6
|
-
* directory lookup is allowed here. An absent file is
|
|
4
|
+
* The path is derived only from injected environment state, through the shared
|
|
5
|
+
* `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `XDG_CONFIG_HOME` >
|
|
6
|
+
* `HOME`); no ambient home directory lookup is allowed here. An absent file is
|
|
7
|
+
* a normal result so the
|
|
7
8
|
* publication verifier can classify it as `unverifiable` instead of confusing
|
|
8
9
|
* a missing trust root with an unsigned bundle.
|
|
9
10
|
*/
|
|
@@ -17,7 +18,10 @@ export interface AllowedSignersAbsent {
|
|
|
17
18
|
path: string;
|
|
18
19
|
}
|
|
19
20
|
export type AllowedSignersResolution = AllowedSignersPresent | AllowedSignersAbsent;
|
|
20
|
-
/**
|
|
21
|
+
/**
|
|
22
|
+
* Resolve `<owenloop config dir>/allowed_signers` from caller-supplied env,
|
|
23
|
+
* through the one shared ladder in `../config-dir.ts`.
|
|
24
|
+
*/
|
|
21
25
|
export declare function allowedSignersPath(env: Record<string, string | undefined>): string;
|
|
22
26
|
/**
|
|
23
27
|
* Read the trust root without collapsing absence and malformed contents. A
|
|
@@ -1,23 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Resolution of the local SSHSIG trust root used for workflow publications.
|
|
3
3
|
*
|
|
4
|
-
* The path is derived only from injected environment state
|
|
5
|
-
*
|
|
6
|
-
* directory lookup is allowed here. An absent file is
|
|
4
|
+
* The path is derived only from injected environment state, through the shared
|
|
5
|
+
* `owenloopConfigDir` ladder (`OWENLOOP_CONFIG_DIR` > `XDG_CONFIG_HOME` >
|
|
6
|
+
* `HOME`); no ambient home directory lookup is allowed here. An absent file is
|
|
7
|
+
* a normal result so the
|
|
7
8
|
* publication verifier can classify it as `unverifiable` instead of confusing
|
|
8
9
|
* a missing trust root with an unsigned bundle.
|
|
9
10
|
*/
|
|
10
11
|
import { existsSync, lstatSync, readFileSync } from 'node:fs';
|
|
11
|
-
import {
|
|
12
|
-
/**
|
|
12
|
+
import { owenloopConfigFile } from "../config-dir.js";
|
|
13
|
+
/**
|
|
14
|
+
* Resolve `<owenloop config dir>/allowed_signers` from caller-supplied env,
|
|
15
|
+
* through the one shared ladder in `../config-dir.ts`.
|
|
16
|
+
*/
|
|
13
17
|
export function allowedSignersPath(env) {
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
try {
|
|
19
|
+
return owenloopConfigFile(env, 'allowed_signers');
|
|
20
|
+
}
|
|
21
|
+
catch (err) {
|
|
22
|
+
// Keep this resolver's own subject in the message. The shared ladder names
|
|
23
|
+
// the VARIABLES; this prefix names WHICH path could not be located, which
|
|
24
|
+
// is what the publication verifier reports to the operator.
|
|
25
|
+
throw new Error(`cannot locate an allowed_signers path: ${err instanceof Error ? err.message : String(err)}`);
|
|
26
|
+
}
|
|
21
27
|
}
|
|
22
28
|
/**
|
|
23
29
|
* Read the trust root without collapsing absence and malformed contents. A
|
package/dist/src/defs.js
CHANGED
|
@@ -667,8 +667,15 @@ export function buildDef(raw, source, baseDir) {
|
|
|
667
667
|
* Prefix all names/stems in a StepDef with `${prefix}.`. Pure — returns a new StepDef.
|
|
668
668
|
* Rewrites: step name, consume stems, produce stems, generates stems, invalidates, and
|
|
669
669
|
* effect.onInvalidate step-name strings (but not 'pin'/'escalate').
|
|
670
|
+
*
|
|
671
|
+
* `defInputs` is the INCLUDED definition's declared input names, unprefixed. A
|
|
672
|
+
* `workdirFrom` stem may name one of those instead of one of the step's own
|
|
673
|
+
* consumes, and that stem is prefixed exactly like a consume stem is, because
|
|
674
|
+
* an unmapped child input is hoisted into the parent under `${prefix}.${name}`.
|
|
675
|
+
* Omitting the list would leave such a stem unparseable here and therefore
|
|
676
|
+
* silently unprefixed, pointing at a stem the expanded definition does not have.
|
|
670
677
|
*/
|
|
671
|
-
function prefixStep(step, prefix) {
|
|
678
|
+
function prefixStep(step, prefix, defInputs = []) {
|
|
672
679
|
const prefixStem = (stem) => `${prefix}.${stem}`;
|
|
673
680
|
const newConsumes = step.consumes.map((c) => {
|
|
674
681
|
const stem = prefixStem(c.stem);
|
|
@@ -710,11 +717,12 @@ function prefixStep(step, prefix) {
|
|
|
710
717
|
// judges: marker names a local stem (unlike calls:, which names an external
|
|
711
718
|
// workflow) — it must be prefixed to keep pointing at the (now-prefixed) produce.
|
|
712
719
|
const newJudges = step.judges !== undefined ? prefixStem(step.judges) : undefined;
|
|
713
|
-
// workdirFrom names a local consumed stem
|
|
714
|
-
//
|
|
720
|
+
// workdirFrom names a local consumed stem or a declared input of the included
|
|
721
|
+
// definition, followed by a dotted value path. Prefix only the stem; the value
|
|
722
|
+
// path is a field path inside that artifact's value.
|
|
715
723
|
let newWorkdirFrom = step.workdirFrom;
|
|
716
724
|
if (step.workdirFrom !== undefined) {
|
|
717
|
-
const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes);
|
|
725
|
+
const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes, defInputs);
|
|
718
726
|
if (parsed)
|
|
719
727
|
newWorkdirFrom = `${prefixStem(parsed.stem)}.${parsed.path}`;
|
|
720
728
|
}
|
|
@@ -785,7 +793,8 @@ export function expandIncludes(def, resolve, stack) {
|
|
|
785
793
|
}
|
|
786
794
|
}
|
|
787
795
|
// (e) prefix child steps
|
|
788
|
-
const
|
|
796
|
+
const childInputList = child.inputs.map((inp) => inp.name);
|
|
797
|
+
const prefixedSteps = child.steps.map((l) => prefixStep(l, inc.as, childInputList));
|
|
789
798
|
// (f) handle inputs: mapped inputs become internal edges; unmapped are hoisted
|
|
790
799
|
const inputRewrites = new Map(); // prefixed-stem -> outer artifact
|
|
791
800
|
for (const childInp of child.inputs) {
|
|
@@ -800,6 +809,7 @@ export function expandIncludes(def, resolve, stack) {
|
|
|
800
809
|
}
|
|
801
810
|
}
|
|
802
811
|
// Apply input rewrites to prefixed steps
|
|
812
|
+
const prefixedChildInputStems = child.inputs.map((inp) => `${inc.as}.${inp.name}`);
|
|
803
813
|
const rewrittenSteps = prefixedSteps.map((l) => {
|
|
804
814
|
const rewrittenConsumes = l.consumes.map((c) => {
|
|
805
815
|
const outer = inputRewrites.get(c.stem);
|
|
@@ -809,7 +819,19 @@ export function expandIncludes(def, resolve, stack) {
|
|
|
809
819
|
}
|
|
810
820
|
return c;
|
|
811
821
|
});
|
|
812
|
-
|
|
822
|
+
// A workdirFrom stem naming a MAPPED child input has to follow the same
|
|
823
|
+
// rewrite its consumes just took, or it would keep pointing at the
|
|
824
|
+
// child-local stem that this expansion just replaced. Split against the
|
|
825
|
+
// pre-rewrite consumes plus every prefixed child input, because the stem
|
|
826
|
+
// may be either and both are subject to the mapping.
|
|
827
|
+
let rewrittenWorkdirFrom = l.workdirFrom;
|
|
828
|
+
if (l.workdirFrom !== undefined) {
|
|
829
|
+
const parsed = parseWorkdirFrom(l.workdirFrom, l.consumes, prefixedChildInputStems);
|
|
830
|
+
const outer = parsed ? inputRewrites.get(parsed.stem) : undefined;
|
|
831
|
+
if (parsed && outer !== undefined)
|
|
832
|
+
rewrittenWorkdirFrom = `${outer}.${parsed.path}`;
|
|
833
|
+
}
|
|
834
|
+
return { ...l, consumes: rewrittenConsumes, workdirFrom: rewrittenWorkdirFrom };
|
|
813
835
|
});
|
|
814
836
|
resultSteps.push(...rewrittenSteps);
|
|
815
837
|
// (g) merge child outputs
|
|
@@ -1103,25 +1125,44 @@ export function validateDef(def) {
|
|
|
1103
1125
|
if (l.workdirFrom === undefined)
|
|
1104
1126
|
continue;
|
|
1105
1127
|
const raw = l.workdirFrom.trim();
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1128
|
+
// A stem that is itself dotted (`a.b`) would otherwise split into `a` + `b`
|
|
1129
|
+
// and report a confusing missing-stem error, so name the real mistake first:
|
|
1130
|
+
// the expression is a bare artifact name with no value path after it.
|
|
1131
|
+
const bareStem = l.consumes.some((c) => c.stem === raw) || inputNames.has(raw);
|
|
1132
|
+
if (bareStem) {
|
|
1133
|
+
errors.push(`step '${l.name}': workdirFrom must use '<stem>.<dotted.path>' with a non-empty value path`);
|
|
1109
1134
|
continue;
|
|
1110
1135
|
}
|
|
1111
1136
|
const firstDot = raw.indexOf('.');
|
|
1112
1137
|
const valuePath = firstDot >= 0 ? raw.slice(firstDot + 1) : '';
|
|
1113
1138
|
if (firstDot <= 0 || valuePath.length === 0) {
|
|
1114
|
-
errors.push(`step '${l.name}': workdirFrom must use '<
|
|
1139
|
+
errors.push(`step '${l.name}': workdirFrom must use '<stem>.<dotted.path>' with a non-empty value path`);
|
|
1115
1140
|
continue;
|
|
1116
1141
|
}
|
|
1117
|
-
//
|
|
1118
|
-
//
|
|
1119
|
-
//
|
|
1120
|
-
|
|
1142
|
+
// A workdirFrom value becomes a filesystem path, so the stem must name
|
|
1143
|
+
// something this def actually declares: one of the step's own plain
|
|
1144
|
+
// consumes, or one of the definition's declared inputs.
|
|
1145
|
+
//
|
|
1146
|
+
// The input form exists because a COMMAND step cannot consume a human seed
|
|
1147
|
+
// at all — `exec/instructions.ts` gates command orders with `hardRule:
|
|
1148
|
+
// true`, and `consumed-verifier.ts` refuses any consumed value lacking a
|
|
1149
|
+
// producer signature, which a human-supplied input never has. Naming the
|
|
1150
|
+
// input here routes it through `OrderPacket.workdir` instead, which is a
|
|
1151
|
+
// spawn parameter rather than shell text or a consumed artifact.
|
|
1152
|
+
//
|
|
1153
|
+
// This deliberately relaxes an earlier rule that demanded a CONSUME, on the
|
|
1154
|
+
// stated grounds that the value must pass the consume-side gate "before a
|
|
1155
|
+
// worker can cd into it". That protection was not real: the engine resolves
|
|
1156
|
+
// this expression itself and ships a plain string as `OrderPacket.workdir`,
|
|
1157
|
+
// an explicitly "opaque location hint" that no proof covers and that the
|
|
1158
|
+
// command worker uses unverified. See `paths.ts`'s parseWorkdirFrom header
|
|
1159
|
+
// for the full argument, and note that the runtime bound on a worker's cwd
|
|
1160
|
+
// is the operator's declared work roots, not this check.
|
|
1161
|
+
const parsed = parseWorkdirFrom(raw, l.consumes, [...inputNames]);
|
|
1121
1162
|
if (!parsed) {
|
|
1122
1163
|
const stem = raw.slice(0, firstDot);
|
|
1123
|
-
errors.push(`step '${l.name}': workdirFrom stem '${stem}' is
|
|
1124
|
-
|
|
1164
|
+
errors.push(`step '${l.name}': workdirFrom stem '${stem}' is neither in consumes nor a declared input; ` +
|
|
1165
|
+
"a step may only take its workdir from an artifact it consumes or from one of the definition's inputs");
|
|
1125
1166
|
}
|
|
1126
1167
|
else if (parsed.mode !== 'plain') {
|
|
1127
1168
|
errors.push(`step '${l.name}': workdirFrom stem '${parsed.stem}' uses a ${parsed.mode} consume; ` +
|
package/dist/src/engine.d.ts
CHANGED
|
@@ -218,7 +218,7 @@ export type EngineEvent = {
|
|
|
218
218
|
workflow: string;
|
|
219
219
|
run?: string;
|
|
220
220
|
path: string;
|
|
221
|
-
action: 'green' | 'emit' | 'seal' | 'reject' | 'retract' | 'skip' | 'retry' | 'provide';
|
|
221
|
+
action: 'green' | 'emit' | 'seal' | 'reject' | 'retract' | 'skip' | 'retry' | 'provide' | 'ask';
|
|
222
222
|
outcome?: CommitResult['outcome'] | EmitResult['outcome'];
|
|
223
223
|
} | {
|
|
224
224
|
type: 'closed';
|
|
@@ -777,12 +777,57 @@ export declare class Engine {
|
|
|
777
777
|
retract(workflow: string, path: string, by: Author, text: string): void;
|
|
778
778
|
/** A producer skips its own owed output on a dead branch (§16.1 routing). */
|
|
779
779
|
skip(workflow: string, path: string, by: Author, text: string): void;
|
|
780
|
+
/**
|
|
781
|
+
* ESCALATION: a producing step stops and asks a human, instead of guessing.
|
|
782
|
+
*
|
|
783
|
+
* WHY THIS IS A SEPARATE VERB AND NOT A FLAVOUR OF `reject`. `reject` is a
|
|
784
|
+
* *verdict on a built version* — it refuses any artifact that is not `green`
|
|
785
|
+
* or `submitted` (see the guard in `reject()`), because bumping
|
|
786
|
+
* `judgmentRejects` on a never-built `owed` artifact would burn stall budget
|
|
787
|
+
* with zero build attempts and silently freeze the producer. `ask` targets
|
|
788
|
+
* exactly that state: the artifact the asking step still OWES and has decided
|
|
789
|
+
* it cannot honestly build. Different precondition, different counter policy,
|
|
790
|
+
* different author — so, a different method.
|
|
791
|
+
*
|
|
792
|
+
* WHAT IT CLOSES. Before this verb a step agent that could not proceed had two
|
|
793
|
+
* options, and both were observed damaging real runs:
|
|
794
|
+
* 1. Submit something it did not believe. The artifact greens and every
|
|
795
|
+
* downstream step builds on a fabrication.
|
|
796
|
+
* 2. End its turn without submitting. The task re-arms, a fresh worker
|
|
797
|
+
* starts from the same missing information, and the step retries until
|
|
798
|
+
* it hits the stall cap — burning budget to relearn the same blocker.
|
|
799
|
+
* Neither ever reaches a person. `ask` is the third option.
|
|
800
|
+
*
|
|
801
|
+
* MECHANICS. The artifact moves `owed` → `rejected` with a trailing reason of
|
|
802
|
+
* kind `'question'`. `isHeld` (model.ts) recognises that kind, so `frozen()`
|
|
803
|
+
* is true and the engine stops re-arming the producer — no retry storm. NO
|
|
804
|
+
* counter moves: `judgmentRejects` and `schemaRejects` are untouched, because
|
|
805
|
+
* a question is not a failed attempt and must not consume stall budget.
|
|
806
|
+
*
|
|
807
|
+
* THE ANSWER IS `retry`. There is deliberately no `answer` verb. A human runs
|
|
808
|
+
* `owenloop retry <workflow> <path> --text "<answer>"`, which appends a
|
|
809
|
+
* `'structural'` reason — clearing held-ness automatically, since `isHeld`
|
|
810
|
+
* reads only the LAST entry — re-arms the artifact to `owed`, and leaves the
|
|
811
|
+
* answer sitting on the reason thread that the next fresh worker reads in its
|
|
812
|
+
* order. Two ways into held, one way out.
|
|
813
|
+
*
|
|
814
|
+
* AUTHORITY. Not `assertAuthority`: that follows the CONSUME edge (who may
|
|
815
|
+
* invalidate someone else's work), and this is the opposite direction — the
|
|
816
|
+
* producer speaking about its own debt. So the rule is that `by` must be the
|
|
817
|
+
* artifact's own producer (or `human`/`engine`).
|
|
818
|
+
*/
|
|
819
|
+
ask(workflow: string, path: string, by: Author, question: string): void;
|
|
780
820
|
/**
|
|
781
821
|
* Human stall-clearing lever (§6): reset an artifact's judgment-reject count
|
|
782
822
|
* and re-arm it to `owed`, optionally appending a line of guiding context that
|
|
783
823
|
* rides to the next producer on the order's `owes` thread. This is how a
|
|
784
824
|
* stalled (capped-out) artifact gets unstuck and steered, rather than thrashing
|
|
785
825
|
* forever or being abandoned. For a stuck collection member, `retract` instead.
|
|
826
|
+
*
|
|
827
|
+
* This is ALSO the answer path for `ask` above — `retry --text "<answer>"`
|
|
828
|
+
* appends a `'structural'` reason, which clears held-ness and delivers the
|
|
829
|
+
* answer to the next worker on the same thread. There is no separate
|
|
830
|
+
* `answer` verb by design.
|
|
786
831
|
*/
|
|
787
832
|
retry(workflow: string, path: string, by?: Author, text?: string): void;
|
|
788
833
|
/** Close a run (audit/budget) and release its lease so the task can re-arm. */
|
package/dist/src/engine.js
CHANGED
|
@@ -1389,14 +1389,36 @@ export class Engine {
|
|
|
1389
1389
|
};
|
|
1390
1390
|
let resolvedWorkdir;
|
|
1391
1391
|
if (step.workdirFrom !== undefined) {
|
|
1392
|
-
const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes);
|
|
1392
|
+
const parsed = parseWorkdirFrom(step.workdirFrom, step.consumes, def.inputs.map((i) => i.name));
|
|
1393
1393
|
if (!parsed) {
|
|
1394
|
-
return unresolved(`workdirFrom '${step.workdirFrom}': expected a consumed stem followed by a non-empty dotted value path`);
|
|
1394
|
+
return unresolved(`workdirFrom '${step.workdirFrom}': expected a consumed or declared-input stem followed by a non-empty dotted value path`);
|
|
1395
1395
|
}
|
|
1396
1396
|
if (parsed.mode !== 'plain') {
|
|
1397
1397
|
return unresolved(`workdirFrom '${step.workdirFrom}': source stem '${parsed.stem}' is not a plain consume`);
|
|
1398
1398
|
}
|
|
1399
|
-
|
|
1399
|
+
// A CONSUMED stem reads out of the firing's resolved consume map, exactly
|
|
1400
|
+
// as before. An INPUT stem the step does not consume is not in that map,
|
|
1401
|
+
// so it reads out of the instance's artifact table instead.
|
|
1402
|
+
//
|
|
1403
|
+
// The green check is what makes this an ordering edge without a consume.
|
|
1404
|
+
// `unresolved` defers the firing rather than failing it, so a step whose
|
|
1405
|
+
// workdir comes from a still-owed input simply is not offered yet and is
|
|
1406
|
+
// reconsidered on the next tick — the same wait a consume would have
|
|
1407
|
+
// produced, without putting the value in `order.consumes` (where the
|
|
1408
|
+
// command launch gate would hard-refuse it for having no producer
|
|
1409
|
+
// signature: a human seed has none). See `paths.ts`'s parseWorkdirFrom
|
|
1410
|
+
// header for why an input-authored cwd is admissible at all.
|
|
1411
|
+
let value;
|
|
1412
|
+
if (parsed.source === 'consume') {
|
|
1413
|
+
value = consumes[parsed.stem];
|
|
1414
|
+
}
|
|
1415
|
+
else {
|
|
1416
|
+
const art = arts.get(parsed.stem);
|
|
1417
|
+
if (art === undefined || art.acceptance !== 'green') {
|
|
1418
|
+
return unresolved(`workdirFrom '${step.workdirFrom}': input '${parsed.stem}' is not green yet`);
|
|
1419
|
+
}
|
|
1420
|
+
value = art.value;
|
|
1421
|
+
}
|
|
1400
1422
|
const segments = parsed.path.split('.');
|
|
1401
1423
|
for (let i = 0; i < segments.length; i++) {
|
|
1402
1424
|
const segment = segments[i];
|
|
@@ -2074,12 +2096,84 @@ export class Engine {
|
|
|
2074
2096
|
this.fire({ type: 'commit', workflow, path, action: 'skip' });
|
|
2075
2097
|
this.fireSettled(workflow);
|
|
2076
2098
|
}
|
|
2099
|
+
/**
|
|
2100
|
+
* ESCALATION: a producing step stops and asks a human, instead of guessing.
|
|
2101
|
+
*
|
|
2102
|
+
* WHY THIS IS A SEPARATE VERB AND NOT A FLAVOUR OF `reject`. `reject` is a
|
|
2103
|
+
* *verdict on a built version* — it refuses any artifact that is not `green`
|
|
2104
|
+
* or `submitted` (see the guard in `reject()`), because bumping
|
|
2105
|
+
* `judgmentRejects` on a never-built `owed` artifact would burn stall budget
|
|
2106
|
+
* with zero build attempts and silently freeze the producer. `ask` targets
|
|
2107
|
+
* exactly that state: the artifact the asking step still OWES and has decided
|
|
2108
|
+
* it cannot honestly build. Different precondition, different counter policy,
|
|
2109
|
+
* different author — so, a different method.
|
|
2110
|
+
*
|
|
2111
|
+
* WHAT IT CLOSES. Before this verb a step agent that could not proceed had two
|
|
2112
|
+
* options, and both were observed damaging real runs:
|
|
2113
|
+
* 1. Submit something it did not believe. The artifact greens and every
|
|
2114
|
+
* downstream step builds on a fabrication.
|
|
2115
|
+
* 2. End its turn without submitting. The task re-arms, a fresh worker
|
|
2116
|
+
* starts from the same missing information, and the step retries until
|
|
2117
|
+
* it hits the stall cap — burning budget to relearn the same blocker.
|
|
2118
|
+
* Neither ever reaches a person. `ask` is the third option.
|
|
2119
|
+
*
|
|
2120
|
+
* MECHANICS. The artifact moves `owed` → `rejected` with a trailing reason of
|
|
2121
|
+
* kind `'question'`. `isHeld` (model.ts) recognises that kind, so `frozen()`
|
|
2122
|
+
* is true and the engine stops re-arming the producer — no retry storm. NO
|
|
2123
|
+
* counter moves: `judgmentRejects` and `schemaRejects` are untouched, because
|
|
2124
|
+
* a question is not a failed attempt and must not consume stall budget.
|
|
2125
|
+
*
|
|
2126
|
+
* THE ANSWER IS `retry`. There is deliberately no `answer` verb. A human runs
|
|
2127
|
+
* `owenloop retry <workflow> <path> --text "<answer>"`, which appends a
|
|
2128
|
+
* `'structural'` reason — clearing held-ness automatically, since `isHeld`
|
|
2129
|
+
* reads only the LAST entry — re-arms the artifact to `owed`, and leaves the
|
|
2130
|
+
* answer sitting on the reason thread that the next fresh worker reads in its
|
|
2131
|
+
* order. Two ways into held, one way out.
|
|
2132
|
+
*
|
|
2133
|
+
* AUTHORITY. Not `assertAuthority`: that follows the CONSUME edge (who may
|
|
2134
|
+
* invalidate someone else's work), and this is the opposite direction — the
|
|
2135
|
+
* producer speaking about its own debt. So the rule is that `by` must be the
|
|
2136
|
+
* artifact's own producer (or `human`/`engine`).
|
|
2137
|
+
*/
|
|
2138
|
+
ask(workflow, path, by, question) {
|
|
2139
|
+
const def = this.defFor(workflow);
|
|
2140
|
+
this.store.tx(() => {
|
|
2141
|
+
const art = this.store.getArtifact(workflow, path);
|
|
2142
|
+
if (!art)
|
|
2143
|
+
throw new Error(`cannot ask about unknown artifact: ${path}`);
|
|
2144
|
+
if (by !== 'human' && by !== 'engine' && art.producer !== by) {
|
|
2145
|
+
throw new Error(`${by} has no authority to ask about ${path} (it is produced by '${art.producer}'). ` +
|
|
2146
|
+
`\`ask\` is the producer speaking about its own debt; to send someone else's work back, use \`reject\`.`);
|
|
2147
|
+
}
|
|
2148
|
+
// A question is only meaningful about work not yet delivered. On a
|
|
2149
|
+
// `green`/`submitted` artifact the honest move is `reject` (there is a
|
|
2150
|
+
// version to have an opinion about); on `retracted`/`skipped` there is no
|
|
2151
|
+
// live debt left to answer.
|
|
2152
|
+
if (art.acceptance !== 'owed' && art.acceptance !== 'rejected') {
|
|
2153
|
+
throw new Error(`cannot ask about '${path}' in state '${art.acceptance}': ` +
|
|
2154
|
+
`\`ask\` records a blocker on work still owed (owed|rejected)`);
|
|
2155
|
+
}
|
|
2156
|
+
this.store.putArtifact({
|
|
2157
|
+
...art,
|
|
2158
|
+
acceptance: 'rejected',
|
|
2159
|
+
reasons: [...art.reasons, reason('ask', 'question', by, question, art.version)],
|
|
2160
|
+
});
|
|
2161
|
+
this.settle(workflow, def);
|
|
2162
|
+
});
|
|
2163
|
+
this.fire({ type: 'commit', workflow, path, action: 'ask' });
|
|
2164
|
+
this.fireSettled(workflow);
|
|
2165
|
+
}
|
|
2077
2166
|
/**
|
|
2078
2167
|
* Human stall-clearing lever (§6): reset an artifact's judgment-reject count
|
|
2079
2168
|
* and re-arm it to `owed`, optionally appending a line of guiding context that
|
|
2080
2169
|
* rides to the next producer on the order's `owes` thread. This is how a
|
|
2081
2170
|
* stalled (capped-out) artifact gets unstuck and steered, rather than thrashing
|
|
2082
2171
|
* forever or being abandoned. For a stuck collection member, `retract` instead.
|
|
2172
|
+
*
|
|
2173
|
+
* This is ALSO the answer path for `ask` above — `retry --text "<answer>"`
|
|
2174
|
+
* appends a `'structural'` reason, which clears held-ness and delivers the
|
|
2175
|
+
* answer to the next worker on the same thread. There is no separate
|
|
2176
|
+
* `answer` verb by design.
|
|
2083
2177
|
*/
|
|
2084
2178
|
retry(workflow, path, by = 'human', text = 'retry: stall cleared') {
|
|
2085
2179
|
const def = this.defFor(workflow);
|
package/dist/src/hub.d.ts
CHANGED
|
@@ -222,7 +222,11 @@ export declare function keychainServiceFor(normalizedOrigin: string): string;
|
|
|
222
222
|
* instead of a clean miss.
|
|
223
223
|
*/
|
|
224
224
|
export declare function parseCredential(raw: unknown): Credential | null;
|
|
225
|
-
/**
|
|
225
|
+
/**
|
|
226
|
+
* The user-level config dir (never the project dir). Derives from the caller's
|
|
227
|
+
* env via the one shared ladder in `config-dir.ts`:
|
|
228
|
+
* `OWENLOOP_CONFIG_DIR` > `$XDG_CONFIG_HOME/owenloop` > `$HOME/.config/owenloop`.
|
|
229
|
+
*/
|
|
226
230
|
export declare function configDir(env: Record<string, string | undefined>): string;
|
|
227
231
|
export declare function credentialFilePath(env: Record<string, string | undefined>): string;
|
|
228
232
|
/**
|
package/dist/src/hub.js
CHANGED
|
@@ -69,6 +69,7 @@ import { createHash, randomBytes } from 'node:crypto';
|
|
|
69
69
|
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
|
|
70
70
|
import { basename, dirname, join } from 'node:path';
|
|
71
71
|
import { parse as parseYaml } from 'yaml';
|
|
72
|
+
import { owenloopConfigDir } from "./config-dir.js";
|
|
72
73
|
import { hashDef, parseDef } from "./defs.js";
|
|
73
74
|
import { mkdirRefusingSymlink } from "./util.js";
|
|
74
75
|
// ---- server-parity def content hash ------------------------------------------
|
|
@@ -277,15 +278,13 @@ export function parseCredential(raw) {
|
|
|
277
278
|
}
|
|
278
279
|
return null;
|
|
279
280
|
}
|
|
280
|
-
/**
|
|
281
|
+
/**
|
|
282
|
+
* The user-level config dir (never the project dir). Derives from the caller's
|
|
283
|
+
* env via the one shared ladder in `config-dir.ts`:
|
|
284
|
+
* `OWENLOOP_CONFIG_DIR` > `$XDG_CONFIG_HOME/owenloop` > `$HOME/.config/owenloop`.
|
|
285
|
+
*/
|
|
281
286
|
export function configDir(env) {
|
|
282
|
-
|
|
283
|
-
if (xdg && xdg.trim() !== '')
|
|
284
|
-
return join(xdg, 'owenloop');
|
|
285
|
-
const home = env.HOME;
|
|
286
|
-
if (home && home.trim() !== '')
|
|
287
|
-
return join(home, '.config', 'owenloop');
|
|
288
|
-
throw new Error('cannot locate a config directory: set HOME or XDG_CONFIG_HOME');
|
|
287
|
+
return owenloopConfigDir(env);
|
|
289
288
|
}
|
|
290
289
|
export function credentialFilePath(env) {
|
|
291
290
|
return join(configDir(env), 'credentials.json');
|
package/dist/src/index.d.ts
CHANGED
|
@@ -35,7 +35,7 @@ export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefP
|
|
|
35
35
|
export type { PolicyFloorGap, PolicyFloorMergeResult, PolicyFloorVerdict, VerifyPolicyFloorInput, VerifyPolicyFloorOptions, } from './crypto/index.ts';
|
|
36
36
|
export { ORIGIN_SOURCE_RANK, OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, } from './crypto/index.ts';
|
|
37
37
|
export type { OriginPolicy, OriginRuleEvaluation, OriginRuleMatch, OriginRuleValue, OriginRules, } from './crypto/index.ts';
|
|
38
|
-
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from './model.ts';
|
|
38
|
+
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isHeld, isStalled, modelCheck, openQuestion, workflowStatus, } from './model.ts';
|
|
39
39
|
export type { ArtifactMap, Blocker, Firing, TimeFacts, WorkflowStatus } from './model.ts';
|
|
40
40
|
export { parseConsume, parseProduce, } from './paths.ts';
|
|
41
41
|
export { assertValidSchema, summarizeIssues, validateValue } from './schema.ts';
|
package/dist/src/index.js
CHANGED
|
@@ -30,7 +30,7 @@ export { DSSE_SSH_NAMESPACE, DSSE_VERSION, DSSE_RECORD_PAYLOAD_TYPES, DsseEnvelo
|
|
|
30
30
|
export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefPolicyMinimum, mergePolicyFloorWithLocal, originRulesMinimum, policyFloorGaps, stricterDefPolicy, verifyPolicyFloorRecord, } from "./crypto/index.js";
|
|
31
31
|
// ---- WP-E2a origin execution policy ----
|
|
32
32
|
export { ORIGIN_SOURCE_RANK, OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, } from "./crypto/index.js";
|
|
33
|
-
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from "./model.js";
|
|
33
|
+
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isHeld, isStalled, modelCheck, openQuestion, workflowStatus, } from "./model.js";
|
|
34
34
|
export { parseConsume, parseProduce, } from "./paths.js";
|
|
35
35
|
export { assertValidSchema, summarizeIssues, validateValue } from "./schema.js";
|
|
36
36
|
export { enrollmentGrantSchema, orderSchema, originSchema, policyFloorSchema, publicationSchema, RECORD_SCHEMAS, revocationSchema, SCHEMA_BY_PAYLOAD_TYPE, submissionSchema, WIRE_SCHEMAS, } from "./schemas/index.js";
|
package/dist/src/model.d.ts
CHANGED
|
@@ -128,12 +128,28 @@ export declare function isStalled(a: ArtifactData | undefined, cap: number): boo
|
|
|
128
128
|
*/
|
|
129
129
|
export declare function isSchemaStalled(a: ArtifactData | undefined, cap: number): boolean;
|
|
130
130
|
/**
|
|
131
|
-
* True if the artifact is held
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
*
|
|
131
|
+
* True if the artifact is held — rejected-and-held, producer not auto-eligible
|
|
132
|
+
* to re-fire. Detected by the last reasons entry having a holding kind. A retry
|
|
133
|
+
* call appends a 'structural' entry, which clears the held condition
|
|
134
|
+
* automatically, so `retry --text '<answer>'` is the release for both kinds.
|
|
135
|
+
*
|
|
136
|
+
* TWO WAYS IN, ONE WAY OUT.
|
|
137
|
+
* - `invalidated-irreversible`: the engine held it because an input moved under
|
|
138
|
+
* a non-idempotent producer.
|
|
139
|
+
* - `question`: the producing STEP held it, via `Engine.ask`, because it could
|
|
140
|
+
* not proceed honestly and needs a human. Without this second kind an agent
|
|
141
|
+
* has no way to stop: its only alternatives are to submit something it does
|
|
142
|
+
* not believe (which greens and silently poisons every downstream step) or to
|
|
143
|
+
* end its turn without submitting (which re-arms the step into a retry storm
|
|
144
|
+
* whose every worker fails identically). Both were observed in production.
|
|
135
145
|
*/
|
|
136
146
|
export declare function isHeld(a: ArtifactData | undefined): boolean;
|
|
147
|
+
/**
|
|
148
|
+
* The open question on a held artifact, if it is held by `ask`. Returns the
|
|
149
|
+
* question text so an operator-facing read can print WHAT is being asked
|
|
150
|
+
* instead of only that something is stuck — the whole point of the channel.
|
|
151
|
+
*/
|
|
152
|
+
export declare function openQuestion(a: ArtifactData | undefined): string | undefined;
|
|
137
153
|
/**
|
|
138
154
|
* §7 escalation trigger: has this artifact been judgment-rejected at least
|
|
139
155
|
* `after` times in the CURRENT rejection episode?
|
|
@@ -293,10 +309,18 @@ export interface WorkflowStatus {
|
|
|
293
309
|
debts: Array<{
|
|
294
310
|
path: string;
|
|
295
311
|
acceptance: Acceptance;
|
|
296
|
-
kind: 'judgment' | 'structural' | 'validation' | 'unbuilt' | 'invalidated-irreversible';
|
|
312
|
+
kind: 'judgment' | 'structural' | 'validation' | 'unbuilt' | 'invalidated-irreversible' | 'question';
|
|
297
313
|
/** §6/§18/held: rejected past its producer's cap, or held — the engine won't re-arm it */
|
|
298
314
|
stalled: boolean;
|
|
299
315
|
reason?: string;
|
|
316
|
+
/**
|
|
317
|
+
* The open question, when `kind === 'question'` — the producing step called
|
|
318
|
+
* `Engine.ask` and stopped waiting on a human. Same string as `reason`,
|
|
319
|
+
* surfaced under its own name so an operator-facing reader can filter for
|
|
320
|
+
* "what is waiting on ME" without pattern-matching a kind. Absent on every
|
|
321
|
+
* other debt shape.
|
|
322
|
+
*/
|
|
323
|
+
question?: string;
|
|
300
324
|
/**
|
|
301
325
|
* Consecutive trailing `failed` runs for this debt's producer (crash-step
|
|
302
326
|
* signal). Enriched by `engine.status()` from the run log — `workflowStatus`
|
package/dist/src/model.js
CHANGED
|
@@ -110,16 +110,39 @@ export function isStalled(a, cap) {
|
|
|
110
110
|
export function isSchemaStalled(a, cap) {
|
|
111
111
|
return !!a && cap > 0 && a.acceptance === 'rejected' && a.schemaRejects >= cap;
|
|
112
112
|
}
|
|
113
|
+
/** Reason kinds that hold an artifact: the producer is not auto-eligible to re-fire. */
|
|
114
|
+
const HOLDING_KINDS = new Set(['invalidated-irreversible', 'question']);
|
|
113
115
|
/**
|
|
114
|
-
* True if the artifact is held
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
116
|
+
* True if the artifact is held — rejected-and-held, producer not auto-eligible
|
|
117
|
+
* to re-fire. Detected by the last reasons entry having a holding kind. A retry
|
|
118
|
+
* call appends a 'structural' entry, which clears the held condition
|
|
119
|
+
* automatically, so `retry --text '<answer>'` is the release for both kinds.
|
|
120
|
+
*
|
|
121
|
+
* TWO WAYS IN, ONE WAY OUT.
|
|
122
|
+
* - `invalidated-irreversible`: the engine held it because an input moved under
|
|
123
|
+
* a non-idempotent producer.
|
|
124
|
+
* - `question`: the producing STEP held it, via `Engine.ask`, because it could
|
|
125
|
+
* not proceed honestly and needs a human. Without this second kind an agent
|
|
126
|
+
* has no way to stop: its only alternatives are to submit something it does
|
|
127
|
+
* not believe (which greens and silently poisons every downstream step) or to
|
|
128
|
+
* end its turn without submitting (which re-arms the step into a retry storm
|
|
129
|
+
* whose every worker fails identically). Both were observed in production.
|
|
118
130
|
*/
|
|
119
131
|
export function isHeld(a) {
|
|
120
132
|
if (!a || a.acceptance !== 'rejected')
|
|
121
133
|
return false;
|
|
122
|
-
return a.reasons.length > 0 && a.reasons[a.reasons.length - 1].kind
|
|
134
|
+
return a.reasons.length > 0 && HOLDING_KINDS.has(a.reasons[a.reasons.length - 1].kind);
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* The open question on a held artifact, if it is held by `ask`. Returns the
|
|
138
|
+
* question text so an operator-facing read can print WHAT is being asked
|
|
139
|
+
* instead of only that something is stuck — the whole point of the channel.
|
|
140
|
+
*/
|
|
141
|
+
export function openQuestion(a) {
|
|
142
|
+
if (!a || a.acceptance !== 'rejected' || a.reasons.length === 0)
|
|
143
|
+
return undefined;
|
|
144
|
+
const last = a.reasons[a.reasons.length - 1];
|
|
145
|
+
return last.kind === 'question' ? last.text : undefined;
|
|
123
146
|
}
|
|
124
147
|
/**
|
|
125
148
|
* §7 escalation trigger: has this artifact been judgment-rejected at least
|
|
@@ -962,18 +985,34 @@ export function workflowStatus(def, arts) {
|
|
|
962
985
|
? 'validation'
|
|
963
986
|
: last.kind === 'invalidated-irreversible'
|
|
964
987
|
? 'invalidated-irreversible'
|
|
965
|
-
: '
|
|
988
|
+
: last.kind === 'question'
|
|
989
|
+
? 'question'
|
|
990
|
+
: 'structural'
|
|
966
991
|
: 'unbuilt';
|
|
967
992
|
const prod = stepByName(def, a.producer);
|
|
968
993
|
const producePat = prod && produceOwning(prod, a.path);
|
|
969
994
|
// Held artifacts (isHeld) surface as stalled: true — they require human intervention.
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
995
|
+
//
|
|
996
|
+
// `isHeld` is deliberately OUTSIDE the `prod &&` guard that the two counter
|
|
997
|
+
// caps sit inside. Those caps are read off a producer STEP, so they are
|
|
998
|
+
// meaningless without one — but held-ness is read off the artifact's own
|
|
999
|
+
// reason thread and is just as real for a `producer: human` input. Keeping
|
|
1000
|
+
// it inside the guard meant a human-produced artifact could never be
|
|
1001
|
+
// reported stalled no matter how many times it was rejected, so a run
|
|
1002
|
+
// waiting on a PERSON was indistinguishable from any other owed row. That
|
|
1003
|
+
// is the single thing an operator most needs told.
|
|
1004
|
+
const stalled = isHeld(a) ||
|
|
1005
|
+
(!!prod &&
|
|
1006
|
+
(isStalled(a, effectiveMaxAttempts(prod, producePat)) ||
|
|
1007
|
+
isSchemaStalled(a, effectiveMaxSchemaFailures(prod, producePat))));
|
|
974
1008
|
const entry = { path: a.path, acceptance: a.acceptance, kind, stalled };
|
|
975
1009
|
if (last)
|
|
976
1010
|
entry.reason = last.text;
|
|
1011
|
+
// The question text is already in `reason`, but a caller filtering for
|
|
1012
|
+
// "what is waiting on me" should not have to infer it from a kind string.
|
|
1013
|
+
const q = openQuestion(a);
|
|
1014
|
+
if (q !== undefined)
|
|
1015
|
+
entry.question = q;
|
|
977
1016
|
debts.push(entry);
|
|
978
1017
|
}
|
|
979
1018
|
debts.sort((x, y) => x.path.localeCompare(y.path));
|
|
@@ -1173,15 +1212,25 @@ export function buildTrace(def, artifacts, runs) {
|
|
|
1173
1212
|
if (e.action === 'retry')
|
|
1174
1213
|
totalRetries++;
|
|
1175
1214
|
}
|
|
1176
|
-
// Check stall
|
|
1215
|
+
// Check stall. Two independent sources, and they are checked separately
|
|
1216
|
+
// on purpose:
|
|
1217
|
+
// 1. The two counter caps — read off the PRODUCER STEP, so they can only
|
|
1218
|
+
// be evaluated when there is a producer step to read them off.
|
|
1219
|
+
// 2. Held-ness — read off the artifact's own reason thread, so it is
|
|
1220
|
+
// just as true for a `producer: human` input. Checking it inside the
|
|
1221
|
+
// `if (producerStep)` block (as this did until 2026-08-15) meant an
|
|
1222
|
+
// artifact a PERSON owes could never appear in `stalledArtifacts`,
|
|
1223
|
+
// which is exactly the row a trace reader is looking for.
|
|
1224
|
+
let stalled = isHeld(art);
|
|
1177
1225
|
const producerStep = def.steps.find((l) => l.name === art.producer);
|
|
1178
|
-
if (producerStep) {
|
|
1226
|
+
if (!stalled && producerStep) {
|
|
1179
1227
|
const producePat = produceOwning(producerStep, art.path);
|
|
1180
1228
|
const stallJ = isStalled(art, effectiveMaxAttempts(producerStep, producePat));
|
|
1181
1229
|
const stallS = isSchemaStalled(art, effectiveMaxSchemaFailures(producerStep, producePat));
|
|
1182
|
-
|
|
1183
|
-
stalledArtifacts.push(art.path);
|
|
1230
|
+
stalled = stallJ || stallS;
|
|
1184
1231
|
}
|
|
1232
|
+
if (stalled)
|
|
1233
|
+
stalledArtifacts.push(art.path);
|
|
1185
1234
|
const bio = {
|
|
1186
1235
|
path: art.path,
|
|
1187
1236
|
producer: art.producer,
|