owenloop 0.5.7 → 0.5.9

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 (111) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +7 -8
  3. package/dist/packages/work/src/agent/capability-model.d.ts +64 -82
  4. package/dist/packages/work/src/agent/capability-model.js +94 -91
  5. package/dist/packages/work/src/agent/loop.d.ts +55 -26
  6. package/dist/packages/work/src/agent/loop.js +144 -50
  7. package/dist/packages/work/src/bundle/types.d.ts +3 -3
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +206 -35
  11. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  12. package/dist/packages/work/src/exec/receipt.js +6 -6
  13. package/dist/packages/work/src/harness/child-env.js +4 -5
  14. package/dist/packages/work/src/harness/claude.js +100 -0
  15. package/dist/packages/work/src/harness/codex.js +3 -4
  16. package/dist/packages/work/src/harness/session-store.d.ts +63 -3
  17. package/dist/packages/work/src/harness/session-store.js +104 -9
  18. package/dist/packages/work/src/hub/client.d.ts +19 -4
  19. package/dist/packages/work/src/hub/client.js +7 -3
  20. package/dist/packages/work/src/hub/types.d.ts +87 -3
  21. package/dist/packages/work/src/main.js +1 -0
  22. package/dist/packages/work/src/roles/agent-run.js +46 -43
  23. package/dist/packages/work/src/roles/exec.js +2 -0
  24. package/dist/packages/work/src/roles/sessions.d.ts +3 -2
  25. package/dist/packages/work/src/roles/sessions.js +9 -2
  26. package/dist/packages/work/src/roles/settings.js +3 -1
  27. package/dist/packages/work/src/roles/shift.js +14 -2
  28. package/dist/packages/work/src/roles/util.d.ts +1 -0
  29. package/dist/packages/work/src/roles/util.js +10 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  31. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  32. package/dist/packages/work/src/settings/roster.d.ts +105 -0
  33. package/dist/packages/work/src/settings/roster.js +439 -0
  34. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  35. package/dist/packages/work/src/settings/serving.js +79 -0
  36. package/dist/packages/work/src/settings/settings.d.ts +25 -24
  37. package/dist/packages/work/src/settings/settings.js +29 -33
  38. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  39. package/dist/packages/work/src/shift/loop.js +299 -51
  40. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  41. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  42. package/dist/packages/work/src/shift/runtime.js +95 -13
  43. package/dist/packages/work/src/shift/server.js +2 -0
  44. package/dist/packages/work/src/shift/spawn.d.ts +18 -50
  45. package/dist/packages/work/src/shift/spawn.js +30 -65
  46. package/dist/packages/work/src/shift/state.d.ts +29 -2
  47. package/dist/packages/work/src/shift/state.js +45 -15
  48. package/dist/packages/work/src/usage.d.ts +1 -1
  49. package/dist/packages/work/src/usage.js +10 -5
  50. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  51. package/dist/packages/work/src/util/modifier-init.js +73 -0
  52. package/dist/src/bundle/tar.d.ts +9 -4
  53. package/dist/src/bundle/tar.js +9 -4
  54. package/dist/src/capabilities.d.ts +50 -0
  55. package/dist/src/capabilities.js +38 -0
  56. package/dist/src/cli.d.ts +15 -1
  57. package/dist/src/cli.js +1099 -32
  58. package/dist/src/config-dir.d.ts +14 -19
  59. package/dist/src/config-dir.js +16 -24
  60. package/dist/src/credentials.d.ts +1 -1
  61. package/dist/src/credentials.js +1 -1
  62. package/dist/src/crypto/index.d.ts +1 -1
  63. package/dist/src/crypto/index.js +1 -1
  64. package/dist/src/crypto/org-root.d.ts +30 -12
  65. package/dist/src/crypto/org-root.js +162 -14
  66. package/dist/src/crypto/records.d.ts +3 -0
  67. package/dist/src/crypto/records.js +8 -0
  68. package/dist/src/crypto/trust-roots.d.ts +2 -2
  69. package/dist/src/crypto/trust-roots.js +2 -2
  70. package/dist/src/defs.d.ts +6 -1
  71. package/dist/src/defs.js +203 -8
  72. package/dist/src/engine.d.ts +55 -6
  73. package/dist/src/engine.js +172 -22
  74. package/dist/src/global-config.d.ts +4 -7
  75. package/dist/src/global-config.js +4 -7
  76. package/dist/src/hub.d.ts +207 -5
  77. package/dist/src/hub.js +263 -3
  78. package/dist/src/index.d.ts +5 -5
  79. package/dist/src/index.js +3 -3
  80. package/dist/src/mcp/serve.d.ts +22 -0
  81. package/dist/src/mcp/serve.js +88 -8
  82. package/dist/src/model.d.ts +2 -0
  83. package/dist/src/model.js +32 -25
  84. package/dist/src/order-resolver.d.ts +1 -0
  85. package/dist/src/order-resolver.js +8 -1
  86. package/dist/src/schemas/index.d.ts +19 -0
  87. package/dist/src/schemas/order.v1.schema.json +13 -2
  88. package/dist/src/store/pre-commit-verifier.js +1 -1
  89. package/dist/src/store.d.ts +5 -0
  90. package/dist/src/store.js +43 -8
  91. package/dist/src/types.d.ts +64 -7
  92. package/dist/src/work-settings.d.ts +2 -4
  93. package/dist/src/work-settings.js +2 -4
  94. package/docs/agent-runner.md +2 -2
  95. package/docs/authoring.md +90 -2
  96. package/docs/bundles.md +29 -3
  97. package/docs/cli.md +456 -120
  98. package/docs/crypto.md +32 -16
  99. package/docs/design.md +70 -1
  100. package/docs/routing.md +762 -0
  101. package/docs/shift-logs.md +37 -10
  102. package/docs/wire-contracts.md +50 -7
  103. package/examples/workflows/delivery.yaml +31 -14
  104. package/examples/workflows/ship.yaml +10 -2
  105. package/package.json +1 -1
  106. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  107. package/plugins/claude-code/plugin/.mcp.json +1 -1
  108. package/plugins/claude-code/plugin/skills/author/SKILL.md +1 -2
  109. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  110. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  111. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +1 -2
