pantheon-opencode 1.6.3-beta.9 → 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 +187 -6
  4. package/README.md +7 -1
  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 +114 -86
  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 +71 -20
  35. package/src/pantheon/j1-approvals.ts +123 -0
  36. package/src/pantheon/jev-decision-tool.ts +148 -17
  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 +244 -14
  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,12 +45,18 @@ 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'
45
50
  import {
51
+ buildJevOrderRequest,
46
52
  buildJevRankRequest,
47
53
  buildJevVerifyRequest,
54
+ consumeJevOrderResult,
48
55
  consumeJevRankResult,
49
56
  consumeJevVerifyResult,
57
+ ORDER_ENVELOPE_KEYS,
58
+ RANK_ENVELOPE_KEYS,
59
+ VERIFY_ENVELOPE_KEYS,
50
60
  } from './jev-rank-verify.ts'
51
61
  import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
52
62
  import {
@@ -128,6 +138,8 @@ export type JevDecisionRunFailure =
128
138
  | 'CRITERIA_INVALID'
129
139
  | 'RANK_INPUT_INVALID'
130
140
  | 'CANDIDATE_INVALID'
141
+ | 'ORDER_INPUT_INVALID'
142
+ | 'ORDER_CANDIDATE_INVALID'
131
143
  | 'VERIFY_INPUT_INVALID'
132
144
  | 'CLAIM_INVALID'
133
145
  | 'CONTEXT_UNAVAILABLE'
@@ -143,6 +155,7 @@ export type JevDecisionRunFailure =
143
155
  | 'PRESET_INVALID'
144
156
  | 'RESERVATION_DENIED'
145
157
  | 'DECISION_CALL_FAILED'
158
+ | 'USAGE_EVIDENCE_UNAVAILABLE'
146
159
  | 'USAGE_UNRECONCILED'
147
160
 
148
161
  interface JevToolContext {
@@ -151,8 +164,12 @@ interface JevToolContext {
151
164
  agent?: unknown
152
165
  }
153
166
 
154
- function refusal(reasonCode: JevDecisionRunFailure): string {
155
- 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
+ )
156
173
  }
157
174
 
158
175
  function isNonBlankString(value: unknown): value is string {
@@ -285,6 +302,14 @@ export async function runGatedNativeJevCall(params: {
285
302
  )
286
303
  if (!selection.ok) return { ok: false, reasonCode: selection.reasonCode }
287
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
+
288
313
  if (typeof params.runtime.permissionAssert !== 'function') {
289
314
  return { ok: false, reasonCode: 'PERMISSION_UNAVAILABLE' }
290
315
  }
@@ -430,10 +455,14 @@ export async function runJevDecision(
430
455
  ? (toolContext as JevToolContext)
431
456
  : undefined
432
457
  const caller = context?.agent
433
- 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')
434
460
  const allowlist = runtime.specialistCallers ?? []
435
461
  if (caller !== 'zeus' && !allowlist.includes(caller)) {
436
- 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
+ )
437
466
  }
438
467
 
439
468
  const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
@@ -444,12 +473,52 @@ export async function runJevDecision(
444
473
  if (caller !== 'zeus' && requested.mode !== undefined) {
445
474
  return refusal('CALLER_NOT_ALLOWED')
446
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
+
447
513
  // Review mode (J4): the bounded request is built before any gate work, and
448
514
  // an invalid review input is a tool-surface refusal — same class as the
449
515
  // caller check, never a gate failure. The v3.1 rank and verify modes follow
450
516
  // the same prebuilt-request pattern (no gate work for a malformed input);
451
517
  // neither has a telemetry point — they are tool modes, not shadow gates.
452
518
  let prebuilt: Omit<NativeDecisionRequest, 'model'> | undefined
519
+ let candidateSource: JevSkillCandidateSource | undefined
520
+ let orderCandidates: readonly string[] = []
521
+ let verifyEvidenceUsed: boolean | undefined
453
522
  if (requested.mode === 'review') {
454
523
  const prepared = buildJevReviewRequest(input ?? {})
455
524
  if (!prepared.ok) {
@@ -467,11 +536,19 @@ export async function runJevDecision(
467
536
  prebuilt = prepared.request
468
537
  } else if (requested.mode === 'rank') {
469
538
  const prepared = buildJevRankRequest(input ?? {})
470
- if (!prepared.ok) return refusal(prepared.reasonCode)
539
+ if (!prepared.ok) return refusal(prepared.reasonCode, prepared.detail)
471
540
  prebuilt = prepared.request
472
541
  } else if (requested.mode === 'verify') {
473
542
  const prepared = buildJevVerifyRequest(input ?? {})
474
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
475
552
  prebuilt = prepared.request
476
553
  }
477
554
  const result = await runGatedNativeJevCall({
@@ -492,12 +569,21 @@ export async function runJevDecision(
492
569
  : requested.mode === undefined
493
570
  ? prepareJevDecisionRequest(route, input ?? {})
494
571
  : isJevDecisionPreset(requested.mode)
495
- ? prepareJevPresetRequest(
496
- route,
497
- requested.mode,
498
- input ?? {},
499
- requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
500
- )
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
+ })()
501
587
  : { ok: false as const, reasonCode: 'PRESET_INVALID' as const },
502
588
  })
503
589
  if (!result.ok) {
@@ -596,6 +682,33 @@ export async function runJevDecision(
596
682
  frozen: result.call.frozen,
597
683
  })
598
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
+ }
599
712
  if (requested.mode === 'verify') {
600
713
  // v3.1 verify: one PASS/FAIL/BLOCK verdict per claim, fail-closed. The
601
714
  // tool never acts on the verdicts; a caller that requires a verdict
@@ -612,6 +725,7 @@ export async function runJevDecision(
612
725
  billing: result.call.selection.route.billing,
613
726
  },
614
727
  mode: 'verify',
728
+ ...(verifyEvidenceUsed === undefined ? {} : { evidenceUsed: verifyEvidenceUsed }),
615
729
  results,
616
730
  answers: advice.answers,
617
731
  missing: advice.missing,
@@ -630,6 +744,7 @@ export async function runJevDecision(
630
744
  billing: result.call.selection.route.billing,
631
745
  },
632
746
  ...(requested.mode === undefined ? {} : { preset: requested.mode }),
747
+ ...(candidateSource === undefined ? {} : { candidateSource }),
633
748
  answers: advice.answers,
634
749
  missing: advice.missing,
635
750
  usage: { costUsd: advice.costUsd, tokens: advice.tokens },
@@ -645,10 +760,14 @@ const TOOL_DESCRIPTION =
645
760
  'host), `mode: "delegation"` to pick ' +
646
761
  'a specialist, `mode: "review"` to score a finished delegated result against named criteria ' +
647
762
  '(advisory quality score + needs-review flag; the result content itself is never sent — ' +
648
- 'shape metrics and criteria only), `mode: "rank"` to pick the best of 2-8 named candidates ' +
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), ' +
649
767
  '(returns the winner and its fit score; no full ordering), `mode: "verify"` to check 1-4 ' +
650
- 'named claims (PASS/FAIL per claim; any refusal, timeout or malformed answer is BLOCK, ' +
651
- 'fail-closed), or pass explicit typed `questions` (choice, score, ' +
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, ' +
652
771
  'predicate). Invalid-input refusals carry a `detail` token naming the exact cause. Returns ' +
653
772
  'probabilistic answers with confidence. Requires decision-router egress ' +
654
773
  'consent and budget caps; asks host permission first. It never dispatches agents, runs ' +
@@ -756,7 +875,7 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
756
875
  properties: {
757
876
  schemaVersion: { type: 'integer', const: 1 },
758
877
  state: { type: 'string', minLength: 1, maxLength: 12_000 },
759
- mode: { type: 'string', enum: ['skills', 'delegation', 'review', 'rank', 'verify'] },
878
+ mode: { type: 'string', enum: ['skills', 'delegation', 'review', 'rank', 'verify', 'order'] },
760
879
  questions: { type: 'array', minItems: 1, maxItems: 4, items: questionSchema },
761
880
  delegateId: {
762
881
  type: 'string',
@@ -770,12 +889,24 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
770
889
  type: 'array',
771
890
  minItems: 1,
772
891
  maxItems: 4,
773
- 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
+ },
774
905
  },
775
906
  candidates: {
776
907
  type: 'array',
777
908
  minItems: 2,
778
- maxItems: 8,
909
+ maxItems: 20,
779
910
  items: RANK_CANDIDATE_SCHEMA,
780
911
  },
781
912
  claims: {
@@ -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). */
@@ -63,10 +63,33 @@ 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
75
+
76
+ /**
77
+ * Normalize one criterion: a plain string, or a `{ id?, description }` record
78
+ * (field report beta.24 #10 — the object form is the natural caller shape and
79
+ * was refused by a strings-only check; both are accepted, the DESCRIPTION is
80
+ * what rides the request, the id is caller bookkeeping).
81
+ */
82
+ export function normalizeJevCriterion(raw: unknown): string | null {
83
+ if (typeof raw === 'string') return raw
84
+ if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
85
+ const record = raw as { id?: unknown; description?: unknown }
86
+ if (record.id !== undefined && (typeof record.id !== 'string' || record.id.length > 64)) {
87
+ return null
88
+ }
89
+ if (typeof record.description === 'string') return record.description
90
+ }
91
+ return null
92
+ }
70
93
  /** A rubric needs at least one named criterion. */
71
94
  export const J4_MIN_CRITERIA = 1
72
95
  /** Each criterion is a bounded instruction string (1–120 chars). */
@@ -114,7 +137,12 @@ export type QualityScorePreparedRequest =
114
137
  /** The request body; the caller attaches the resolved route's `model`. */
115
138
  readonly request: Omit<NativeDecisionRequest, 'model'>
116
139
  }
117
- | { readonly ok: false; readonly reasonCode: QualityScoreRequestFailure }
140
+ | {
141
+ readonly ok: false
142
+ readonly reasonCode: QualityScoreRequestFailure
143
+ /** Per-cause token (e.g. CRITERIA_SHAPE) so the caller can fix the input. */
144
+ readonly detail?: string
145
+ }
118
146
 
119
147
  const QUALITY_LABELS = [
120
148
  'unusable',
@@ -220,16 +248,23 @@ export function buildQualityScoreRequest(
220
248
  if (criteria.length < J4_MIN_CRITERIA || criteria.length > J4_MAX_CRITERIA) {
221
249
  return { ok: false, reasonCode: 'CRITERIA_INVALID' }
222
250
  }
251
+ const normalized: string[] = []
223
252
  for (const criterion of criteria) {
253
+ const text = normalizeJevCriterion(criterion)
224
254
  if (
225
- typeof criterion !== 'string' ||
226
- criterion.length < 1 ||
227
- criterion.length > J4_CRITERIA_MAX_LENGTH ||
228
- criterion.trim().length === 0 ||
229
- isHostileCriterion(criterion)
255
+ text === null ||
256
+ text.length < 1 ||
257
+ text.length > J4_CRITERIA_MAX_LENGTH ||
258
+ text.trim().length === 0 ||
259
+ isHostileCriterion(text)
230
260
  ) {
231
- return { ok: false, reasonCode: 'CRITERIA_INVALID' }
261
+ return {
262
+ ok: false,
263
+ reasonCode: 'CRITERIA_INVALID',
264
+ detail: 'CRITERIA_SHAPE — cada critério é uma string (1-120) ou {id?, description}',
265
+ }
232
266
  }
267
+ normalized.push(text)
233
268
  }
234
269
 
235
270
  const state =
@@ -244,7 +279,7 @@ export function buildQualityScoreRequest(
244
279
  }
245
280
  const qualityInstructions =
246
281
  QUALITY_INSTRUCTIONS_PREFIX +
247
- ` Criteria: ${criteria.map((criterion, index) => `(${index + 1}) ${criterion}`).join('; ')}.`
282
+ ` Criteria: ${normalized.map((criterion, index) => `(${index + 1}) ${criterion}`).join('; ')}.`
248
283
  return {
249
284
  ok: true,
250
285
  request: Object.freeze({
@@ -356,7 +391,7 @@ export function encodeQualityScoreReason(input: {
356
391
  * ANY other key — `state`, `questions`, or a smuggled content field — refuses
357
392
  * the preparation, so no content slot exists even at the input boundary.
358
393
  */
359
- const REVIEW_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
394
+ export const REVIEW_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
360
395
  'schemaVersion',
361
396
  'mode',
362
397
  'delegateId',