pantheon-opencode 1.6.3-beta.6 → 1.7.0-beta.1

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