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.
Files changed (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
package/CHANGELOG.md CHANGED
@@ -4,6 +4,28 @@ 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.2](https://github.com/typicalday/owenloop/compare/v0.5.1...v0.5.2) (2026-08-14)
8
+
9
+
10
+ ### Features
11
+
12
+ * 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))
13
+ * 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))
14
+ * 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))
15
+ * 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))
16
+ * 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))
17
+
18
+
19
+ ### Bug Fixes
20
+
21
+ * 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))
22
+ * 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))
23
+ * 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))
24
+ * 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))
25
+ * 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))
26
+ * 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))
27
+ * 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))
28
+
7
29
  ## [0.5.1](https://github.com/typicalday/owenloop/compare/v0.5.0...v0.5.1) (2026-08-12)
8
30
 
9
31
 
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, and [`docs/wire-contracts.md`](docs/wire-contracts.md) defines the
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
- return templateContent
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 ModelPolicy } from './model-policy.ts';
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
- /** Resolve authored model tiers and retry escalation before dispatch. */
58
- modelPolicy?: ModelPolicy;
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`?