pantheon-opencode 1.6.3-beta.2 → 1.6.3-beta.21

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 (69) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +143 -0
  4. package/README.md +21 -3
  5. package/README.pt-BR.md +1 -1
  6. package/bin/pantheon-init.mjs +46 -28
  7. package/package.json +1 -1
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/decision-router-budget.mjs +103 -3
  11. package/scripts/decision-router-v2-budget.mjs +2 -2
  12. package/scripts/decision-router.mjs +88 -6
  13. package/scripts/install/cli-ui.mjs +2 -1
  14. package/scripts/install/decision-router-config.mjs +53 -0
  15. package/scripts/install/interactive.mjs +103 -9
  16. package/scripts/install/opencode.mjs +101 -30
  17. package/scripts/install/plugin.mjs +17 -0
  18. package/scripts/jev-live-probe.mjs +212 -0
  19. package/scripts/skill-search.mjs +273 -0
  20. package/scripts/sync-tui.mjs +11 -0
  21. package/skills-lock.json +1 -0
  22. package/src/agents/aphrodite.md +34 -1
  23. package/src/agents/apollo.md +227 -0
  24. package/src/agents/athena.md +26 -0
  25. package/src/agents/demeter.md +33 -0
  26. package/src/agents/gaia.md +24 -0
  27. package/src/agents/hephaestus.md +24 -0
  28. package/src/agents/hermes.md +33 -0
  29. package/src/agents/iris.md +24 -0
  30. package/src/agents/mnemosyne.md +25 -3
  31. package/src/agents/nyx.md +50 -22
  32. package/src/agents/prometheus.md +242 -1
  33. package/src/agents/talos.md +24 -0
  34. package/src/agents/themis.md +24 -0
  35. package/src/agents/zeus.md +67 -6
  36. package/src/pantheon/j-telemetry-file.ts +96 -0
  37. package/src/pantheon/j1-approvals.ts +123 -0
  38. package/src/pantheon/jev-decision-tool.ts +268 -34
  39. package/src/pantheon/jev-decisions.ts +92 -8
  40. package/src/pantheon/jev-escalation.ts +1 -1
  41. package/src/pantheon/jev-quality-score.ts +7 -2
  42. package/src/pantheon/jev-rank-verify.ts +661 -0
  43. package/src/pantheon/jev-risk-gate.ts +75 -8
  44. package/src/pantheon/local-decision-budget.ts +170 -3
  45. package/src/pantheon/local-decision-router.ts +16 -0
  46. package/src/pantheon/local-decision-turn.ts +39 -4
  47. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  48. package/src/pantheon/pantheon-decision-catalog.ts +9 -2
  49. package/src/pantheon/v2-decision-budget.ts +4 -2
  50. package/src/plugin-v2.ts +94 -7
  51. package/src/plugins/tui/dist/server-v2.d.ts +14 -6
  52. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  53. package/src/plugins/tui/dist/server-v2.js +16 -9
  54. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  55. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  56. package/src/plugins/tui/dist/tui-v2.js +560 -4
  57. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  58. package/src/plugins/tui/dist/tui.js +1 -1
  59. package/src/plugins/tui/package-lock.json +2 -2
  60. package/src/plugins/tui/package.json +1 -1
  61. package/src/plugins/tui/src/index-v2.tsx +6 -0
  62. package/src/plugins/tui/src/server-v2.ts +14 -7
  63. package/src/plugins/tui/src/whats-new-highlights.ts +317 -0
  64. package/src/plugins/tui/src/whats-new-open.ts +120 -0
  65. package/src/plugins/tui/src/whats-new-state.ts +128 -0
  66. package/src/plugins/tui/src/whats-new.tsx +172 -0
  67. package/src/routing.yml +1 -0
  68. package/src/skills/README.md +1 -1
  69. package/src/skills/prompt-refinery/SKILL.md +41 -0
@@ -24,8 +24,11 @@
24
24
  */
25
25
  import { readUserDecisionRouterConfig } from '../../scripts/install/decision-router-config.mjs'
