owenloop 0.5.1 → 0.5.3
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 +30 -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/claude.js +69 -9
- package/dist/packages/work/src/harness/codex.js +56 -8
- package/dist/packages/work/src/harness/contract.d.ts +65 -1
- package/dist/packages/work/src/harness/contract.js +56 -0
- 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/bundle/runtime.d.ts +1 -1
- package/dist/src/bundle/runtime.js +9 -0
- package/dist/src/capabilities.d.ts +93 -0
- package/dist/src/capabilities.js +101 -0
- package/dist/src/cli.js +37 -11
- 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/agent-runner.md +26 -1
- 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/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format is based on
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
|
|
5
5
|
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.5.3](https://github.com/typicalday/owenloop/compare/v0.5.2...v0.5.3) (2026-08-14)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* let owenloop start pick a run modifier ([#154](https://github.com/typicalday/owenloop/issues/154)) ([a412b5b](https://github.com/typicalday/owenloop/commit/a412b5b334b5fd228d4558b50125e069512bd860))
|
|
13
|
+
* neutral permissionMode vocabulary across harness adapters ([#156](https://github.com/typicalday/owenloop/issues/156)) ([c96340f](https://github.com/typicalday/owenloop/commit/c96340f2d3f910e49838c6fbd68ed817e52f7ddc))
|
|
14
|
+
|
|
15
|
+
## [0.5.2](https://github.com/typicalday/owenloop/compare/v0.5.1...v0.5.2) (2026-08-14)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
### Features
|
|
19
|
+
|
|
20
|
+
* durable on-disk shift logs (shift.log + per-run worker logs) ([#150](https://github.com/typicalday/owenloop/issues/150)) ([ad95862](https://github.com/typicalday/owenloop/commit/ad9586292b2d977f3c0be3f2f005c537eba03bfc))
|
|
21
|
+
* pass consumed inputs to command steps and warn on cwd fallback ([#149](https://github.com/typicalday/owenloop/issues/149)) ([76f0783](https://github.com/typicalday/owenloop/commit/76f0783201eb93b8af8ece4c8910952bec781b61))
|
|
22
|
+
* per-crew tier profiles with model and effort resolution ([#140](https://github.com/typicalday/owenloop/issues/140)) ([98d96bb](https://github.com/typicalday/owenloop/commit/98d96bbeaf3e17e0aa097389b766248f78e87451))
|
|
23
|
+
* route agent orders by composed capability instead of model tiers ([#152](https://github.com/typicalday/owenloop/issues/152)) ([a48068b](https://github.com/typicalday/owenloop/commit/a48068b547e16d1db763e3bc739c8277ae1fb628))
|
|
24
|
+
* routing modifiers, capability composition, and escalation in the engine ([#151](https://github.com/typicalday/owenloop/issues/151)) ([6d440a9](https://github.com/typicalday/owenloop/commit/6d440a951bc15bd961e4004c4652f6e87c88560c))
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### Bug Fixes
|
|
28
|
+
|
|
29
|
+
* brake a shift step on worker failure, not on dispatch count ([#146](https://github.com/typicalday/owenloop/issues/146)) ([2b4c0c6](https://github.com/typicalday/owenloop/commit/2b4c0c657173c114377daa432b878a8dd12d0c05))
|
|
30
|
+
* distinguish a corrupt session record from a schema-invalid one ([#145](https://github.com/typicalday/owenloop/issues/145)) ([c65416b](https://github.com/typicalday/owenloop/commit/c65416b523efa5784a2e8f173ac44bd6b77435b0))
|
|
31
|
+
* issue a retry-safe owed target version so producer submits can sign ([#143](https://github.com/typicalday/owenloop/issues/143)) ([1a27f65](https://github.com/typicalday/owenloop/commit/1a27f65eb2abdba50f52931fd08c99ae3b3d2df6))
|
|
32
|
+
* measure escalation.after against the highest per-produce maxAttempts ([#153](https://github.com/typicalday/owenloop/issues/153)) ([0d654f9](https://github.com/typicalday/owenloop/commit/0d654f9e593ecdbc10a50cad8f59a5a73036016f))
|
|
33
|
+
* normalize a JSON-string submit value before signing it ([#147](https://github.com/typicalday/owenloop/issues/147)) ([2f67b12](https://github.com/typicalday/owenloop/commit/2f67b12453631ca9425ea66050eeb9afbbd32817))
|
|
34
|
+
* read the capability payloads under the hub's own field names ([#142](https://github.com/typicalday/owenloop/issues/142)) ([eb53609](https://github.com/typicalday/owenloop/commit/eb536093f4202afdd491269e7aab07bb60e21a1f))
|
|
35
|
+
* stop the agent-run MCP hold child from releasing its parent's claim ([#144](https://github.com/typicalday/owenloop/issues/144)) ([4b46fa8](https://github.com/typicalday/owenloop/commit/4b46fa84c15074924a937ff0954ee967bf4a1523))
|
|
36
|
+
|
|
7
37
|
## [0.5.1](https://github.com/typicalday/owenloop/compare/v0.5.0...v0.5.1) (2026-08-12)
|
|
8
38
|
|
|
9
39
|
|
package/README.md
CHANGED
|
@@ -443,6 +443,11 @@ explicitly; `--all` serves all Crews for the Scoped Identity. `shift next` waits
|
|
|
443
443
|
up to 90 seconds by default. For flags, JSON output, daemon behavior, and exit
|
|
444
444
|
codes, see the [`shift` reference](docs/cli.md#shift--foreground-daemon-and-client).
|
|
445
445
|
|
|
446
|
+
A running shift also writes to disk: its own dispatch record as JSON Lines in
|
|
447
|
+
`shift.log`, and each dispatched worker's stdout and stderr in `<run>.log`. Both
|
|
448
|
+
outlive the shift, which is what makes a postmortem possible after a shift dies.
|
|
449
|
+
See [`docs/shift-logs.md`](docs/shift-logs.md).
|
|
450
|
+
|
|
446
451
|
**Want to see or drive the machinery yourself?** Everything above goes
|
|
447
452
|
through the same small CLI (`create`, `tick`, `green`, `reject`, …).
|
|
448
453
|
[`docs/cli.md`](docs/cli.md) has the full command reference and a hand-driven
|
|
@@ -736,8 +741,10 @@ owenloop is a faithful, decoupled implementation of a dataflow-engine spec.
|
|
|
736
741
|
firing rule, forward cascade, the reject kinds, the liveness rules, and the concurrency
|
|
737
742
|
model — cross-referenced from the source. [`docs/cli.md`](docs/cli.md) has the full
|
|
738
743
|
command reference, [`docs/authoring.md`](docs/authoring.md) has the full YAML
|
|
739
|
-
grammar,
|
|
740
|
-
versioned trust-boundary records
|
|
744
|
+
grammar, [`docs/wire-contracts.md`](docs/wire-contracts.md) defines the
|
|
745
|
+
versioned trust-boundary records, and
|
|
746
|
+
[`docs/shift-logs.md`](docs/shift-logs.md) is the on-disk log contract a shift
|
|
747
|
+
writes and an uploader reads.
|
|
741
748
|
|
|
742
749
|
---
|
|
743
750
|
|
|
@@ -57,6 +57,18 @@ export interface BriefSpec {
|
|
|
57
57
|
origin: string;
|
|
58
58
|
account: string;
|
|
59
59
|
shiftId?: string;
|
|
60
|
+
/**
|
|
61
|
+
* The run's routing modifier (`express` | `standard` | `deep` — whatever the
|
|
62
|
+
* def declared), as the caller asked for at `start_run`. Absent on a run
|
|
63
|
+
* started without one.
|
|
64
|
+
*/
|
|
65
|
+
modifier?: string;
|
|
66
|
+
/**
|
|
67
|
+
* `true` when the engine re-offered THIS step at its escalation target
|
|
68
|
+
* instead of the run's own modifier — the step is on the recovery path after
|
|
69
|
+
* repeated rejections, not a first attempt.
|
|
70
|
+
*/
|
|
71
|
+
escalated?: boolean;
|
|
60
72
|
}
|
|
61
73
|
/**
|
|
62
74
|
* Substitute the four dispatch tokens into a step template.
|
|
@@ -77,6 +89,15 @@ export declare function renderBrief(templateContent: string, spec: BriefSpec): s
|
|
|
77
89
|
* with no value or a null array entry, which is what `hold`'s parser expects.
|
|
78
90
|
* (The shape originated with the deleted stamp path, which had to survive a YAML
|
|
79
91
|
* args array; it is kept because it is still the correct, unambiguous form.)
|
|
92
|
+
*
|
|
93
|
+
* `--never-release` is load-bearing. This child runs its own lease loop, but it
|
|
94
|
+
* is NOT the holder of record: `agent-run`'s `exec` loop already claimed the
|
|
95
|
+
* order and is the only thing entitled to hand it back. Without the flag the
|
|
96
|
+
* child's stdin EOF — which in `--mcp` mode is just the harness closing the
|
|
97
|
+
* JSON-RPC transport — fired a final-breath `release`, unclaiming a run the
|
|
98
|
+
* agent was still working. The mount's terminal guard then fast-failed every
|
|
99
|
+
* later get_order/submit, the agent finished with nothing, and the shift
|
|
100
|
+
* re-dispatched the same order into a fresh worker that did it all again.
|
|
80
101
|
*/
|
|
81
102
|
export declare function buildOwenloopMcp(spec: BriefSpec, binPath?: string, execPath?: string): {
|
|
82
103
|
command: string;
|
|
@@ -19,7 +19,7 @@ function composite(spec) {
|
|
|
19
19
|
* (no accidental `$&` expansion from template text the author controls).
|
|
20
20
|
*/
|
|
21
21
|
export function renderBrief(templateContent, spec) {
|
|
22
|
-
|
|
22
|
+
const substituted = templateContent
|
|
23
23
|
.split(ORDER_TOKEN)
|
|
24
24
|
.join(composite(spec))
|
|
25
25
|
.split(ORIGIN_TOKEN)
|
|
@@ -28,6 +28,37 @@ export function renderBrief(templateContent, spec) {
|
|
|
28
28
|
.join(spec.account)
|
|
29
29
|
.split(SHIFT_TOKEN)
|
|
30
30
|
.join(spec.shiftId ?? '');
|
|
31
|
+
const routing = renderRoutingLine(spec);
|
|
32
|
+
return routing === '' ? substituted : `${routing}\n\n${substituted}`;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* The run's depth, stated to the agent in one line, PREPENDED rather than
|
|
36
|
+
* substituted into a token.
|
|
37
|
+
*
|
|
38
|
+
* A token would only reach agents whose def author remembered to write it, and
|
|
39
|
+
* the whole point of the modifier is that the SAME step body runs at three
|
|
40
|
+
* different depths — the author has one template and cannot mark every place
|
|
41
|
+
* depth matters. Prepending puts it in front of every agent on every run at no
|
|
42
|
+
* cost to existing bundles.
|
|
43
|
+
*
|
|
44
|
+
* It is deliberately DESCRIPTIVE, not directive: it tells the agent what depth
|
|
45
|
+
* the run was started at and leaves the interpretation to the step's own body.
|
|
46
|
+
* The modifier already decided the model and effort before this line was
|
|
47
|
+
* written; restating it as an order ("think harder") would be the brief trying
|
|
48
|
+
* to do the router's job.
|
|
49
|
+
*
|
|
50
|
+
* Empty string when the run carries no modifier — a run started without one has
|
|
51
|
+
* nothing true to say here, and a line reading "modifier: none" would invite an
|
|
52
|
+
* agent to reason about an absence that means nothing.
|
|
53
|
+
*/
|
|
54
|
+
function renderRoutingLine(spec) {
|
|
55
|
+
if (spec.modifier === undefined || spec.modifier === '')
|
|
56
|
+
return '';
|
|
57
|
+
const escalated = spec.escalated === true
|
|
58
|
+
? ' This step was RE-OFFERED at a deeper modifier after repeated rejections of its output —' +
|
|
59
|
+
' it is a recovery attempt, not a first pass.'
|
|
60
|
+
: '';
|
|
61
|
+
return `Routing: this run was started at the '${spec.modifier}' depth modifier.${escalated}`;
|
|
31
62
|
}
|
|
32
63
|
/**
|
|
33
64
|
* The born-bound work-holder mount handed to `HarnessAdapter.start` as
|
|
@@ -40,6 +71,15 @@ export function renderBrief(templateContent, spec) {
|
|
|
40
71
|
* with no value or a null array entry, which is what `hold`'s parser expects.
|
|
41
72
|
* (The shape originated with the deleted stamp path, which had to survive a YAML
|
|
42
73
|
* args array; it is kept because it is still the correct, unambiguous form.)
|
|
74
|
+
*
|
|
75
|
+
* `--never-release` is load-bearing. This child runs its own lease loop, but it
|
|
76
|
+
* is NOT the holder of record: `agent-run`'s `exec` loop already claimed the
|
|
77
|
+
* order and is the only thing entitled to hand it back. Without the flag the
|
|
78
|
+
* child's stdin EOF — which in `--mcp` mode is just the harness closing the
|
|
79
|
+
* JSON-RPC transport — fired a final-breath `release`, unclaiming a run the
|
|
80
|
+
* agent was still working. The mount's terminal guard then fast-failed every
|
|
81
|
+
* later get_order/submit, the agent finished with nothing, and the shift
|
|
82
|
+
* re-dispatched the same order into a fresh worker that did it all again.
|
|
43
83
|
*/
|
|
44
84
|
export function buildOwenloopMcp(spec, binPath = resolveOwenloopBin(), execPath = process.execPath) {
|
|
45
85
|
return {
|
|
@@ -56,6 +96,7 @@ export function buildOwenloopMcp(spec, binPath = resolveOwenloopBin(), execPath
|
|
|
56
96
|
spec.account,
|
|
57
97
|
`--shift=${spec.shiftId ?? ''}`,
|
|
58
98
|
'--mcp',
|
|
99
|
+
'--never-release',
|
|
59
100
|
],
|
|
60
101
|
};
|
|
61
102
|
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve an order's COMPOSED CAPABILITY to the model and reasoning effort this
|
|
3
|
+
* machine runs it at.
|
|
4
|
+
*
|
|
5
|
+
* The hub decides WHAT grade of work an order is (`builder` composed with the
|
|
6
|
+
* run's `deep` modifier → `builder:deep`). It never decides which model serves
|
|
7
|
+
* that grade. That decision is local to the operator's machine, because it is a
|
|
8
|
+
* statement about accounts, quotas and taste — three things a shared workflow
|
|
9
|
+
* definition has no business asserting.
|
|
10
|
+
*
|
|
11
|
+
* So the settings file carries a flat map from capability to `{model, effort}`:
|
|
12
|
+
*
|
|
13
|
+
* ```json
|
|
14
|
+
* {
|
|
15
|
+
* "capabilityModels": {
|
|
16
|
+
* "wise:deep": { "model": "<model-id>", "effort": "xhigh" },
|
|
17
|
+
* "build:deep": { "model": "<model-id>", "effort": "xhigh" },
|
|
18
|
+
* "wise": { "model": "<model-id>", "effort": "high" }
|
|
19
|
+
* }
|
|
20
|
+
* }
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* `<model-id>` is whatever string the shift's harness accepts as a model. This
|
|
24
|
+
* module never enumerates real model ids: it ships as neutral runtime, and
|
|
25
|
+
* `test/vendor-gate.test.ts` forbids a harness vendor's names here. `README.md`
|
|
26
|
+
* and `docs/` carry worked examples with real ids.
|
|
27
|
+
*
|
|
28
|
+
* THIS REPLACES `tierMap`/`tierProfiles` OUTRIGHT. A tier was an abstract rung
|
|
29
|
+
* (`fast`/`standard`/`strong`/`strongest`) that a machine then mapped to a
|
|
30
|
+
* model, and the tier ladder could not express the thing the operator actually
|
|
31
|
+
* wanted: "Luna at low effort" and "Fable at max effort" are different routes,
|
|
32
|
+
* but the ladder welded model choice and depth into one ordered axis, so one
|
|
33
|
+
* could not vary without the other. A capability is just a name. What serves it
|
|
34
|
+
* is a local lookup, and depth rides on the capability's modifier suffix rather
|
|
35
|
+
* than on a rung.
|
|
36
|
+
*
|
|
37
|
+
* The one behavior worth carrying out of the tier code is EFFORT VALIDITY
|
|
38
|
+
* CHECKING, which now happens at settings load rather than at resolution time.
|
|
39
|
+
* It checks the effort against `EFFORT_LADDER` — the neutral start contract's
|
|
40
|
+
* own five rungs — and nothing else.
|
|
41
|
+
*
|
|
42
|
+
* IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL. Doing that would
|
|
43
|
+
* require a table of real model ids in this file, which the vendor gate forbids
|
|
44
|
+
* and which this repository has no ground truth for anyway. Look at what the
|
|
45
|
+
* harness adapters in `src/harness/` actually enforce: one validates effort
|
|
46
|
+
* against a closed union that is a property of THE HARNESS — every model that
|
|
47
|
+
* harness runs accepts the same rungs — and the other passes effort through
|
|
48
|
+
* without validating it at all. Neither knows a per-model constraint, so a
|
|
49
|
+
* table here would be either a restatement of `EFFORT_LADDER` under
|
|
50
|
+
* model-shaped keys, or an invention that blocks a valid operator config. The
|
|
51
|
+
* real per-harness check belongs on the adapter contract; see the follow-up
|
|
52
|
+
* noted in `validateCapabilityModels`.
|
|
53
|
+
*
|
|
54
|
+
* The old snap-up/ceiling-refusal logic in `resolveEffort` is gone with the
|
|
55
|
+
* ladder it resolved through: there is no abstract rung left to snap.
|
|
56
|
+
*/
|
|
57
|
+
/** Reasoning rungs the neutral start contract accepts, weakest to strongest. */
|
|
58
|
+
export declare const EFFORT_LADDER: readonly ["low", "medium", "high", "xhigh", "max"];
|
|
59
|
+
export type Effort = (typeof EFFORT_LADDER)[number];
|
|
60
|
+
/**
|
|
61
|
+
* What separates a capability's NAME PART from its MODIFIER: `wise:deep` is the
|
|
62
|
+
* name `wise` at the modifier `deep`. Split on the FIRST separator, matching
|
|
63
|
+
* the engine's own `capabilityName` — a capability name may not contain `:`
|
|
64
|
+
* (install-time rule), so anything after the first one is modifier territory.
|
|
65
|
+
*/
|
|
66
|
+
export declare const MODIFIER_SEPARATOR = ":";
|
|
67
|
+
/** The bare capability name inside a composed capability. `wise:deep` → `wise`. */
|
|
68
|
+
export declare function capabilityNamePart(capability: string): string;
|
|
69
|
+
/** One settings row: the model that serves a capability, and how hard it thinks. */
|
|
70
|
+
export interface CapabilityModelRow {
|
|
71
|
+
model: string;
|
|
72
|
+
effort: string;
|
|
73
|
+
}
|
|
74
|
+
/** The settings map, keyed by composed capability (`wise:deep`) or bare name (`wise`). */
|
|
75
|
+
export type CapabilityModelMap = Readonly<Record<string, CapabilityModelRow>>;
|
|
76
|
+
/** Thrown when the capability map is unusable. Never silently repaired. */
|
|
77
|
+
export declare class CapabilityModelError extends Error {
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Validate the map, throwing on the first unusable row. Returns nothing: every
|
|
81
|
+
* fault this function can see is certainly wrong.
|
|
82
|
+
*
|
|
83
|
+
* WHAT IT CATCHES — a capability key that is empty, a row that is not an object,
|
|
84
|
+
* a missing or empty `model`, and an `effort` that is not one of
|
|
85
|
+
* `EFFORT_LADDER`. Each is wrong under every harness and every model, and a
|
|
86
|
+
* shift that started anyway would refuse or misroute its first matching order
|
|
87
|
+
* hours later, far from the typo.
|
|
88
|
+
*
|
|
89
|
+
* WHAT IT DOES NOT CATCH — an effort a particular MODEL or HARNESS rejects, and
|
|
90
|
+
* a model id that does not exist. Neither is knowable here (see this module's
|
|
91
|
+
* header). FOLLOW-UP: `HarnessAdapter` is the right owner for the first one —
|
|
92
|
+
* an adapter that validates effort against a closed union could declare that
|
|
93
|
+
* union, and a composition root could check every row against every registered
|
|
94
|
+
* adapter at shift start. Until then those faults surface at the vendor API on
|
|
95
|
+
* the first order that lands on the bad row.
|
|
96
|
+
*/
|
|
97
|
+
export declare function validateCapabilityModels(map: Readonly<Record<string, unknown>>, ctx?: string): void;
|
|
98
|
+
/** Which row served the order: its exact compound, or the bare name fallback. */
|
|
99
|
+
export type CapabilityMatch = 'exact' | 'bare';
|
|
100
|
+
export interface CapabilityResolution {
|
|
101
|
+
/** The capability the winning row was keyed by (`wise:deep` or `wise`). */
|
|
102
|
+
capability: string;
|
|
103
|
+
match: CapabilityMatch;
|
|
104
|
+
model: string;
|
|
105
|
+
effort: string;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Resolve an order's capabilities against the map: exact compound row first,
|
|
109
|
+
* then the bare name-part row, else `undefined` (the caller REFUSES the order —
|
|
110
|
+
* never a default model).
|
|
111
|
+
*
|
|
112
|
+
* TWO PASSES ACROSS ALL CAPABILITIES, NOT ONE PASS PER CAPABILITY. A step may
|
|
113
|
+
* author several capabilities, and the hub's claim gate is itself exact-first
|
|
114
|
+
* across the set (§4/§5: "lookup mirrors the claim rule"). Resolving capability
|
|
115
|
+
* by capability instead would let a bare row on the FIRST capability beat an
|
|
116
|
+
* exact row on the second — the shift would run a `builder:deep` order at the
|
|
117
|
+
* bare `builder` grade purely because of authoring order.
|
|
118
|
+
*
|
|
119
|
+
* The bare row is what makes a NAME-MATCH FALLBACK order resolvable at all: the
|
|
120
|
+
* hub stamps `wise:deep` on an order that a crew bound only to `wise:standard`
|
|
121
|
+
* then claims, and that shift has no `wise:deep` row by construction.
|
|
122
|
+
*/
|
|
123
|
+
export declare function resolveCapabilityModel(map: CapabilityModelMap, capabilities: readonly string[]): CapabilityResolution | undefined;
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve an order's COMPOSED CAPABILITY to the model and reasoning effort this
|
|
3
|
+
* machine runs it at.
|
|
4
|
+
*
|
|
5
|
+
* The hub decides WHAT grade of work an order is (`builder` composed with the
|
|
6
|
+
* run's `deep` modifier → `builder:deep`). It never decides which model serves
|
|
7
|
+
* that grade. That decision is local to the operator's machine, because it is a
|
|
8
|
+
* statement about accounts, quotas and taste — three things a shared workflow
|
|
9
|
+
* definition has no business asserting.
|
|
10
|
+
*
|
|
11
|
+
* So the settings file carries a flat map from capability to `{model, effort}`:
|
|
12
|
+
*
|
|
13
|
+
* ```json
|
|
14
|
+
* {
|
|
15
|
+
* "capabilityModels": {
|
|
16
|
+
* "wise:deep": { "model": "<model-id>", "effort": "xhigh" },
|
|
17
|
+
* "build:deep": { "model": "<model-id>", "effort": "xhigh" },
|
|
18
|
+
* "wise": { "model": "<model-id>", "effort": "high" }
|
|
19
|
+
* }
|
|
20
|
+
* }
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* `<model-id>` is whatever string the shift's harness accepts as a model. This
|
|
24
|
+
* module never enumerates real model ids: it ships as neutral runtime, and
|
|
25
|
+
* `test/vendor-gate.test.ts` forbids a harness vendor's names here. `README.md`
|
|
26
|
+
* and `docs/` carry worked examples with real ids.
|
|
27
|
+
*
|
|
28
|
+
* THIS REPLACES `tierMap`/`tierProfiles` OUTRIGHT. A tier was an abstract rung
|
|
29
|
+
* (`fast`/`standard`/`strong`/`strongest`) that a machine then mapped to a
|
|
30
|
+
* model, and the tier ladder could not express the thing the operator actually
|
|
31
|
+
* wanted: "Luna at low effort" and "Fable at max effort" are different routes,
|
|
32
|
+
* but the ladder welded model choice and depth into one ordered axis, so one
|
|
33
|
+
* could not vary without the other. A capability is just a name. What serves it
|
|
34
|
+
* is a local lookup, and depth rides on the capability's modifier suffix rather
|
|
35
|
+
* than on a rung.
|
|
36
|
+
*
|
|
37
|
+
* The one behavior worth carrying out of the tier code is EFFORT VALIDITY
|
|
38
|
+
* CHECKING, which now happens at settings load rather than at resolution time.
|
|
39
|
+
* It checks the effort against `EFFORT_LADDER` — the neutral start contract's
|
|
40
|
+
* own five rungs — and nothing else.
|
|
41
|
+
*
|
|
42
|
+
* IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL. Doing that would
|
|
43
|
+
* require a table of real model ids in this file, which the vendor gate forbids
|
|
44
|
+
* and which this repository has no ground truth for anyway. Look at what the
|
|
45
|
+
* harness adapters in `src/harness/` actually enforce: one validates effort
|
|
46
|
+
* against a closed union that is a property of THE HARNESS — every model that
|
|
47
|
+
* harness runs accepts the same rungs — and the other passes effort through
|
|
48
|
+
* without validating it at all. Neither knows a per-model constraint, so a
|
|
49
|
+
* table here would be either a restatement of `EFFORT_LADDER` under
|
|
50
|
+
* model-shaped keys, or an invention that blocks a valid operator config. The
|
|
51
|
+
* real per-harness check belongs on the adapter contract; see the follow-up
|
|
52
|
+
* noted in `validateCapabilityModels`.
|
|
53
|
+
*
|
|
54
|
+
* The old snap-up/ceiling-refusal logic in `resolveEffort` is gone with the
|
|
55
|
+
* ladder it resolved through: there is no abstract rung left to snap.
|
|
56
|
+
*/
|
|
57
|
+
/** Reasoning rungs the neutral start contract accepts, weakest to strongest. */
|
|
58
|
+
export const EFFORT_LADDER = ['low', 'medium', 'high', 'xhigh', 'max'];
|
|
59
|
+
/**
|
|
60
|
+
* What separates a capability's NAME PART from its MODIFIER: `wise:deep` is the
|
|
61
|
+
* name `wise` at the modifier `deep`. Split on the FIRST separator, matching
|
|
62
|
+
* the engine's own `capabilityName` — a capability name may not contain `:`
|
|
63
|
+
* (install-time rule), so anything after the first one is modifier territory.
|
|
64
|
+
*/
|
|
65
|
+
export const MODIFIER_SEPARATOR = ':';
|
|
66
|
+
/** The bare capability name inside a composed capability. `wise:deep` → `wise`. */
|
|
67
|
+
export function capabilityNamePart(capability) {
|
|
68
|
+
const at = capability.indexOf(MODIFIER_SEPARATOR);
|
|
69
|
+
return at === -1 ? capability : capability.slice(0, at);
|
|
70
|
+
}
|
|
71
|
+
/** Thrown when the capability map is unusable. Never silently repaired. */
|
|
72
|
+
export class CapabilityModelError extends Error {
|
|
73
|
+
}
|
|
74
|
+
function isEffort(value) {
|
|
75
|
+
return EFFORT_LADDER.includes(value);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Validate the map, throwing on the first unusable row. Returns nothing: every
|
|
79
|
+
* fault this function can see is certainly wrong.
|
|
80
|
+
*
|
|
81
|
+
* WHAT IT CATCHES — a capability key that is empty, a row that is not an object,
|
|
82
|
+
* a missing or empty `model`, and an `effort` that is not one of
|
|
83
|
+
* `EFFORT_LADDER`. Each is wrong under every harness and every model, and a
|
|
84
|
+
* shift that started anyway would refuse or misroute its first matching order
|
|
85
|
+
* hours later, far from the typo.
|
|
86
|
+
*
|
|
87
|
+
* WHAT IT DOES NOT CATCH — an effort a particular MODEL or HARNESS rejects, and
|
|
88
|
+
* a model id that does not exist. Neither is knowable here (see this module's
|
|
89
|
+
* header). FOLLOW-UP: `HarnessAdapter` is the right owner for the first one —
|
|
90
|
+
* an adapter that validates effort against a closed union could declare that
|
|
91
|
+
* union, and a composition root could check every row against every registered
|
|
92
|
+
* adapter at shift start. Until then those faults surface at the vendor API on
|
|
93
|
+
* the first order that lands on the bad row.
|
|
94
|
+
*/
|
|
95
|
+
export function validateCapabilityModels(map, ctx = 'capabilityModels') {
|
|
96
|
+
for (const [capability, raw] of Object.entries(map)) {
|
|
97
|
+
if (capability.trim() === '') {
|
|
98
|
+
throw new CapabilityModelError(`${ctx}: a capability key may not be empty`);
|
|
99
|
+
}
|
|
100
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
|
|
101
|
+
throw new CapabilityModelError(`${ctx}['${capability}'] must be an object with 'model' and 'effort', got ${JSON.stringify(raw)}`);
|
|
102
|
+
}
|
|
103
|
+
const row = raw;
|
|
104
|
+
const model = row['model'];
|
|
105
|
+
if (typeof model !== 'string' || model.trim() === '') {
|
|
106
|
+
throw new CapabilityModelError(`${ctx}['${capability}'].model must be a non-empty string`);
|
|
107
|
+
}
|
|
108
|
+
const effort = row['effort'];
|
|
109
|
+
if (typeof effort !== 'string' || !isEffort(effort)) {
|
|
110
|
+
throw new CapabilityModelError(`${ctx}['${capability}'].effort must be one of ${EFFORT_LADDER.join(', ')}, got ${JSON.stringify(effort)}`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Resolve an order's capabilities against the map: exact compound row first,
|
|
116
|
+
* then the bare name-part row, else `undefined` (the caller REFUSES the order —
|
|
117
|
+
* never a default model).
|
|
118
|
+
*
|
|
119
|
+
* TWO PASSES ACROSS ALL CAPABILITIES, NOT ONE PASS PER CAPABILITY. A step may
|
|
120
|
+
* author several capabilities, and the hub's claim gate is itself exact-first
|
|
121
|
+
* across the set (§4/§5: "lookup mirrors the claim rule"). Resolving capability
|
|
122
|
+
* by capability instead would let a bare row on the FIRST capability beat an
|
|
123
|
+
* exact row on the second — the shift would run a `builder:deep` order at the
|
|
124
|
+
* bare `builder` grade purely because of authoring order.
|
|
125
|
+
*
|
|
126
|
+
* The bare row is what makes a NAME-MATCH FALLBACK order resolvable at all: the
|
|
127
|
+
* hub stamps `wise:deep` on an order that a crew bound only to `wise:standard`
|
|
128
|
+
* then claims, and that shift has no `wise:deep` row by construction.
|
|
129
|
+
*/
|
|
130
|
+
export function resolveCapabilityModel(map, capabilities) {
|
|
131
|
+
for (const capability of capabilities) {
|
|
132
|
+
const row = map[capability];
|
|
133
|
+
if (row !== undefined)
|
|
134
|
+
return { capability, match: 'exact', model: row.model, effort: row.effort };
|
|
135
|
+
}
|
|
136
|
+
for (const capability of capabilities) {
|
|
137
|
+
const name = capabilityNamePart(capability);
|
|
138
|
+
// Skip a capability that IS its own name part — the first pass already
|
|
139
|
+
// tried that key, and reporting it as a `bare` match would misreport an
|
|
140
|
+
// exact hit as a fallback in the resolution record.
|
|
141
|
+
if (name === capability)
|
|
142
|
+
continue;
|
|
143
|
+
const row = map[name];
|
|
144
|
+
if (row !== undefined)
|
|
145
|
+
return { capability: name, match: 'bare', model: row.model, effort: row.effort };
|
|
146
|
+
}
|
|
147
|
+
return undefined;
|
|
148
|
+
}
|
|
@@ -4,9 +4,9 @@ import type { ConsumedVerifier } from '../consumed-verifier.ts';
|
|
|
4
4
|
import type { NormalizedStepSpec } from '../bundle/types.ts';
|
|
5
5
|
import type { HarnessAdapter } from '../harness/contract.ts';
|
|
6
6
|
import { type SessionRecord } from '../harness/session-store.ts';
|
|
7
|
-
import { type
|
|
7
|
+
import { type CapabilityModelMap, type CapabilityResolution } from './capability-model.ts';
|
|
8
8
|
/** Discriminated result of one worker life; the role maps these to exit codes. */
|
|
9
|
-
export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
|
|
9
|
+
export type AgentRunOutcome = 'submitted' | 'completed' | 'misroute' | 'no-template' | 'no-harness' | 'incompatible-harness-policy' | 'unresolvable-capability' | 'unverified-consumed' | 'session-store-failed' | 'no-submit' | 'killed' | 'lease-lost' | 'ownership-error' | 'hub-unreachable' | 'stopped';
|
|
10
10
|
/**
|
|
11
11
|
* Locate the normalized step spec for an order. Injected because the lookup is
|
|
12
12
|
* I/O (the verified workflow store) and because resolving the local definition
|
|
@@ -54,8 +54,18 @@ export interface AgentRunLoopOptions {
|
|
|
54
54
|
cwd: string;
|
|
55
55
|
loadStep: StepLoader;
|
|
56
56
|
resolveAdapter: AdapterResolver;
|
|
57
|
-
/**
|
|
58
|
-
|
|
57
|
+
/**
|
|
58
|
+
* THIS MACHINE'S capability → `{model, effort}` map, straight from the
|
|
59
|
+
* settings file (plan §5). The loop resolves the order's composed capabilities
|
|
60
|
+
* against it before dispatch and REFUSES the order when nothing matches —
|
|
61
|
+
* there is no default model here, by design.
|
|
62
|
+
*
|
|
63
|
+
* Absent (or empty) means the shift declared no map at all, which makes every
|
|
64
|
+
* capability-bearing order unresolvable. That is deliberate: a shift that
|
|
65
|
+
* forgot its map should say so on the first order, not run everything on a
|
|
66
|
+
* hardcoded model.
|
|
67
|
+
*/
|
|
68
|
+
capabilityModels?: CapabilityModelMap;
|
|
59
69
|
/** Gate dynamic values and rejection reasons before any prompt rendering. */
|
|
60
70
|
consumedVerifier?: ConsumedVerifier;
|
|
61
71
|
/** Append one session record. Wired to `appendSession` by the role. */
|
|
@@ -119,6 +129,39 @@ export interface ConfirmOptions {
|
|
|
119
129
|
*/
|
|
120
130
|
cancelled?: () => boolean;
|
|
121
131
|
}
|
|
132
|
+
/**
|
|
133
|
+
* How this order's model was decided.
|
|
134
|
+
*
|
|
135
|
+
* `resolved` — a settings row matched; `resolution` names it, plus the model
|
|
136
|
+
* and effort the harness starts with.
|
|
137
|
+
* `refused` — the order named capabilities and NONE of them, exact or bare,
|
|
138
|
+
* has a row. The order is handed back; nothing launches. Plan
|
|
139
|
+
* §5: "never a silent default model".
|
|
140
|
+
* `unrouted` — the order named NO capabilities at all, so there is nothing to
|
|
141
|
+
* look up. This is not a failure: a def that declares no
|
|
142
|
+
* `modifiers:` may author capability-silent steps, and those
|
|
143
|
+
* have always run at the harness's own default model. The loop
|
|
144
|
+
* passes no model and no effort, exactly as it did for a step
|
|
145
|
+
* with no authored tier before this scheme existed.
|
|
146
|
+
*/
|
|
147
|
+
export type OrderRouting = {
|
|
148
|
+
kind: 'resolved';
|
|
149
|
+
resolution: CapabilityResolution;
|
|
150
|
+
} | {
|
|
151
|
+
kind: 'refused';
|
|
152
|
+
capabilities: readonly string[];
|
|
153
|
+
} | {
|
|
154
|
+
kind: 'unrouted';
|
|
155
|
+
};
|
|
156
|
+
/**
|
|
157
|
+
* Resolve an order's composed capabilities against this machine's map.
|
|
158
|
+
*
|
|
159
|
+
* ONLY `packet.capabilities` is consulted. `packet.model` — the def's authored
|
|
160
|
+
* tier name under the retired scheme — is deliberately ignored: a tier is an
|
|
161
|
+
* abstract rung with no meaning left, and reading it as a model id would put a
|
|
162
|
+
* literal `strong` on the wire to a vendor.
|
|
163
|
+
*/
|
|
164
|
+
export declare function resolveOrderRouting(packet: OrderPacket, map: CapabilityModelMap | undefined): OrderRouting;
|
|
122
165
|
/**
|
|
123
166
|
* Poll `get_order` at `intervalMs` for at most `graceMs`, answering ONE
|
|
124
167
|
* question: did the hub see the agent's `submit`?
|