package/CHANGELOG.md CHANGED
@@ -4,6 +4,47 @@ 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.9](https://github.com/typicalday/owenloop/compare/v0.5.8...v0.5.9) (2026-08-19)
8
+
9
+
10
+ ### Features
11
+
12
+ * add --scope and --priority to owenloop start, default MCP scope to repo name ([#205](https://github.com/typicalday/owenloop/issues/205)) ([1270885](https://github.com/typicalday/owenloop/commit/12708856d837b6bba40c8294ad62d76940b3944a))
13
+ * add hub retry artifact controls ([#191](https://github.com/typicalday/owenloop/issues/191)) ([2afcaf6](https://github.com/typicalday/owenloop/commit/2afcaf6321ab952be7c7895e4e85907efd4965e5))
14
+ * bind artifact values to run modifier and meta, with deterministic init ([#200](https://github.com/typicalday/owenloop/issues/200)) ([ca7c402](https://github.com/typicalday/owenloop/commit/ca7c4026ff60816987dca43dfca492610dc43b09))
15
+ * declare cleanup steps for cancelled runs ([#204](https://github.com/typicalday/owenloop/issues/204)) ([bc3d1ef](https://github.com/typicalday/owenloop/commit/bc3d1ef94ca177cafa37c697709c26bef6d3a59d))
16
+ * **shift:** advertise serving capabilities ([#194](https://github.com/typicalday/owenloop/issues/194)) ([4ff4010](https://github.com/typicalday/owenloop/commit/4ff4010c57ba91c4b12cab812d0cbd2cc4b33b75))
17
+ * stamp matched crews on orders and resolve worker rosters from the stamp ([#193](https://github.com/typicalday/owenloop/issues/193)) ([aceae05](https://github.com/typicalday/owenloop/commit/aceae055d72eb54a0da8b5edb87b4ce3caddebe5))
18
+ * sync hub org rosters into the shift cache and merge them as the weakest layers ([#190](https://github.com/typicalday/owenloop/issues/190)) ([643e2fd](https://github.com/typicalday/owenloop/commit/643e2fdfe93c4b6d9dd80cd15a211c275b130918))
19
+
20
+
21
+ ### Bug Fixes
22
+
23
+ * carry the child command output tail into a payload reject ([#197](https://github.com/typicalday/owenloop/issues/197)) ([e3ee61f](https://github.com/typicalday/owenloop/commit/e3ee61fbc51598d883a310e33b84abafb399aa98))
24
+ * do not hold hub claims a shift cannot dispatch ([#209](https://github.com/typicalday/owenloop/issues/209)) ([5b61433](https://github.com/typicalday/owenloop/commit/5b61433cab384107f5cf126253e0fd1b3c62e0c2))
25
+ * escalate failed command diagnostics through ask ([#203](https://github.com/typicalday/owenloop/issues/203)) ([583d4c3](https://github.com/typicalday/owenloop/commit/583d4c34772d32035b7067abc71620bf46143acc))
26
+ * log claude adapter turn activity ([#188](https://github.com/typicalday/owenloop/issues/188)) ([c9ba76a](https://github.com/typicalday/owenloop/commit/c9ba76a8948dd5dc0733a204313374322f2fa22f))
27
+ * make the bind shorthand resolve a key path instead of the whole value ([#206](https://github.com/typicalday/owenloop/issues/206)) ([03ac38c](https://github.com/typicalday/owenloop/commit/03ac38ca2066cf6e23592f693e484601efdd6ebb))
28
+ * make the modifier vocabulary consistent across parse, start, and bind ([#210](https://github.com/typicalday/owenloop/issues/210)) ([afd33a6](https://github.com/typicalday/owenloop/commit/afd33a6d5f49525e3e7e65a8df481af6b53c1a55))
29
+ * reserve dispatch capacity for exec orders ([#207](https://github.com/typicalday/owenloop/issues/207)) ([91c6a66](https://github.com/typicalday/owenloop/commit/91c6a66869b5b2c06c9db228818c6bb19c7ede9e))
30
+ * **shift:** release exited workers and resweep braked steps ([#196](https://github.com/typicalday/owenloop/issues/196)) ([1b23815](https://github.com/typicalday/owenloop/commit/1b238153caf5d4dacdce7731c06b64830dbe15ce))
31
+
32
+ ## [0.5.8](https://github.com/typicalday/owenloop/compare/v0.5.7...v0.5.8) (2026-08-17)
33
+
34
+
35
+ ### Features
36
+
37
+ * add layered crew roster routing ([#186](https://github.com/typicalday/owenloop/issues/186)) ([9fc1a55](https://github.com/typicalday/owenloop/commit/9fc1a55447bc48806d5b8775a9bdd5340f9258b8))
38
+ * add owenloop routing command group for alerts and reroute rules ([#182](https://github.com/typicalday/owenloop/issues/182)) ([012a16a](https://github.com/typicalday/owenloop/commit/012a16a97f01b2c98691403a2a8a9eba201ef889))
39
+ * let the offer caller reroute a composed capability ([#181](https://github.com/typicalday/owenloop/issues/181)) ([7240e61](https://github.com/typicalday/owenloop/commit/7240e61ee4263290d9eb1adfea96c3659a657ca9))
40
+
41
+
42
+ ### Bug Fixes
43
+
44
+ * key session resume on the engine task, not on the per-firing run id ([#177](https://github.com/typicalday/owenloop/issues/177)) ([f1d4fbb](https://github.com/typicalday/owenloop/commit/f1d4fbbccab3048558a5319293e87bb3bcff22e8))
45
+ * relay a command step's output to the worker log on success too ([#185](https://github.com/typicalday/owenloop/issues/185)) ([618a3e0](https://github.com/typicalday/owenloop/commit/618a3e0309d79bb680f521c19fc183934f6f7bf8))
46
+ * surface a hub instance's terminal status in `instance show` ([#187](https://github.com/typicalday/owenloop/issues/187)) ([42e53bd](https://github.com/typicalday/owenloop/commit/42e53bd809bfe8e93a27ffa2941b8a89b0161bcc))
47
+
7
48
  ## [0.5.7](https://github.com/typicalday/owenloop/compare/v0.5.6...v0.5.7) (2026-08-16)
8
49
 
9
50
 
package/README.md CHANGED
@@ -453,8 +453,10 @@ through the same small CLI (`create`, `tick`, `green`, `reject`, …).
453
453
  [`docs/cli.md`](docs/cli.md) has the full command reference and a hand-driven
454
454
  walkthrough of a pipeline — including a rejection knock-back and a stall —
455
455
  and [`examples/workflows`](examples/workflows) has seventeen runnable defs, from a
456
- minimal review loop ([`delivery`](examples/workflows/delivery.yaml)) to a
457
- full production line ([`ship`](examples/workflows/ship.yaml)), a
456
+ minimal review loop written to teach the wiring
457
+ ([`delivery`](examples/workflows/delivery.yaml) — a four-step example, not the
458
+ production line) to a production-shaped pipeline
459
+ ([`ship`](examples/workflows/ship.yaml)), a
458
460
  collections-heavy research pipeline
459
461
  ([`research`](examples/workflows/research.yaml)), and a compiler that turns
460
462
  live vendor docs into a new gate-checked def
@@ -487,12 +489,9 @@ hub's own def hashes. `owenloop agent new
487
489
  Setting up a machine from scratch? `owenloop setup` may sign you in as a human
488
490
  and, when needed, mint or rekey and store a Scoped Identity. Setup writes only
489
491
  `hubOrigin` into the execution settings file, preserving the other keys. The
490
- file is `$OWENLOOP_CONFIG_DIR/settings.json` when `OWENLOOP_CONFIG_DIR` is set
491
- to a non-blank absolute path; otherwise `$XDG_CONFIG_HOME/owenloop/settings.json`
492
- when `XDG_CONFIG_HOME` is non-blank; otherwise
493
- `$HOME/.config/owenloop/settings.json`. Prefer `OWENLOOP_CONFIG_DIR` when
494
- running several shifts on one machine — `XDG_CONFIG_HOME` also relocates `gh`,
495
- `git`, and `gcloud` for every command step the shift dispatches. For
492
+ file is `$HOME/.owenloop/settings.json` by default (`OWENLOOP_CONFIG_DIR` can
493
+ provide an absolute isolated directory; `XDG_CONFIG_HOME` is not consulted).
494
+ For
496
495
  a non-default account,
497
496
  setup only prints the `OWENLOOP_ACCOUNT=<name>` instruction. Setup probes and,
498
497
  when needed, converges the bundled `owenloop` plugins for Claude Code and Codex.
@@ -1,58 +1,34 @@
1
1
  /**
2
- * Resolve an order's COMPOSED CAPABILITY to the model and reasoning effort this
3
- * machine runs it at.
2
+ * Resolve an order's COMPOSED CAPABILITY to the local crew roster that serves
3
+ * it. The hub decides what grade of work an order is; the machine decides
4
+ * which locally available harness, model, and effort serve that grade.
4
5
  *
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}`:
6
+ * A crew roster is a capability-to-candidate-list table. It is deliberately
7
+ * local: accounts, quotas, and operator preference do not belong in a shared
8
+ * workflow definition. The candidates are ordered so an operator can express
9
+ * a preferred harness with a deterministic fallback:
12
10
  *
13
11
  * ```json
14
12
  * {
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" }
13
+ * "roster": {
14
+ * "wise:deep": [
15
+ * { "harness": "<harness-id>", "model": "<model-id>", "effort": "xhigh" }
16
+ * ]
19
17
  * }
20
18
  * }
21
19
  * ```
22
20
  *
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.
21
+ * The one behavior worth carrying out of the retired tier code is EFFORT
22
+ * VALIDITY CHECKING. It happens at settings load and checks only the neutral
23
+ * start contract's five rungs.
41
24
  *
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.
25
+ * IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL. That would require a
26
+ * table of model identifiers which this repository has no ground truth for.
27
+ * Harnesses may validate effort as a harness-wide property or pass it through;
28
+ * neither case establishes a per-model constraint. A table here would either
29
+ * restate `EFFORT_LADDER` under model-shaped keys or invent a restriction that
30
+ * rejects a valid operator config. A future per-harness check belongs on the
31
+ * adapter contract, not in this neutral shape module.
56
32
  */
57
33
  /** Reasoning rungs the neutral start contract accepts, weakest to strongest. */
58
34
  export declare const EFFORT_LADDER: readonly ["low", "medium", "high", "xhigh", "max"];
@@ -66,58 +42,64 @@ export type Effort = (typeof EFFORT_LADDER)[number];
66
42
  export declare const MODIFIER_SEPARATOR = ":";
67
43
  /** The bare capability name inside a composed capability. `wise:deep` → `wise`. */
68
44
  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 {
45
+ /** One ordered candidate in a crew roster row. */
46
+ export interface RosterCandidate {
47
+ harness: string;
71
48
  model: string;
72
49
  effort: string;
73
50
  }
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 {
51
+ /** A crew roster keyed by composed capability (`wise:deep`) or bare name (`wise`). */
52
+ export type Roster = Readonly<Record<string, readonly RosterCandidate[]>>;
53
+ /** Thrown when the crew roster is unusable. Never silently repaired. */
54
+ export declare class RosterError extends Error {
78
55
  }
79
56
  /**
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.
57
+ * Validate a crew roster, throwing on the first unusable row. Every fault this
58
+ * function catches is certainly wrong: an empty capability, an old object row,
59
+ * an empty candidate list, or a candidate missing any required part would make
60
+ * routing ambiguous hours after the configuration mistake.
88
61
  *
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.
62
+ * It intentionally does not judge whether a model id exists or whether a
63
+ * particular model accepts an effort; see this module's header.
96
64
  */
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. */
65
+ export declare function validateRoster(roster: Readonly<Record<string, unknown>>, ctx?: string): void;
66
+ /** Which roster row served the order: its exact compound, or the bare name fallback. */
99
67
  export type CapabilityMatch = 'exact' | 'bare';
100
- export interface CapabilityResolution {
68
+ export interface CapabilityCandidates {
101
69
  /** The capability the winning row was keyed by (`wise:deep` or `wise`). */
102
70
  capability: string;
103
71
  match: CapabilityMatch;
104
- model: string;
105
- effort: string;
72
+ candidates: readonly RosterCandidate[];
106
73
  }
107
74
  /**
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).
75
+ * Resolve an order's capabilities against the merged roster: exact compound
76
+ * row first, then the bare name-part row, else `undefined` (the caller
77
+ * refuses the order — never a default model).
111
78
  *
112
79
  * TWO PASSES ACROSS ALL CAPABILITIES, NOT ONE PASS PER CAPABILITY. A step may
113
80
  * 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.
81
+ * across the set. Resolving capability by capability instead would let a bare
82
+ * row on the first capability beat an exact row on the second — the shift
83
+ * would run a deep order at the bare grade purely because of authoring order.
118
84
  *
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.
85
+ * The bare row is what makes a name-match fallback order resolvable at all:
86
+ * the hub can stamp `wise:deep` on an order that a crew bound only to
87
+ * `wise:standard` then claims, and that shift has no `wise:deep` row by
88
+ * construction.
89
+ */
90
+ export declare function resolveCapabilityCandidates(roster: Roster, capabilities: readonly string[]): CapabilityCandidates | undefined;
91
+ export type SelectionOutcome = {
92
+ kind: 'selected';
93
+ candidate: RosterCandidate;
94
+ } | {
95
+ kind: 'harness-policy';
96
+ offered: readonly string[];
97
+ } | {
98
+ kind: 'none-available';
99
+ offered: readonly string[];
100
+ };
101
+ /**
102
+ * Select the first usable candidate in roster order. A non-empty step harness
103
+ * is a policy constraint; it narrows candidates before availability is tested.
122
104
  */
123
- export declare function resolveCapabilityModel(map: CapabilityModelMap, capabilities: readonly string[]): CapabilityResolution | undefined;
105
+ export declare function selectCandidate(candidates: readonly RosterCandidate[], stepHarness: string | undefined, isAvailable: (harnessId: string) => boolean): SelectionOutcome;
@@ -1,58 +1,34 @@
1
1
  /**
2
- * Resolve an order's COMPOSED CAPABILITY to the model and reasoning effort this
3
- * machine runs it at.
2
+ * Resolve an order's COMPOSED CAPABILITY to the local crew roster that serves
3
+ * it. The hub decides what grade of work an order is; the machine decides
4
+ * which locally available harness, model, and effort serve that grade.
4
5
  *
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}`:
6
+ * A crew roster is a capability-to-candidate-list table. It is deliberately
7
+ * local: accounts, quotas, and operator preference do not belong in a shared
8
+ * workflow definition. The candidates are ordered so an operator can express
9
+ * a preferred harness with a deterministic fallback:
12
10
  *
13
11
  * ```json
14
12
  * {
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" }
13
+ * "roster": {
14
+ * "wise:deep": [
15
+ * { "harness": "<harness-id>", "model": "<model-id>", "effort": "xhigh" }
16
+ * ]
19
17
  * }
20
18
  * }
21
19
  * ```
22
20
  *
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.
21
+ * The one behavior worth carrying out of the retired tier code is EFFORT
22
+ * VALIDITY CHECKING. It happens at settings load and checks only the neutral
23
+ * start contract's five rungs.
41
24
  *
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.
25
+ * IT DELIBERATELY DOES NOT CHECK EFFORT AGAINST THE MODEL. That would require a
26
+ * table of model identifiers which this repository has no ground truth for.
27
+ * Harnesses may validate effort as a harness-wide property or pass it through;
28
+ * neither case establishes a per-model constraint. A table here would either
29
+ * restate `EFFORT_LADDER` under model-shaped keys or invent a restriction that
30
+ * rejects a valid operator config. A future per-harness check belongs on the
31
+ * adapter contract, not in this neutral shape module.
56
32
  */
57
33
  /** Reasoning rungs the neutral start contract accepts, weakest to strongest. */
58
34
  export const EFFORT_LADDER = ['low', 'medium', 'high', 'xhigh', 'max'];
@@ -68,70 +44,80 @@ export function capabilityNamePart(capability) {
68
44
  const at = capability.indexOf(MODIFIER_SEPARATOR);
69
45
  return at === -1 ? capability : capability.slice(0, at);
70
46
  }
71
- /** Thrown when the capability map is unusable. Never silently repaired. */
72
- export class CapabilityModelError extends Error {
47
+ /** Thrown when the crew roster is unusable. Never silently repaired. */
48
+ export class RosterError extends Error {
73
49
  }
74
50
  function isEffort(value) {
75
51
  return EFFORT_LADDER.includes(value);
76
52
  }
77
53
  /**
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.
54
+ * Validate a crew roster, throwing on the first unusable row. Every fault this
55
+ * function catches is certainly wrong: an empty capability, an old object row,
56
+ * an empty candidate list, or a candidate missing any required part would make
57
+ * routing ambiguous hours after the configuration mistake.
86
58
  *
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.
59
+ * It intentionally does not judge whether a model id exists or whether a
60
+ * particular model accepts an effort; see this module's header.
94
61
  */
95
- export function validateCapabilityModels(map, ctx = 'capabilityModels') {
96
- for (const [capability, raw] of Object.entries(map)) {
62
+ export function validateRoster(roster, ctx = 'roster') {
63
+ for (const [capability, rawCandidates] of Object.entries(roster)) {
97
64
  if (capability.trim() === '') {
98
- throw new CapabilityModelError(`${ctx}: a capability key may not be empty`);
65
+ throw new RosterError(`${ctx}: a capability key may not be empty`);
99
66
  }
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)}`);
67
+ if (!Array.isArray(rawCandidates)) {
68
+ throw new RosterError(`${ctx}['${capability}'] must be a non-empty array of { harness: "<harness-id>", model: "<model-id>", effort: "high" }, got ${JSON.stringify(rawCandidates)}`);
102
69
  }
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`);
70
+ if (rawCandidates.length === 0) {
71
+ throw new RosterError(`${ctx}['${capability}'] must be a non-empty array of candidates`);
107
72
  }
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)}`);
73
+ for (const [index, rawCandidate] of rawCandidates.entries()) {
74
+ const entryCtx = `${ctx}['${capability}'][${index}]`;
75
+ if (typeof rawCandidate !== 'object' || rawCandidate === null || Array.isArray(rawCandidate)) {
76
+ throw new RosterError(`${entryCtx} must be an object with exactly 'harness', 'model', and 'effort', got ${JSON.stringify(rawCandidate)}`);
77
+ }
78
+ const candidate = rawCandidate;
79
+ const keys = Object.keys(candidate);
80
+ const unknown = keys.filter((key) => !['harness', 'model', 'effort'].includes(key));
81
+ if (unknown.length > 0) {
82
+ throw new RosterError(`${entryCtx} has unknown key(s): ${unknown.join(', ')}`);
83
+ }
84
+ for (const key of ['harness', 'model']) {
85
+ if (typeof candidate[key] !== 'string' || candidate[key].trim() === '') {
86
+ throw new RosterError(`${entryCtx}.${key} must be a non-empty string`);
87
+ }
88
+ }
89
+ const effort = candidate['effort'];
90
+ if (typeof effort !== 'string' || !isEffort(effort)) {
91
+ throw new RosterError(`${entryCtx}.effort must be one of ${EFFORT_LADDER.join(', ')}, got ${JSON.stringify(effort)}`);
92
+ }
111
93
  }
112
94
  }
113
95
  }
96
+ /** Read only a declared roster row; inherited Object.prototype names are never capabilities. */
97
+ function ownCandidates(roster, capability) {
98
+ return Object.prototype.hasOwnProperty.call(roster, capability) ? roster[capability] : undefined;
99
+ }
114
100
  /**
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).
101
+ * Resolve an order's capabilities against the merged roster: exact compound
102
+ * row first, then the bare name-part row, else `undefined` (the caller
103
+ * refuses the order — never a default model).
118
104
  *
119
105
  * TWO PASSES ACROSS ALL CAPABILITIES, NOT ONE PASS PER CAPABILITY. A step may
120
106
  * 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.
107
+ * across the set. Resolving capability by capability instead would let a bare
108
+ * row on the first capability beat an exact row on the second — the shift
109
+ * would run a deep order at the bare grade purely because of authoring order.
125
110
  *
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.
111
+ * The bare row is what makes a name-match fallback order resolvable at all:
112
+ * the hub can stamp `wise:deep` on an order that a crew bound only to
113
+ * `wise:standard` then claims, and that shift has no `wise:deep` row by
114
+ * construction.
129
115
  */
130
- export function resolveCapabilityModel(map, capabilities) {
116
+ export function resolveCapabilityCandidates(roster, capabilities) {
131
117
  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 };
118
+ const candidates = ownCandidates(roster, capability);
119
+ if (candidates !== undefined)
120
+ return { capability, match: 'exact', candidates };
135
121
  }
136
122
  for (const capability of capabilities) {
137
123
  const name = capabilityNamePart(capability);
@@ -140,9 +126,26 @@ export function resolveCapabilityModel(map, capabilities) {
140
126
  // exact hit as a fallback in the resolution record.
141
127
  if (name === capability)
142
128
  continue;
143
- const row = map[name];
144
- if (row !== undefined)
145
- return { capability: name, match: 'bare', model: row.model, effort: row.effort };
129
+ const candidates = ownCandidates(roster, name);
130
+ if (candidates !== undefined)
131
+ return { capability: name, match: 'bare', candidates };
146
132
  }
147
133
  return undefined;
148
134
  }
135
+ /**
136
+ * Select the first usable candidate in roster order. A non-empty step harness
137
+ * is a policy constraint; it narrows candidates before availability is tested.
138
+ */
139
+ export function selectCandidate(candidates, stepHarness, isAvailable) {
140
+ const survivors = stepHarness !== undefined && stepHarness !== ''
141
+ ? candidates.filter((candidate) => candidate.harness === stepHarness)
142
+ : candidates;
143
+ if (survivors.length === 0) {
144
+ return { kind: 'harness-policy', offered: candidates.map((candidate) => candidate.harness) };
145
+ }
146
+ for (const candidate of survivors) {
147
+ if (isAvailable(candidate.harness))
148
+ return { kind: 'selected', candidate };
149
+ }
150
+ return { kind: 'none-available', offered: survivors.map((candidate) => candidate.harness) };
151
+ }