26
26
  import {
27
+ checkJevEnvelope,
27
28
  consumeJevDecisionResult,
28
29
  isJevDecisionPreset,
30
+ JEV_EXPLICIT_ENVELOPE_KEYS,
31
+ JEV_PRESET_ENVELOPE_KEYS,
29
32
  type JevDecisionPreparation,
30
33
  type JevHostSkill,
31
34
  type NativeJevRouteFailure,
@@ -41,7 +44,19 @@ import {
41
44
  J4_QUALITY_SCORE_POINT,
42
45
  type QualityScoreEvaluation,
43
46
  qualityVerdict,
47
+ REVIEW_ENVELOPE_KEYS,
44
48
  } from './jev-quality-score.ts'
49
+ import {
50
+ buildJevOrderRequest,
51
+ buildJevRankRequest,
52
+ buildJevVerifyRequest,
53
+ consumeJevOrderResult,
54
+ consumeJevRankResult,
55
+ consumeJevVerifyResult,
56
+ ORDER_ENVELOPE_KEYS,
57
+ RANK_ENVELOPE_KEYS,
58
+ VERIFY_ENVELOPE_KEYS,
59
+ } from './jev-rank-verify.ts'
45
60
  import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
46
61
  import {
47
62
  openLocalDecisionBudgetLedger,
@@ -70,7 +85,8 @@ export interface V2JevDecisionRuntime {
70
85
  /**
71
86
  * Allowlisted specialist callers for explicit-questions mode (parsed from
72
87
  * `PANTHEON_JEV_SPECIALIST_CALLERS` by the plugin wiring). Empty/absent =
73
- * Zeus only. Preset modes stay Zeus-only regardless.
88
+ * Zeus only. Preset and v3.1 modes (skills, delegation, review, rank,
89
+ * verify) stay Zeus-only regardless.
74
90
  */
75
91
  readonly specialistCallers?: readonly string[]
76
92
  /**
@@ -98,11 +114,12 @@ export const SPECIALIST_CALLERS_FLAG_ENV = 'PANTHEON_JEV_SPECIALIST_CALLERS'
98
114
 
99
115
  /**
100
116
  * Parse the caller allowlist from the flag's CSV value. Unset/empty = Zeus
101
- * only (the default). Preset modes (skills, delegation, review) stay
102
- * Zeus-only regardless of the flag: owner/skill selection and result
103
- * scoring are orchestration decisions; specialists may ask bounded typed
104
- * questions mid-task, nothing else. Lives in the plugin wiring (which owns
105
- * flag reads); this module receives the parsed list via the runtime.
117
+ * only (the default). Preset and v3.1 modes (skills, delegation, review,
118
+ * rank, verify) stay Zeus-only regardless of the flag: owner/skill selection,
119
+ * result scoring, candidate ranking and claim verification are orchestration
120
+ * decisions; specialists may ask bounded typed questions mid-task, nothing
121
+ * else. Lives in the plugin wiring (which owns flag reads); this module
122
+ * receives the parsed list via the runtime.
106
123
  */
107
124
  export function specialistCallerAllowlist(flagValue: string | undefined): readonly string[] {
108
125
  const raw = String(flagValue ?? '').trim()
@@ -118,6 +135,12 @@ export type JevDecisionRunFailure =
118
135
  | 'CALLER_NOT_ALLOWED'
119
136
  | 'REVIEW_INPUT_INVALID'
120
137
  | 'CRITERIA_INVALID'
138
+ | 'RANK_INPUT_INVALID'
139
+ | 'CANDIDATE_INVALID'
140
+ | 'ORDER_INPUT_INVALID'
141
+ | 'ORDER_CANDIDATE_INVALID'
142
+ | 'VERIFY_INPUT_INVALID'
143
+ | 'CLAIM_INVALID'
121
144
  | 'CONTEXT_UNAVAILABLE'
122
145
  | 'CONFIG_UNAVAILABLE'
123
146
  | 'DISABLED'
@@ -131,6 +154,7 @@ export type JevDecisionRunFailure =
131
154
  | 'PRESET_INVALID'
132
155
  | 'RESERVATION_DENIED'
133
156
  | 'DECISION_CALL_FAILED'
157
+ | 'USAGE_EVIDENCE_UNAVAILABLE'
134
158
  | 'USAGE_UNRECONCILED'
135
159
 
136
160
  interface JevToolContext {
@@ -139,8 +163,12 @@ interface JevToolContext {
139
163
  agent?: unknown
140
164
  }
141
165
 
142
- function refusal(reasonCode: JevDecisionRunFailure): string {
143
- return JSON.stringify({ advisory: false, effect: 'none', reasonCode })
166
+ function refusal(reasonCode: JevDecisionRunFailure, detail?: string): string {
167
+ return JSON.stringify(
168
+ detail === undefined
169
+ ? { advisory: false, effect: 'none', reasonCode }
170
+ : { advisory: false, effect: 'none', reasonCode, detail },
171
+ )
144
172
  }
145
173
 
146
174
  function isNonBlankString(value: unknown): value is string {
@@ -159,15 +187,24 @@ function reviewRefusalSkipReason(reasonCode: JevDecisionRunFailure): string {
159
187
  /**
160
188
  * Every gate-chain failure the shared runner can produce. It is
161
189
  * {@link JevDecisionRunFailure} minus the tool-surface properties:
162
- * `CALLER_NOT_ALLOWED` (the caller check) and the review mode's input
163
- * validation (`REVIEW_INPUT_INVALID` / `CRITERIA_INVALID`) — all three are
164
- * properties of the explicit tool surface, whose input the caller supplies
165
- * directly, not of the gate chain; the J1/J3 shadow observers run the same
166
- * chain for any agent and can never produce them.
190
+ * `CALLER_NOT_ALLOWED` (the caller check) and the input validation of the
191
+ * prebuilt-request modes — the review mode (`REVIEW_INPUT_INVALID` /
192
+ * `CRITERIA_INVALID`) and the v3.1 rank and verify modes
193
+ * (`RANK_INPUT_INVALID` / `CANDIDATE_INVALID` / `VERIFY_INPUT_INVALID` /
194
+ * `CLAIM_INVALID`). All of these are properties of the explicit tool surface,
195
+ * whose input the caller supplies directly, not of the gate chain; the
196
+ * J1/J3 shadow observers run the same chain for any agent and can never
197
+ * produce them.
167
198
  */
168
199
  export type GatedNativeJevFailure = Exclude<
169
200
  JevDecisionRunFailure,
170
- 'CALLER_NOT_ALLOWED' | 'REVIEW_INPUT_INVALID' | 'CRITERIA_INVALID'
201
+ | 'CALLER_NOT_ALLOWED'
202
+ | 'REVIEW_INPUT_INVALID'
203
+ | 'CRITERIA_INVALID'
204
+ | 'RANK_INPUT_INVALID'
205
+ | 'CANDIDATE_INVALID'
206
+ | 'VERIFY_INPUT_INVALID'
207
+ | 'CLAIM_INVALID'
171
208
  >
172
209
 
173
210
  /** The minimal runtime slice the gate chain needs. */
@@ -264,6 +301,14 @@ export async function runGatedNativeJevCall(params: {
264
301
  )
265
302
  if (!selection.ok) return { ok: false, reasonCode: selection.reasonCode }
266
303
 
304
+ // Cloudflare Workers AI has no supported native-usage evidence parser yet.
305
+ // Reject its Jev route before permission, request preparation, or budget
306
+ // reservation; otherwise the provider could be called and leave a pending
307
+ // reservation when reconciliation cannot be verified.
308
+ if (selection.selection.provider === 'cloudflare-workers-jev') {
309
+ return { ok: false, reasonCode: 'USAGE_EVIDENCE_UNAVAILABLE' }
310
+ }
311
+
267
312
  if (typeof params.runtime.permissionAssert !== 'function') {
268
313
  return { ok: false, reasonCode: 'PERMISSION_UNAVAILABLE' }
269
314
  }
@@ -409,10 +454,14 @@ export async function runJevDecision(
409
454
  ? (toolContext as JevToolContext)
410
455
  : undefined
411
456
  const caller = context?.agent
412
- if (typeof caller !== 'string' || caller.length === 0) return refusal('CALLER_NOT_ALLOWED')
457
+ if (typeof caller !== 'string' || caller.length === 0)
458
+ return refusal('CALLER_NOT_ALLOWED', 'CALLER_NOT_ALLOWLISTED')
413
459
  const allowlist = runtime.specialistCallers ?? []
414
460
  if (caller !== 'zeus' && !allowlist.includes(caller)) {
415
- return refusal('CALLER_NOT_ALLOWED')
461
+ return refusal(
462
+ 'CALLER_NOT_ALLOWED',
463
+ 'CALLER_NOT_ALLOWLISTED — allowlist this caller via PANTHEON_JEV_SPECIALIST_CALLERS (then restart) or ask Zeus to route',
464
+ )
416
465
  }
417
466
 
418
467
  const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
@@ -423,10 +472,51 @@ export async function runJevDecision(
423
472
  if (caller !== 'zeus' && requested.mode !== undefined) {
424
473
  return refusal('CALLER_NOT_ALLOWED')
425
474
  }
475
+ // The ONE envelope gate every path passes through before its builder:
476
+ // schemaVersion required, unknown keys rejected — explicit questions,
477
+ // presets, review, rank and verify alike (beta.10 claimed this contract;
478
+ // beta.12 applies it uniformly). Builders keep their semantic checks.
479
+ const envelopeKeys =
480
+ requested.mode === undefined
481
+ ? JEV_EXPLICIT_ENVELOPE_KEYS
482
+ : requested.mode === 'review'
483
+ ? REVIEW_ENVELOPE_KEYS
484
+ : requested.mode === 'rank'
485
+ ? RANK_ENVELOPE_KEYS
486
+ : requested.mode === 'verify'
487
+ ? VERIFY_ENVELOPE_KEYS
488
+ : requested.mode === 'order'
489
+ ? ORDER_ENVELOPE_KEYS
490
+ : isJevDecisionPreset(requested.mode)
491
+ ? JEV_PRESET_ENVELOPE_KEYS
492
+ : undefined
493
+ if (envelopeKeys !== undefined) {
494
+ const envelope = checkJevEnvelope(input, envelopeKeys)
495
+ if (!envelope.ok) {
496
+ const reasonCode: JevDecisionRunFailure =
497
+ requested.mode === undefined
498
+ ? 'QUESTIONS_INVALID'
499
+ : requested.mode === 'review'
500
+ ? 'REVIEW_INPUT_INVALID'
501
+ : requested.mode === 'rank'
502
+ ? 'RANK_INPUT_INVALID'
503
+ : requested.mode === 'verify'
504
+ ? 'VERIFY_INPUT_INVALID'
505
+ : requested.mode === 'order'
506
+ ? 'ORDER_INPUT_INVALID'
507
+ : 'PRESET_INVALID'
508
+ return refusal(reasonCode, envelope.detail)
509
+ }
510
+ }
511
+
426
512
  // Review mode (J4): the bounded request is built before any gate work, and
427
513
  // an invalid review input is a tool-surface refusal — same class as the
428
- // caller check, never a gate failure.
429
- let reviewRequest: Omit<NativeDecisionRequest, 'model'> | undefined
514
+ // caller check, never a gate failure. The v3.1 rank and verify modes follow
515
+ // the same prebuilt-request pattern (no gate work for a malformed input);
516
+ // neither has a telemetry point — they are tool modes, not shadow gates.
517
+ let prebuilt: Omit<NativeDecisionRequest, 'model'> | undefined
518
+ let candidateSource: JevDecisionPreparation['candidateSource'] | undefined
519
+ let orderCandidates: readonly string[] = []
430
520
  if (requested.mode === 'review') {
431
521
  const prepared = buildJevReviewRequest(input ?? {})
432
522
  if (!prepared.ok) {
@@ -441,7 +531,20 @@ export async function runJevDecision(
441
531
  )
442
532
  return refusal(prepared.reasonCode)
443
533
  }
444
- reviewRequest = prepared.request
534
+ prebuilt = prepared.request
535
+ } else if (requested.mode === 'rank') {
536
+ const prepared = buildJevRankRequest(input ?? {})
537
+ if (!prepared.ok) return refusal(prepared.reasonCode, prepared.detail)
538
+ prebuilt = prepared.request
539
+ } else if (requested.mode === 'verify') {
540
+ const prepared = buildJevVerifyRequest(input ?? {})
541
+ if (!prepared.ok) return refusal(prepared.reasonCode)
542
+ prebuilt = prepared.request
543
+ } else if (requested.mode === 'order') {
544
+ const prepared = buildJevOrderRequest(input ?? {})
545
+ if (!prepared.ok) return refusal(prepared.reasonCode, prepared.detail)
546
+ orderCandidates = prepared.candidates
547
+ prebuilt = prepared.request
445
548
  }
446
549
  const result = await runGatedNativeJevCall({
447
550
  sessionID: context?.sessionID,
@@ -449,24 +552,28 @@ export async function runJevDecision(
449
552
  agent: caller,
450
553
  runtime,
451
554
  prepare: async (route) =>
452
- reviewRequest !== undefined
555
+ prebuilt !== undefined
453
556
  ? {
454
557
  ok: true as const,
455
558
  request: {
456
559
  model: route.model,
457
- input: reviewRequest.input,
458
- questions: reviewRequest.questions,
560
+ input: prebuilt.input,
561
+ questions: prebuilt.questions,
459
562
  },
460
563
  }
461
564
  : requested.mode === undefined
462
565
  ? prepareJevDecisionRequest(route, input ?? {})
463
566
  : isJevDecisionPreset(requested.mode)
464
- ? prepareJevPresetRequest(
465
- route,
466
- requested.mode,
467
- input ?? {},
468
- requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
469
- )
567
+ ? (async () => {
568
+ const prepared = prepareJevPresetRequest(
569
+ route,
570
+ requested.mode,
571
+ input ?? {},
572
+ requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
573
+ )
574
+ if (prepared.ok) candidateSource = prepared.candidateSource
575
+ return prepared
576
+ })()
470
577
  : { ok: false as const, reasonCode: 'PRESET_INVALID' as const },
471
578
  })
472
579
  if (!result.ok) {
@@ -541,6 +648,80 @@ export async function runJevDecision(
541
648
  frozen: result.call.frozen,
542
649
  })
543
650
  }
651
+ if (requested.mode === 'rank') {
652
+ // v3.1 rank: the winner choice plus that candidate's fit score. The host
653
+ // API answers one scalar per question, so no runner-up or full ordering is
654
+ // returned — see jev-rank-verify.ts for the honest limitation.
655
+ const rank = consumeJevRankResult(result.call.response, result.call.request)
656
+ return JSON.stringify({
657
+ advisory: true,
658
+ effect: 'none',
659
+ reason: 'JEV_DECISION',
660
+ caller,
661
+ route: {
662
+ providerID: result.call.selection.route.model.providerID,
663
+ id: result.call.selection.route.model.id,
664
+ billing: result.call.selection.route.billing,
665
+ },
666
+ mode: 'rank',
667
+ winner: rank.winner,
668
+ winnerFit: rank.winnerFit,
669
+ answers: advice.answers,
670
+ missing: advice.missing,
671
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
672
+ frozen: result.call.frozen,
673
+ })
674
+ }
675
+ if (requested.mode === 'order') {
676
+ // v3.1 ordering: one fit question per candidate (2-4), sorted descending.
677
+ // Null score = the host answered nothing usable for that candidate —
678
+ // visible, placed last, never guessed.
679
+ const ordering = consumeJevOrderResult(
680
+ result.call.response,
681
+ result.call.request,
682
+ orderCandidates,
683
+ )
684
+ return JSON.stringify({
685
+ advisory: true,
686
+ effect: 'none',
687
+ reason: 'JEV_DECISION',
688
+ caller,
689
+ route: {
690
+ providerID: result.call.selection.route.model.providerID,
691
+ id: result.call.selection.route.model.id,
692
+ billing: result.call.selection.route.billing,
693
+ },
694
+ mode: 'order',
695
+ ordering,
696
+ answers: advice.answers,
697
+ missing: advice.missing,
698
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
699
+ frozen: result.call.frozen,
700
+ })
701
+ }
702
+ if (requested.mode === 'verify') {
703
+ // v3.1 verify: one PASS/FAIL/BLOCK verdict per claim, fail-closed. The
704
+ // tool never acts on the verdicts; a caller that requires a verdict
705
+ // treats a refusal (which never reaches this branch) as BLOCK.
706
+ const results = consumeJevVerifyResult(result.call.response, result.call.request)
707
+ return JSON.stringify({
708
+ advisory: true,
709
+ effect: 'none',
710
+ reason: 'JEV_DECISION',
711
+ caller,
712
+ route: {
713
+ providerID: result.call.selection.route.model.providerID,
714
+ id: result.call.selection.route.model.id,
715
+ billing: result.call.selection.route.billing,
716
+ },
717
+ mode: 'verify',
718
+ results,
719
+ answers: advice.answers,
720
+ missing: advice.missing,
721
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
722
+ frozen: result.call.frozen,
723
+ })
724
+ }
544
725
  return JSON.stringify({
545
726
  advisory: true,
546
727
  effect: 'none',
@@ -552,6 +733,7 @@ export async function runJevDecision(
552
733
  billing: result.call.selection.route.billing,
553
734
  },
554
735
  ...(requested.mode === undefined ? {} : { preset: requested.mode }),
736
+ ...(candidateSource === undefined ? {} : { candidateSource }),
555
737
  answers: advice.answers,
556
738
  missing: advice.missing,
557
739
  usage: { costUsd: advice.costUsd, tokens: advice.tokens },
@@ -567,7 +749,13 @@ const TOOL_DESCRIPTION =
567
749
  'host), `mode: "delegation"` to pick ' +
568
750
  'a specialist, `mode: "review"` to score a finished delegated result against named criteria ' +
569
751
  '(advisory quality score + needs-review flag; the result content itself is never sent — ' +
570
- 'shape metrics and criteria only), or pass explicit typed `questions` (choice, score, ' +
752
+ 'shape metrics and criteria only), `mode: "rank"` to pick the best of 2-20 named candidates ' +
753
+ '(winner + fit; no full ordering), `mode: "order"` to ORDER 2-4 candidates by fit (one ' +
754
+ 'score question per candidate; returns the descending ordering with per-candidate scores), ' +
755
+ '(returns the winner and its fit score; no full ordering), `mode: "verify"` to check 1-4 ' +
756
+ 'named claims, with optional `state` evidence the claims are judged against ' +
757
+ '(verdicts PASS, FAIL, or UNVERIFIABLE for the 0.35-0.65 band; any refusal, timeout or ' +
758
+ 'malformed answer is BLOCK, fail-closed), or pass explicit typed `questions` (choice, score, ' +
571
759
  'predicate). Invalid-input refusals carry a `detail` token naming the exact cause. Returns ' +
572
760
  'probabilistic answers with confidence. Requires decision-router egress ' +
573
761
  'consent and budget caps; asks host permission first. It never dispatches agents, runs ' +
@@ -622,13 +810,45 @@ const REVIEW_METRICS_SCHEMA = {
622
810
  },
623
811
  } as const
624
812
 
813
+ const RANK_CANDIDATE_SCHEMA = {
814
+ type: 'object',
815
+ additionalProperties: false,
816
+ required: ['id'],
817
+ properties: {
818
+ id: {
819
+ type: 'string',
820
+ minLength: 1,
821
+ maxLength: 64,
822
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
823
+ },
824
+ description: { type: 'string', minLength: 1, maxLength: 500 },
825
+ },
826
+ } as const
827
+
828
+ const VERIFY_CLAIM_SCHEMA = {
829
+ type: 'object',
830
+ additionalProperties: false,
831
+ required: ['name', 'claim'],
832
+ properties: {
833
+ name: {
834
+ type: 'string',
835
+ minLength: 1,
836
+ maxLength: 64,
837
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
838
+ },
839
+ claim: { type: 'string', minLength: 1, maxLength: 200 },
840
+ },
841
+ } as const
842
+
625
843
  /**
626
- * One schema, two disjoint payloads: the state branch (presets and explicit
627
- * questions carry the state text) and the review branch (J4 takes structural
844
+ * One schema, four disjoint payloads: the state branch (presets and explicit
845
+ * questions carry the state text), the review branch (J4 takes structural
628
846
  * shape metrics, a delegate id and named criteria — never a state text, never
629
847
  * result content; the criteria are the only free text, bounded at the DSH
630
- * caps: at most 4, each 1–120 chars). The preparers are the authority; the
631
- * schema is the model-facing contract.
848
+ * caps: at most 4, each 1–120 chars), the rank branch (v3.1: a state plus
849
+ * 2–8 named candidates) and the verify branch (v3.1: 1–4 named claims, no
850
+ * state). The preparers are the authority; the schema is the model-facing
851
+ * contract.
632
852
  */
633
853
  const JEV_INPUT_SCHEMA: Record<string, unknown> = {
634
854
  type: 'object',
@@ -637,11 +857,13 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
637
857
  anyOf: [
638
858
  { required: ['state'] },
639
859
  { required: ['delegateId', 'resultSummaryKind', 'resultMetrics', 'criteria'] },
860
+ { required: ['candidates'] },
861
+ { required: ['claims'] },
640
862
  ],
641
863
  properties: {
642
864
  schemaVersion: { type: 'integer', const: 1 },
643
865
  state: { type: 'string', minLength: 1, maxLength: 12_000 },
644
- mode: { type: 'string', enum: ['skills', 'delegation', 'review'] },
866
+ mode: { type: 'string', enum: ['skills', 'delegation', 'review', 'rank', 'verify', 'order'] },
645
867
  questions: { type: 'array', minItems: 1, maxItems: 4, items: questionSchema },
646
868
  delegateId: {
647
869
  type: 'string',
@@ -657,6 +879,18 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
657
879
  maxItems: 4,
658
880
  items: { type: 'string', minLength: 1, maxLength: 120 },
659
881
  },
882
+ candidates: {
883
+ type: 'array',
884
+ minItems: 2,
885
+ maxItems: 20,
886
+ items: RANK_CANDIDATE_SCHEMA,
887
+ },
888
+ claims: {
889
+ type: 'array',
890
+ minItems: 1,
891
+ maxItems: 4,
892
+ items: VERIFY_CLAIM_SCHEMA,
893
+ },
660
894
  },
661
895
  }
662
896
 
@@ -221,15 +221,62 @@ export type JevDecisionPreparationDetail =
221
221
  | 'SCORE_INVALID'
222
222
  | 'PREDICATE_HAS_CHOICES_OR_LEVELS'
223
223
  | 'QUESTION_TYPE_INVALID'
224
+ | 'SCHEMA_VERSION_INVALID'
225
+ | 'UNKNOWN_INPUT_KEYS'
226
+
227
+ export type JevSkillCandidateSource = 'prefilter' | 'full-catalog' | 'host-skills'
224
228
 
225
229
  export type JevDecisionPreparation =
226
- | { readonly ok: true; readonly request: NativeDecisionRequest }
230
+ | {
231
+ readonly ok: true
232
+ readonly request: NativeDecisionRequest
233
+ /** Skills mode only: which path produced the candidate pool. */
234
+ readonly candidateSource?: JevSkillCandidateSource
235
+ }
227
236
  | {
228
237
  readonly ok: false
229
238
  readonly reasonCode: JevDecisionPreparationFailure
230
239
  readonly detail?: JevDecisionPreparationDetail
231
240
  }
232
241
 
242
+ /**
243
+ * The ONE envelope check every tool path passes through before its builder:
244
+ * `schemaVersion` is required (and must be 1) and unknown keys are rejected —
245
+ * the declared contract, now enforced uniformly (beta.10 claimed it; beta.12
246
+ * applies it to presets, review, rank and verify too).
247
+ */
248
+ export type JevEnvelopeCheck = { ok: true } | { ok: false; detail: JevDecisionPreparationDetail }
249
+
250
+ export function checkJevEnvelope(
251
+ input: unknown,
252
+ allowedKeys: ReadonlySet<string>,
253
+ ): JevEnvelopeCheck {
254
+ if (
255
+ input === null ||
256
+ typeof input !== 'object' ||
257
+ Array.isArray(input) ||
258
+ (input as Record<string, unknown>).schemaVersion !== 1
259
+ ) {
260
+ return { ok: false, detail: 'SCHEMA_VERSION_INVALID' }
261
+ }
262
+ const unknown = Object.keys(input as Record<string, unknown>).filter(
263
+ (key) => !allowedKeys.has(key),
264
+ )
265
+ if (unknown.length > 0) return { ok: false, detail: 'UNKNOWN_INPUT_KEYS' }
266
+ return { ok: true }
267
+ }
268
+
269
+ export const JEV_EXPLICIT_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
270
+ 'schemaVersion',
271
+ 'state',
272
+ 'questions',
273
+ ])
274
+ export const JEV_PRESET_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
275
+ 'schemaVersion',
276
+ 'mode',
277
+ 'state',
278
+ ])
279
+
233
280
  function isBoundedNonBlankString(value: unknown, max: number): value is string {
234
281
  return typeof value === 'string' && value.trim().length > 0 && value.length <= max
235
282
  }
@@ -311,8 +358,23 @@ function readScoreQuestion(
311
358
  */
312
359
  export function prepareJevDecisionRequest(
313
360
  route: ResolvedNativeDecisionRoute,
314
- input: { readonly state?: unknown; readonly questions?: unknown },
361
+ input: {
362
+ readonly schemaVersion?: unknown
363
+ readonly state?: unknown
364
+ readonly questions?: unknown
365
+ },
315
366
  ): JevDecisionPreparation {
367
+ // Envelope enforcement (field report N2/N3): schemaVersion was documented
368
+ // as required but never checked, and unknown keys passed silently to the
369
+ // provider against the declared additionalProperties: false.
370
+ if (input.schemaVersion !== 1) {
371
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'SCHEMA_VERSION_INVALID' }
372
+ }
373
+ const knownKeys = new Set(['schemaVersion', 'state', 'questions'])
374
+ const unknown = Object.keys(input).filter((key) => !knownKeys.has(key))
375
+ if (unknown.length > 0) {
376
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'UNKNOWN_INPUT_KEYS' }
377
+ }
316
378
  const state = input.state
317
379
  if (!isBoundedNonBlankString(state, NATIVE_DECISION_MAX_PROMPT_LENGTH)) {
318
380
  return { ok: false, reasonCode: 'STATE_INVALID' }
@@ -403,12 +465,21 @@ export function isJevDecisionPreset(value: unknown): value is JevDecisionPreset
403
465
  }
404
466
 
405
467
  /** Every canonical specialist except the orchestrator itself. */
406
- const SPECIALIST_CHOICES: ReadonlyArray<{ value: string }> = Object.freeze(
468
+ const SPECIALIST_CHOICES: ReadonlyArray<{ value: string; description?: string }> = Object.freeze(
407
469
  PANTHEON_AGENT_CATALOG.filter((agent) => agent.id !== 'zeus').map((agent) => ({
408
470
  value: agent.id,
471
+ description: boundedCatalogDescription(agent.description),
409
472
  })),
410
473
  )
411
474
 
475
+ /** Catalog descriptions are short; truncate defensively at the documented bound. */
476
+ function boundedCatalogDescription(value: unknown): string | undefined {
477
+ if (typeof value !== 'string' || value.trim() === '') return undefined
478
+ return value.length > JEV_DECISION_MAX_DESCRIPTION_LENGTH
479
+ ? `${value.slice(0, JEV_DECISION_MAX_DESCRIPTION_LENGTH - 1)}…`
480
+ : value
481
+ }
482
+
412
483
  const SKILL_DESCRIPTIONS = new Map(
413
484
  PANTHEON_SKILL_CATALOG.map((entry) => [entry.id, entry.description]),
414
485
  )
@@ -504,15 +575,25 @@ export function prepareJevPresetRequest(
504
575
  instructions:
505
576
  'Choose one listed specialist only when the described task clearly needs it; ' +
506
577
  'otherwise choose none. This is advisory only; nothing is dispatched.',
507
- choices: [...SPECIALIST_CHOICES, { value: 'none' }],
578
+ choices: [
579
+ ...SPECIALIST_CHOICES,
580
+ { value: 'none', description: 'No specialist fits the described task.' },
581
+ ],
508
582
  },
509
583
  ],
510
584
  } satisfies NativeDecisionRequest
511
585
  return { ok: true, request: Object.freeze(request) }
512
586
  }
513
587
 
514
- const shortlist = selectPantheonSkills(state).skillIds
515
- const pool = shortlist.length > 0 ? shortlist : CATALOG_SKILL_IDS
588
+ // Field report beta.15 §skills: the lexical prefilter dropped the exact
589
+ // skill the state described (codemap → none 0.88 from a prefiltered pool).
590
+ // The local catalog is 12 entries and the choice bound is 24 — recall beats
591
+ // a filter that saves half of $0.00003. The full local catalog + host
592
+ // skills always ride; `candidateSource` keeps reporting which pool the
593
+ // caller got.
594
+ const hostHasSkills = Array.isArray(hostSkills) && hostSkills.length > 0
595
+ const candidateSource: JevSkillCandidateSource = hostHasSkills ? 'host-skills' : 'full-catalog'
596
+ const pool = CATALOG_SKILL_IDS
516
597
  const descriptions = new Map(PANTHEON_SKILL_CATALOG.map((entry) => [entry.id, entry.description]))
517
598
  const request = {
518
599
  model: route.model,
@@ -524,11 +605,14 @@ export function prepareJevPresetRequest(
524
605
  instructions:
525
606
  'Choose the skills worth stacking for the described task, or none when none apply. ' +
526
607
  'This is advisory only; nothing is loaded or executed by this decision.',
527
- choices: [...mergeHostSkills(pool, hostSkills, descriptions), { value: 'none' }],
608
+ choices: [
609
+ ...mergeHostSkills(pool, hostSkills, descriptions),
610
+ { value: 'none', description: 'No skill stack fits the described task.' },
611
+ ],
528
612
  },
529
613
  ],
530
614
  } satisfies NativeDecisionRequest
531
- return { ok: true, request: Object.freeze(request) }
615
+ return { ok: true, request: Object.freeze(request), candidateSource }
532
616
  }
533
617
  // ─── Response consumption ───────────────────────────────────────────────
534
618
 
@@ -152,7 +152,7 @@ export const J3_ESCALATION_CHEAP_MODEL = 'opencode/mimo-v2.6-flash'
152
152
  /** Bound for the composed state text (the template is ~320 chars). */
153
153
  export const J3_ESCALATION_STATE_MAX_LENGTH = 512
154
154
 
155
- const FLAG_ON = new Set(['1', 'on', 'true'])
155
+ const FLAG_ON = new Set(['1', 'on', 'true', 'shadow'])
156
156
  const TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
157
157
  const SHA256_HEX = /^[0-9a-f]{64}$/
158
158
  /** Largest state_chars printed into the template (8 digits). */
@@ -63,7 +63,12 @@ export const J4_QUALITY_SCORE_POINT = 'J4'
63
63
 
64
64
  /** Question names of the two prepared questions, matched on consumption. */
65
65
  export const QUALITY_QUESTION_NAME = 'quality'
66
- export const REVIEW_QUESTION_NAME = 'noul'
66
+ /**
67
+ * Field report (beta.13→16): the review question was literally named 'noul'
68
+ * — the decision model's internal archetype leaked into a user-visible
69
+ * payload. The name is ours to choose; `quality` says what it measures.
70
+ */
71
+ export const REVIEW_QUESTION_NAME = 'needs_review'
67
72
 
68
73
  /** DSH hard-cap mirror: at most 4 criteria per review request. */
69
74
  export const J4_MAX_CRITERIA = 4
@@ -356,7 +361,7 @@ export function encodeQualityScoreReason(input: {
356
361
  * ANY other key — `state`, `questions`, or a smuggled content field — refuses
357
362
  * the preparation, so no content slot exists even at the input boundary.
358
363
  */
359
- const REVIEW_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
364
+ export const REVIEW_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
360
365
  'schemaVersion',
361
366
  'mode',
362
367
  'delegateId',