owenloop 0.5.1 → 0.5.2
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 +22 -0
- package/README.md +9 -2
- package/dist/packages/work/src/agent/brief.d.ts +21 -0
- package/dist/packages/work/src/agent/brief.js +42 -1
- package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
- package/dist/packages/work/src/agent/capability-model.js +148 -0
- package/dist/packages/work/src/agent/loop.d.ts +47 -4
- package/dist/packages/work/src/agent/loop.js +83 -53
- package/dist/packages/work/src/exec/loop.d.ts +17 -0
- package/dist/packages/work/src/exec/loop.js +195 -34
- package/dist/packages/work/src/exec/runner.js +15 -5
- package/dist/packages/work/src/harness/session-store.d.ts +3 -1
- package/dist/packages/work/src/harness/session-store.js +46 -22
- package/dist/packages/work/src/hold/mcp.js +9 -2
- package/dist/packages/work/src/hub/client.d.ts +7 -1
- package/dist/packages/work/src/hub/client.js +1 -0
- package/dist/packages/work/src/hub/types.d.ts +71 -3
- package/dist/packages/work/src/roles/agent-run.js +8 -9
- package/dist/packages/work/src/roles/hold.d.ts +2 -0
- package/dist/packages/work/src/roles/hold.js +39 -8
- package/dist/packages/work/src/roles/settings.js +18 -6
- package/dist/packages/work/src/roles/shift.js +13 -1
- package/dist/packages/work/src/settings/settings.d.ts +60 -7
- package/dist/packages/work/src/settings/settings.js +69 -22
- package/dist/packages/work/src/shift/logretention.d.ts +253 -0
- package/dist/packages/work/src/shift/logretention.js +407 -0
- package/dist/packages/work/src/shift/logsink.d.ts +14 -0
- package/dist/packages/work/src/shift/logsink.js +98 -0
- package/dist/packages/work/src/shift/loop.d.ts +18 -1
- package/dist/packages/work/src/shift/loop.js +250 -12
- package/dist/packages/work/src/shift/protocol.d.ts +124 -1
- package/dist/packages/work/src/shift/protocol.js +14 -0
- package/dist/packages/work/src/shift/runtime.d.ts +14 -0
- package/dist/packages/work/src/shift/runtime.js +229 -6
- package/dist/packages/work/src/shift/server.d.ts +13 -0
- package/dist/packages/work/src/shift/server.js +61 -36
- package/dist/packages/work/src/shift/spawn.d.ts +78 -5
- package/dist/packages/work/src/shift/spawn.js +158 -12
- package/dist/packages/work/src/shift/state.d.ts +25 -0
- package/dist/packages/work/src/shift/state.js +29 -5
- package/dist/packages/work/src/shift/truncate.d.ts +35 -0
- package/dist/packages/work/src/shift/truncate.js +73 -0
- package/dist/packages/work/src/submit-proof.d.ts +31 -6
- package/dist/packages/work/src/submit-proof.js +33 -7
- package/dist/packages/work/src/submit-value.d.ts +48 -0
- package/dist/packages/work/src/submit-value.js +118 -0
- package/dist/packages/work/src/usage.d.ts +1 -1
- package/dist/packages/work/src/usage.js +11 -0
- package/dist/src/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.js +14 -9
- package/dist/src/crypto/records.d.ts +3 -0
- package/dist/src/crypto/records.js +11 -0
- package/dist/src/defs.js +192 -4
- package/dist/src/engine.d.ts +112 -3
- package/dist/src/engine.js +224 -28
- package/dist/src/hub.d.ts +27 -11
- package/dist/src/hub.js +24 -18
- package/dist/src/index.d.ts +3 -1
- package/dist/src/index.js +4 -1
- package/dist/src/mcp/serve.js +11 -4
- package/dist/src/model.d.ts +36 -0
- package/dist/src/model.js +46 -0
- package/dist/src/schemas/index.d.ts +17 -0
- package/dist/src/schemas/order.v1.schema.json +17 -3
- package/dist/src/store.d.ts +33 -1
- package/dist/src/store.js +57 -4
- package/dist/src/types.d.ts +102 -2
- package/docs/authoring.md +7 -0
- package/docs/bundles.md +103 -3
- package/docs/cli.md +127 -9
- package/docs/crypto.md +23 -7
- package/docs/shift-logs.md +642 -0
- package/docs/wire-contracts.md +34 -19
- 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
- package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
- package/dist/packages/work/src/agent/model-policy.js +0 -138
package/dist/src/defs.js
CHANGED
|
@@ -26,6 +26,9 @@ import { parse as parseYaml } from 'yaml';
|
|
|
26
26
|
import { parseConsume, parseProduce, parseWorkdirFrom } from "./paths.js";
|
|
27
27
|
import { parseDurationMs, parseDurationSecs } from "./util.js";
|
|
28
28
|
import { assertValidSchema } from "./schema.js";
|
|
29
|
+
// The separator lives with composition/matching (capabilities.ts); the parser
|
|
30
|
+
// only enforces that an AUTHORED name never contains it.
|
|
31
|
+
import { MODIFIER_SEPARATOR } from "./capabilities.js";
|
|
29
32
|
/** Hand-maintained key allowlist for RawInput — kept next to the interface so
|
|
30
33
|
* the two can't silently drift (§27 unknown-key rejection). */
|
|
31
34
|
const RAW_INPUT_KEYS = ['name', 'producer', 'seedOwed', 'schema'];
|
|
@@ -35,13 +38,14 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
|
|
|
35
38
|
* fields, so it gets its own allowlist rather than folding into
|
|
36
39
|
* RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
|
|
37
40
|
const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
|
|
38
|
-
const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec'];
|
|
41
|
+
const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec', 'capabilities'];
|
|
39
42
|
/** Keys valid on a normal (non-calls:, non-include:) step entry. */
|
|
40
43
|
const RAW_STEP_KEYS = [
|
|
41
44
|
'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
|
|
42
45
|
'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
|
|
43
46
|
'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
|
|
44
47
|
'calls', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
|
|
48
|
+
'escalation',
|
|
45
49
|
];
|
|
46
50
|
/** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
|
|
47
51
|
* the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
|
|
@@ -49,7 +53,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
|
|
|
49
53
|
/** Keys valid on an include: directive entry — the `include:` key is the
|
|
50
54
|
* discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
|
|
51
55
|
const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
|
|
52
|
-
const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors'];
|
|
56
|
+
const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors', 'modifiers'];
|
|
53
57
|
// ---- defaults ----------------------------------------------------------------
|
|
54
58
|
const DEFAULTS = {
|
|
55
59
|
cadence: '0s',
|
|
@@ -84,6 +88,75 @@ function asStringArray(v, ctx) {
|
|
|
84
88
|
}
|
|
85
89
|
return v;
|
|
86
90
|
}
|
|
91
|
+
/**
|
|
92
|
+
* A routing capability as an author may write it: no separator, no surrounding
|
|
93
|
+
* whitespace, non-empty.
|
|
94
|
+
*
|
|
95
|
+
* Deliberately NOT a full charset rule. Capability names are opaque routing
|
|
96
|
+
* labels shared with a hub whose own validation is length + non-empty + no
|
|
97
|
+
* `personal:` prefix; imposing a charset here would reject names that already
|
|
98
|
+
* bind successfully today. The one new restriction is the reserved separator.
|
|
99
|
+
*/
|
|
100
|
+
function assertAuthoredCapability(value, ctx) {
|
|
101
|
+
if (value.trim().length === 0) {
|
|
102
|
+
throw new DefError(`${ctx}: capability names must not be empty or whitespace`);
|
|
103
|
+
}
|
|
104
|
+
if (value.includes(MODIFIER_SEPARATOR)) {
|
|
105
|
+
throw new DefError(`${ctx}: capability '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
|
|
106
|
+
'the suffix position is reserved for the modifier the engine composes at offer time ' +
|
|
107
|
+
"(a run carrying 'deep' turns the authored capability 'wise' into 'wise:deep')");
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Parse the def-level `modifiers:` block into a validated, order-insensitive
|
|
112
|
+
* set of plain names.
|
|
113
|
+
*
|
|
114
|
+
* Order is NOT preserved as meaning: the list is a vocabulary, and nothing in
|
|
115
|
+
* the engine compares two modifiers or treats one as higher than another. The
|
|
116
|
+
* array shape is only YAML's way of writing a set.
|
|
117
|
+
*/
|
|
118
|
+
function parseModifiers(v, ctx) {
|
|
119
|
+
const values = asStringArray(v, ctx);
|
|
120
|
+
if (values.length === 0) {
|
|
121
|
+
throw new DefError(`${ctx} must list at least one modifier, or be omitted entirely`);
|
|
122
|
+
}
|
|
123
|
+
const seen = new Set();
|
|
124
|
+
for (const value of values) {
|
|
125
|
+
if (value.trim().length === 0) {
|
|
126
|
+
throw new DefError(`${ctx}: modifier names must not be empty or whitespace`);
|
|
127
|
+
}
|
|
128
|
+
if (value.includes(MODIFIER_SEPARATOR)) {
|
|
129
|
+
throw new DefError(`${ctx}: modifier '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
|
|
130
|
+
'it is the separator the engine composes with');
|
|
131
|
+
}
|
|
132
|
+
if (seen.has(value))
|
|
133
|
+
throw new DefError(`${ctx}: duplicate modifier '${value}'`);
|
|
134
|
+
seen.add(value);
|
|
135
|
+
}
|
|
136
|
+
return values;
|
|
137
|
+
}
|
|
138
|
+
/** Parse a step's `escalation:` block. Cross-checks against the def's declared
|
|
139
|
+
* modifier set and the step's effective maxAttempts happen in `validateDef`,
|
|
140
|
+
* which is the first place that sees the whole def. */
|
|
141
|
+
function parseEscalation(v, ctx) {
|
|
142
|
+
if (typeof v !== 'object' || v === null || Array.isArray(v)) {
|
|
143
|
+
throw new DefError(`${ctx} must be a mapping of { after, modifier }`);
|
|
144
|
+
}
|
|
145
|
+
const raw = v;
|
|
146
|
+
assertNoUnknownKeys(raw, ['after', 'modifier'], ctx);
|
|
147
|
+
if (raw['after'] === undefined)
|
|
148
|
+
throw new DefError(`${ctx} must set 'after'`);
|
|
149
|
+
if (raw['modifier'] === undefined)
|
|
150
|
+
throw new DefError(`${ctx} must set 'modifier'`);
|
|
151
|
+
const after = asNumber(raw['after'], 0, `${ctx}.after`);
|
|
152
|
+
if (!Number.isInteger(after) || after < 1) {
|
|
153
|
+
throw new DefError(`${ctx}.after must be a positive integer (rejection count that triggers the escalated re-offer)`);
|
|
154
|
+
}
|
|
155
|
+
const modifier = asString(raw['modifier'], `${ctx}.modifier`);
|
|
156
|
+
if (modifier.trim().length === 0)
|
|
157
|
+
throw new DefError(`${ctx}.modifier must not be empty`);
|
|
158
|
+
return { after, modifier };
|
|
159
|
+
}
|
|
87
160
|
function asNumber(v, fallback, ctx) {
|
|
88
161
|
if (v === undefined)
|
|
89
162
|
return fallback;
|
|
@@ -269,6 +342,15 @@ function parseJudges(v, ctx, baseDir) {
|
|
|
269
342
|
judge.command = asString(raw.command, `judge '${name}'.command`);
|
|
270
343
|
if (raw.spec !== undefined)
|
|
271
344
|
judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
|
|
345
|
+
if (raw.capabilities !== undefined) {
|
|
346
|
+
const caps = asStringArray(raw.capabilities, `judge '${name}'.capabilities`);
|
|
347
|
+
if (caps.length === 0) {
|
|
348
|
+
throw new DefError(`judge '${name}'.capabilities must not be empty — omit the key to inherit the producing step's capabilities`);
|
|
349
|
+
}
|
|
350
|
+
for (const cap of caps)
|
|
351
|
+
assertAuthoredCapability(cap, `judge '${name}'.capabilities`);
|
|
352
|
+
judge.capabilities = caps;
|
|
353
|
+
}
|
|
272
354
|
return judge;
|
|
273
355
|
});
|
|
274
356
|
}
|
|
@@ -576,6 +658,8 @@ export function buildDef(raw, source, baseDir) {
|
|
|
576
658
|
def.x = asExtension(r.x, `workflow '${name}'.x`);
|
|
577
659
|
if (r.executors !== undefined)
|
|
578
660
|
def.executors = asStringArray(r.executors, `workflow '${name}'.executors`);
|
|
661
|
+
if (r.modifiers !== undefined)
|
|
662
|
+
def.modifiers = parseModifiers(r.modifiers, `workflow '${name}'.modifiers`);
|
|
579
663
|
return def;
|
|
580
664
|
}
|
|
581
665
|
// ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
|
|
@@ -772,7 +856,7 @@ export function parseDef(raw, source, baseDir) {
|
|
|
772
856
|
* an ordinary step, because judge orders flow through the normal
|
|
773
857
|
* eligibleFirings → applySchedule → claim → buildOrder pipeline (§7.1).
|
|
774
858
|
*/
|
|
775
|
-
function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX) {
|
|
859
|
+
function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX, producerCapabilities) {
|
|
776
860
|
if (!pat.judges || pat.judges.length === 0)
|
|
777
861
|
return [];
|
|
778
862
|
return pat.judges.map((j) => {
|
|
@@ -798,6 +882,17 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, produ
|
|
|
798
882
|
// alter another synthesized step. Absence stays absence: no empty x bag.
|
|
799
883
|
if (producerX !== undefined)
|
|
800
884
|
step.x = structuredClone(producerX);
|
|
885
|
+
// Routing: an explicit judge `capabilities:` wins; otherwise the judge
|
|
886
|
+
// INHERITS the producer's. Without inheritance every synthesized judge
|
|
887
|
+
// would be capability-silent, and a capability-silent step bypasses the
|
|
888
|
+
// claim filter entirely — any polling crew could claim the judge that
|
|
889
|
+
// gates work routed deliberately to one crew. Copied, not shared, so a
|
|
890
|
+
// later mutation of either step cannot reach the other (same contract as
|
|
891
|
+
// the `x` clone above).
|
|
892
|
+
if (j.capabilities !== undefined)
|
|
893
|
+
step.capabilities = [...j.capabilities];
|
|
894
|
+
else if (producerCapabilities !== undefined)
|
|
895
|
+
step.capabilities = [...producerCapabilities];
|
|
801
896
|
if (j.model !== undefined)
|
|
802
897
|
step.model = j.model;
|
|
803
898
|
if (j.executor !== undefined)
|
|
@@ -955,9 +1050,14 @@ function buildStep(rl, i, baseDir) {
|
|
|
955
1050
|
// any caller), mirroring the groups.length > 0 pattern below.
|
|
956
1051
|
if (rl.capabilities !== undefined) {
|
|
957
1052
|
const ls = asStringArray(rl.capabilities, `step '${name}'.capabilities`);
|
|
1053
|
+
for (const cap of ls)
|
|
1054
|
+
assertAuthoredCapability(cap, `step '${name}'.capabilities`);
|
|
958
1055
|
if (ls.length > 0)
|
|
959
1056
|
step.capabilities = ls;
|
|
960
1057
|
}
|
|
1058
|
+
if (rl.escalation !== undefined) {
|
|
1059
|
+
step.escalation = parseEscalation(rl.escalation, `step '${name}'.escalation`);
|
|
1060
|
+
}
|
|
961
1061
|
// A3: per-step max total lease lifetime (duration string, same as reapTtl).
|
|
962
1062
|
if (rl.maxLease !== undefined) {
|
|
963
1063
|
step.maxLeaseMs = parseDurationMs(asString(rl.maxLease, `step '${name}'.maxLease`));
|
|
@@ -970,7 +1070,7 @@ function buildStep(rl, i, baseDir) {
|
|
|
970
1070
|
}
|
|
971
1071
|
}
|
|
972
1072
|
const producerConsumeStems = consumes.map((c) => c.stem);
|
|
973
|
-
const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x));
|
|
1073
|
+
const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x, step.capabilities));
|
|
974
1074
|
return [step, ...judgeSteps];
|
|
975
1075
|
}
|
|
976
1076
|
// ---- validation --------------------------------------------------------------
|
|
@@ -1303,6 +1403,94 @@ export function validateDef(def) {
|
|
|
1303
1403
|
}
|
|
1304
1404
|
}
|
|
1305
1405
|
}
|
|
1406
|
+
// ---- routing modifiers and escalation ------------------------------------
|
|
1407
|
+
//
|
|
1408
|
+
// Three separate rules, each with its own precondition. They are grouped
|
|
1409
|
+
// because they all read `def.modifiers`, not because they are one check.
|
|
1410
|
+
//
|
|
1411
|
+
// R1 escalation.modifier must be a member of the def's declared set, and
|
|
1412
|
+
// a step may not carry `escalation:` at all in a def that declares no
|
|
1413
|
+
// `modifiers:` — there is no target vocabulary for it to draw from.
|
|
1414
|
+
// R2 escalation.after must be strictly less than the effective maxAttempts
|
|
1415
|
+
// of EVERY produce on the step. At judgmentRejects >= maxAttempts the
|
|
1416
|
+
// engine freezes the artifact (`model.ts` isStalled), so a rule
|
|
1417
|
+
// authored at or past that threshold re-offers a step that can never
|
|
1418
|
+
// run again. Taking the MINIMUM across produces is the conservative
|
|
1419
|
+
// reading: the step is dead as soon as its shortest-fused produce
|
|
1420
|
+
// freezes, whatever the others allow.
|
|
1421
|
+
// R3 in a def that declares `modifiers:`, every command step must author
|
|
1422
|
+
// `capabilities`. A capability-silent step bypasses the claim filter
|
|
1423
|
+
// (`engine.ts` A2) entirely, so any polling crew could claim it —
|
|
1424
|
+
// and, under composition, it would never receive a modifier suffix
|
|
1425
|
+
// either, silently opting out of the routing the def just declared.
|
|
1426
|
+
//
|
|
1427
|
+
// SCOPED DELIBERATELY to modifier-declaring defs. The plan document
|
|
1428
|
+
// states this rule unconditionally, but every def that predates
|
|
1429
|
+
// modifiers (examples/workflows/command-executor.yaml among them) has
|
|
1430
|
+
// capability-silent command steps, and the same document promises
|
|
1431
|
+
// "defs without `modifiers:` run exactly as today". Opting into the
|
|
1432
|
+
// new routing vocabulary is what turns the stricter rule on.
|
|
1433
|
+
const declaredModifiers = new Set(def.modifiers ?? []);
|
|
1434
|
+
for (const l of def.steps) {
|
|
1435
|
+
if (l.escalation === undefined)
|
|
1436
|
+
continue;
|
|
1437
|
+
if (declaredModifiers.size === 0) {
|
|
1438
|
+
errors.push(`step '${l.name}': escalation is set but workflow '${def.name}' declares no modifiers:; ` +
|
|
1439
|
+
'escalation.modifier must name a declared modifier');
|
|
1440
|
+
}
|
|
1441
|
+
else if (!declaredModifiers.has(l.escalation.modifier)) {
|
|
1442
|
+
errors.push(`step '${l.name}': escalation.modifier '${l.escalation.modifier}' is not in workflow ` +
|
|
1443
|
+
`'${def.name}'.modifiers (${[...declaredModifiers].join(', ')})`);
|
|
1444
|
+
}
|
|
1445
|
+
// An escalated re-offer is the same step's capabilities composed with the
|
|
1446
|
+
// target modifier. A step with no capabilities composes nothing, so the
|
|
1447
|
+
// re-offer would be byte-identical to the original offer: a rule that can
|
|
1448
|
+
// never route anywhere new.
|
|
1449
|
+
if (l.capabilities === undefined || l.capabilities.length === 0) {
|
|
1450
|
+
errors.push(`step '${l.name}': escalation is set but the step authors no capabilities; ` +
|
|
1451
|
+
'an escalated re-offer composes <capability>:<modifier>, so there is nothing to escalate');
|
|
1452
|
+
}
|
|
1453
|
+
// The rule is REACHABILITY: at least one owed output must be able to sit at
|
|
1454
|
+
// `after` judgment rejects while still being re-offered. That is a MAX over
|
|
1455
|
+
// the per-produce caps, not a MIN, because the engine evaluates the trigger
|
|
1456
|
+
// per owed path and drops frozen paths from the firing rather than killing
|
|
1457
|
+
// the firing:
|
|
1458
|
+
//
|
|
1459
|
+
// - eligibleFirings (model.ts) filters a step's outputs to the ones that
|
|
1460
|
+
// are still debt AND not frozen, and emits the firing when that filtered
|
|
1461
|
+
// list is non-empty. A step producing `plan` (cap 6) and `consult`
|
|
1462
|
+
// (cap 2) keeps firing for `plan` after `consult` has stalled.
|
|
1463
|
+
// - routingFor (engine.ts) then tests `f.outputs.find((p) => isEscalated(
|
|
1464
|
+
// arts.get(p), rule.after))` — the SAME filtered list. One live path over
|
|
1465
|
+
// the threshold is enough to route.
|
|
1466
|
+
//
|
|
1467
|
+
// So the shortest-fused produce freezing does not end the step, and a
|
|
1468
|
+
// MIN ceiling would reject a def whose escalation is plainly reachable
|
|
1469
|
+
// through a longer-fused produce. The `>=` is still right at the MAX: an
|
|
1470
|
+
// artifact with `judgmentRejects >= cap` is stalled (isStalled, model.ts),
|
|
1471
|
+
// therefore frozen, therefore filtered out of `f.outputs` before routingFor
|
|
1472
|
+
// ever looks at it — so `after` equal to the highest cap can never fire.
|
|
1473
|
+
const attemptCeilings = l.produces.length > 0
|
|
1474
|
+
? l.produces.map((p) => p.maxAttempts ?? l.maxAttempts)
|
|
1475
|
+
: [l.maxAttempts];
|
|
1476
|
+
const ceiling = Math.max(...attemptCeilings);
|
|
1477
|
+
if (l.escalation.after >= ceiling) {
|
|
1478
|
+
errors.push(`step '${l.name}': escalation.after (${l.escalation.after}) must be strictly less than ` +
|
|
1479
|
+
`the step's highest per-produce maxAttempts (${ceiling}); at ${ceiling} rejections every ` +
|
|
1480
|
+
'output has frozen, so the escalated re-offer could never run');
|
|
1481
|
+
}
|
|
1482
|
+
}
|
|
1483
|
+
if (declaredModifiers.size > 0) {
|
|
1484
|
+
for (const l of def.steps) {
|
|
1485
|
+
if ((l.executor ?? 'agent') !== 'command')
|
|
1486
|
+
continue;
|
|
1487
|
+
if (l.capabilities === undefined || l.capabilities.length === 0) {
|
|
1488
|
+
errors.push(`step '${l.name}': workflow '${def.name}' declares modifiers:, so every command step must ` +
|
|
1489
|
+
'author capabilities: — a capability-silent step is claimable by any crew and never ' +
|
|
1490
|
+
'receives a modifier');
|
|
1491
|
+
}
|
|
1492
|
+
}
|
|
1493
|
+
}
|
|
1306
1494
|
// Semantic invariant validation: unknown stem references and duplicate names.
|
|
1307
1495
|
if (def.invariants && def.invariants.length > 0) {
|
|
1308
1496
|
const invariantNames = new Set();
|
package/dist/src/engine.d.ts
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import type { WorkflowStatus } from './model.ts';
|
|
13
13
|
import type { SchemaIssue } from './schema.ts';
|
|
14
|
+
import type { MatchMode } from './capabilities.ts';
|
|
14
15
|
import type { Store } from './store.ts';
|
|
15
16
|
import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
|
|
16
17
|
import { OrderResolver } from './order-resolver.ts';
|
|
@@ -157,6 +158,30 @@ export interface CreateOpts {
|
|
|
157
158
|
parentWf: string;
|
|
158
159
|
parentPath: string;
|
|
159
160
|
};
|
|
161
|
+
/**
|
|
162
|
+
* The ONE routing modifier this instance carries for its whole life. Must be
|
|
163
|
+
* a member of the def's declared `modifiers` set — `createInstance` throws
|
|
164
|
+
* {@link ModifierRefusalError} otherwise, rather than starting a run that
|
|
165
|
+
* would compose capabilities no crew was ever bound to.
|
|
166
|
+
*
|
|
167
|
+
* Absent = an unmodified run: every step is offered on bare capabilities.
|
|
168
|
+
* Never mutated after creation; an escalated re-offer carries its own target
|
|
169
|
+
* modifier per-offer without rewriting this.
|
|
170
|
+
*/
|
|
171
|
+
modifier?: string;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Thrown by `createInstance` when the requested modifier is not in the def's
|
|
175
|
+
* declared `modifiers` set (including the case of a def that declares none).
|
|
176
|
+
* Its own class so the hub can map it to a 400 instead of an opaque 500 —
|
|
177
|
+
* this is a caller mistake, not an engine fault.
|
|
178
|
+
*/
|
|
179
|
+
export declare class ModifierRefusalError extends Error {
|
|
180
|
+
readonly defName: string;
|
|
181
|
+
readonly modifier: string;
|
|
182
|
+
/** The def's declared modifier set — empty when the def declares none. */
|
|
183
|
+
readonly declared: string[];
|
|
184
|
+
constructor(defName: string, modifier: string, declared: string[]);
|
|
160
185
|
}
|
|
161
186
|
/**
|
|
162
187
|
* Map a definition name to its `WorkflowDef`, or throw if there is none.
|
|
@@ -503,7 +528,23 @@ export declare class Engine {
|
|
|
503
528
|
tick(workflow: string, opts?: {
|
|
504
529
|
now?: number;
|
|
505
530
|
deep?: boolean;
|
|
531
|
+
/**
|
|
532
|
+
* The claiming crew's capabilities. OMITTING this is not the same as
|
|
533
|
+
* passing `[]`: omitted means "no filter presented" (a local operator or
|
|
534
|
+
* test driver — everything matches, as before capabilities existed),
|
|
535
|
+
* while `[]` means a crew that serves nothing and therefore matches only
|
|
536
|
+
* capability-silent steps. See `claimMatches`.
|
|
537
|
+
*/
|
|
506
538
|
capabilities?: string[];
|
|
539
|
+
/**
|
|
540
|
+
* Per-offered-capability claim mode, keyed by the COMPOSED capability
|
|
541
|
+
* (`wise:deep`), supplied by the caller that can see crew bindings — the
|
|
542
|
+
* hub. Any capability absent from the map is matched by name part
|
|
543
|
+
* (`DEFAULT_MATCH_MODE`), which is what a caller with no binding
|
|
544
|
+
* knowledge should get: the permissive tier. The pure engine never
|
|
545
|
+
* decides a mode, it only enforces the one it is handed.
|
|
546
|
+
*/
|
|
547
|
+
matchModes?: Record<string, MatchMode>;
|
|
507
548
|
}): TickResult;
|
|
508
549
|
/**
|
|
509
550
|
* The recursive tick worker. Runs this instance's own maintain → reap →
|
|
@@ -576,11 +617,23 @@ export declare class Engine {
|
|
|
576
617
|
private callsDescendTargets;
|
|
577
618
|
/**
|
|
578
619
|
* Per-step cadence + daily budget + parallel cap over the eligible firings.
|
|
579
|
-
*
|
|
580
|
-
*
|
|
581
|
-
*
|
|
620
|
+
*
|
|
621
|
+
* A2: `capabilities` is the tick caller's claim filter, matched against the
|
|
622
|
+
* step's OFFERED capabilities — the authored list composed with the modifier
|
|
623
|
+
* this firing will actually be offered under (`wise` + `deep` → `wise:deep`),
|
|
624
|
+
* which is the same list the order will carry. `claimMatches` owns the rule;
|
|
625
|
+
* see it for the four cases (no filter presented, capability-silent step,
|
|
626
|
+
* empty caller list, both non-empty) and for what `matchModes` changes.
|
|
627
|
+
* A firing this caller may not claim is deferred as `'capability-mismatch'`.
|
|
582
628
|
* Filtering here (before cadence/budget) means a mismatched firing never
|
|
583
629
|
* consumes the caller's slots and never perturbs cadence math.
|
|
630
|
+
*
|
|
631
|
+
* The filter is per FIRING, not per step, because §7 escalation is per firing:
|
|
632
|
+
* on a map step one element may have escalated to `build:deep` while its
|
|
633
|
+
* siblings are still offered at `build:standard`, and a crew bound to only one
|
|
634
|
+
* of those must be judged against the compound its own firing carries. With no
|
|
635
|
+
* escalation authored every firing of a step composes identically, so this
|
|
636
|
+
* behaves exactly as a per-step filter would.
|
|
584
637
|
*/
|
|
585
638
|
private applySchedule;
|
|
586
639
|
/** Return the effective reap TTL for a step — per-step override or engine default. */
|
|
@@ -861,7 +914,63 @@ export declare class Engine {
|
|
|
861
914
|
* make `status(parent)` throw (same stance as the §28 drift flag).
|
|
862
915
|
*/
|
|
863
916
|
private childStatusSummary;
|
|
917
|
+
/**
|
|
918
|
+
* The two per-instance facts a tick needs, from ONE run-record read: the def
|
|
919
|
+
* this instance is pinned to, and the routing modifier it carries.
|
|
920
|
+
*
|
|
921
|
+
* Offer-time composition needs the modifier inside the claim path, where the
|
|
922
|
+
* run record was not previously in scope. Reading it here — in the same
|
|
923
|
+
* `getWorkflow` the def resolution already performs, once per tick frame —
|
|
924
|
+
* keeps that cost at zero extra reads rather than one per claim.
|
|
925
|
+
*/
|
|
926
|
+
private instanceFor;
|
|
864
927
|
private defFor;
|
|
928
|
+
/**
|
|
929
|
+
* §7: the modifier ONE offer of ONE firing composes with — the run's, or the
|
|
930
|
+
* step's escalation target when the escalation rule has tripped.
|
|
931
|
+
*
|
|
932
|
+
* Derived, never stored. Every offer re-evaluates it from the artifact
|
|
933
|
+
* counters, which is what makes the transition atomic (there is no separate
|
|
934
|
+
* write that could half-apply), idempotent (recomputing it changes nothing),
|
|
935
|
+
* and self-reversing (a human `retry` zeroes `judgmentRejects`, and the very
|
|
936
|
+
* next offer composes with the run's modifier again).
|
|
937
|
+
*
|
|
938
|
+
* The trigger is per OUTPUT PATH: the firing escalates when any path it owes
|
|
939
|
+
* has taken `escalation.after` judgment rejections. For a plain step that is
|
|
940
|
+
* its single produce; for a map step each element firing escalates on its own
|
|
941
|
+
* element's count, so one bad element does not promote the whole step.
|
|
942
|
+
*
|
|
943
|
+
* Three cases return the run's modifier untouched:
|
|
944
|
+
* - the step authors no `escalation:` block — rejections run the normal
|
|
945
|
+
* retry path at the same compound until the stall brake;
|
|
946
|
+
* - no owed path has reached the threshold yet;
|
|
947
|
+
* - the run's modifier ALREADY equals the escalation target — there is
|
|
948
|
+
* nothing to promote, so no `escalated` flag and no history record. A
|
|
949
|
+
* `deep` run whose builder escalates to `deep` is a no-op, not an event.
|
|
950
|
+
*
|
|
951
|
+
* `escalation` on the result is set ONLY in the case that actually changed
|
|
952
|
+
* the routing; `claim` writes the history record from it.
|
|
953
|
+
*/
|
|
954
|
+
private routingFor;
|
|
955
|
+
/**
|
|
956
|
+
* Write the ONE artifact-history record for an escalation promotion.
|
|
957
|
+
*
|
|
958
|
+
* `version: 0` on purpose. The promotion belongs to the artifact across a
|
|
959
|
+
* whole rejection episode, not to any single produced version — the episode
|
|
960
|
+
* spans every attempt from the crossing rejection to the human `retry` that
|
|
961
|
+
* ends it, and those attempts each produce their own version. Anchoring the
|
|
962
|
+
* record to a version would either mislabel it or (since the row id mixes in
|
|
963
|
+
* the version) write one row per version, breaking the once-per-episode
|
|
964
|
+
* guarantee. `getArtifactHistory` collects version-0 events in its
|
|
965
|
+
* artifact-level `events` bucket, which is exactly where this belongs; the
|
|
966
|
+
* version the promotion took effect at is in `metadata.atVersion`.
|
|
967
|
+
*
|
|
968
|
+
* The dedupe key is `(step, firing key, episode)`. Step and key are in it
|
|
969
|
+
* because two different steps can owe the same path in different firings; the
|
|
970
|
+
* episode ordinal is what makes a SECOND promotion, after a human `retry` and
|
|
971
|
+
* three fresh rejections, a distinct row rather than a swallowed duplicate.
|
|
972
|
+
*/
|
|
973
|
+
private recordEscalation;
|
|
865
974
|
private step;
|
|
866
975
|
/**
|
|
867
976
|
* The JSON Schema (if any) declared for the artifact `art` greened by `green()`
|