pantheon-opencode 1.6.2 → 1.6.3-beta.10

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 (38) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +69 -0
  4. package/README.md +14 -2
  5. package/bin/pantheon-init.mjs +1 -1
  6. package/package.json +1 -1
  7. package/plugin.json +1 -1
  8. package/pyproject.toml +1 -1
  9. package/scripts/decision-router-budget.mjs +4 -2
  10. package/scripts/decision-router-v2-egress.mjs +9 -2
  11. package/scripts/decision-router.mjs +58 -10
  12. package/scripts/install/decision-router-config.mjs +94 -8
  13. package/scripts/install/interactive.mjs +78 -10
  14. package/scripts/install/opencode.mjs +20 -0
  15. package/scripts/install/plugin.mjs +17 -0
  16. package/scripts/jev-live-probe.mjs +184 -0
  17. package/scripts/secret-scan.mjs +1 -1
  18. package/scripts/sync-tui.mjs +11 -0
  19. package/src/agents/zeus.md +24 -0
  20. package/src/pantheon/j-telemetry-file.ts +96 -0
  21. package/src/pantheon/jev-decision-tool.ts +240 -27
  22. package/src/pantheon/jev-decisions.ts +78 -14
  23. package/src/pantheon/jev-rank-verify.ts +435 -0
  24. package/src/pantheon/local-decision-budget.ts +11 -3
  25. package/src/pantheon/local-decision-provider-matrix.ts +3 -1
  26. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  27. package/src/plugin-v2.ts +12 -2
  28. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  29. package/src/plugins/tui/dist/tui-v2.js +457 -4
  30. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  31. package/src/plugins/tui/dist/tui.js +1 -1
  32. package/src/plugins/tui/package-lock.json +2 -2
  33. package/src/plugins/tui/package.json +1 -1
  34. package/src/plugins/tui/src/index-v2.tsx +6 -0
  35. package/src/plugins/tui/src/whats-new-highlights.ts +263 -0
  36. package/src/plugins/tui/src/whats-new-open.ts +80 -0
  37. package/src/plugins/tui/src/whats-new-state.ts +128 -0
  38. package/src/plugins/tui/src/whats-new.tsx +119 -0
@@ -42,6 +42,12 @@ import {
42
42
  type QualityScoreEvaluation,
43
43
  qualityVerdict,
44
44
  } from './jev-quality-score.ts'
45
+ import {
46
+ buildJevRankRequest,
47
+ buildJevVerifyRequest,
48
+ consumeJevRankResult,
49
+ consumeJevVerifyResult,
50
+ } from './jev-rank-verify.ts'
45
51
  import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
46
52
  import {
47
53
  openLocalDecisionBudgetLedger,
@@ -67,6 +73,13 @@ export interface V2JevDecisionRuntime {
67
73
  readonly listModels: () => Promise<unknown>
68
74
  /** The host's native Decisions API (`ctx.experimental.generate.decisions`). */
69
75
  readonly decide: (request: NativeDecisionRequest) => Promise<unknown>
76
+ /**
77
+ * Allowlisted specialist callers for explicit-questions mode (parsed from
78
+ * `PANTHEON_JEV_SPECIALIST_CALLERS` by the plugin wiring). Empty/absent =
79
+ * Zeus only. Preset and v3.1 modes (skills, delegation, review, rank,
80
+ * verify) stay Zeus-only regardless.
81
+ */
82
+ readonly specialistCallers?: readonly string[]
70
83
  /**
71
84
  * Raw host skill registry (`ctx.skill.list()`); optional. Its entries extend
72
85
  * the skills preset so installed Agent Skills become decidable.
@@ -88,10 +101,35 @@ export function nativeJevPermissionResource(providerID: string, id: string): str
88
101
  return `pantheon-native-decisions://${providerID}/${id}`
89
102
  }
90
103
 
104
+ export const SPECIALIST_CALLERS_FLAG_ENV = 'PANTHEON_JEV_SPECIALIST_CALLERS'
105
+
106
+ /**
107
+ * Parse the caller allowlist from the flag's CSV value. Unset/empty = Zeus
108
+ * only (the default). Preset and v3.1 modes (skills, delegation, review,
109
+ * rank, verify) stay Zeus-only regardless of the flag: owner/skill selection,
110
+ * result scoring, candidate ranking and claim verification are orchestration
111
+ * decisions; specialists may ask bounded typed questions mid-task, nothing
112
+ * else. Lives in the plugin wiring (which owns flag reads); this module
113
+ * receives the parsed list via the runtime.
114
+ */
115
+ export function specialistCallerAllowlist(flagValue: string | undefined): readonly string[] {
116
+ const raw = String(flagValue ?? '').trim()
117
+ if (!raw) return []
118
+ const parsed = raw
119
+ .split(',')
120
+ .map((name) => name.trim())
121
+ .filter((name) => /^[a-z][a-z0-9-]{0,31}$/.test(name))
122
+ return [...new Set(parsed)]
123
+ }
124
+
91
125
  export type JevDecisionRunFailure =
92
- | 'CALLER_NOT_ZEUS'
126
+ | 'CALLER_NOT_ALLOWED'
93
127
  | 'REVIEW_INPUT_INVALID'
94
128
  | 'CRITERIA_INVALID'
129
+ | 'RANK_INPUT_INVALID'
130
+ | 'CANDIDATE_INVALID'
131
+ | 'VERIFY_INPUT_INVALID'
132
+ | 'CLAIM_INVALID'
95
133
  | 'CONTEXT_UNAVAILABLE'
96
134
  | 'CONFIG_UNAVAILABLE'
97
135
  | 'DISABLED'
@@ -133,21 +171,36 @@ function reviewRefusalSkipReason(reasonCode: JevDecisionRunFailure): string {
133
171
  /**
134
172
  * Every gate-chain failure the shared runner can produce. It is
135
173
  * {@link JevDecisionRunFailure} minus the tool-surface properties:
136
- * `CALLER_NOT_ZEUS` (the caller check) and the review mode's input
137
- * validation (`REVIEW_INPUT_INVALID` / `CRITERIA_INVALID`) — all three are
138
- * properties of the explicit tool surface, whose input the caller supplies
139
- * directly, not of the gate chain; the J1/J3 shadow observers run the same
140
- * chain for any agent and can never produce them.
174
+ * `CALLER_NOT_ALLOWED` (the caller check) and the input validation of the
175
+ * prebuilt-request modes — the review mode (`REVIEW_INPUT_INVALID` /
176
+ * `CRITERIA_INVALID`) and the v3.1 rank and verify modes
177
+ * (`RANK_INPUT_INVALID` / `CANDIDATE_INVALID` / `VERIFY_INPUT_INVALID` /
178
+ * `CLAIM_INVALID`). All of these are properties of the explicit tool surface,
179
+ * whose input the caller supplies directly, not of the gate chain; the
180
+ * J1/J3 shadow observers run the same chain for any agent and can never
181
+ * produce them.
141
182
  */
142
183
  export type GatedNativeJevFailure = Exclude<
143
184
  JevDecisionRunFailure,
144
- 'CALLER_NOT_ZEUS' | 'REVIEW_INPUT_INVALID' | 'CRITERIA_INVALID'
185
+ | 'CALLER_NOT_ALLOWED'
186
+ | 'REVIEW_INPUT_INVALID'
187
+ | 'CRITERIA_INVALID'
188
+ | 'RANK_INPUT_INVALID'
189
+ | 'CANDIDATE_INVALID'
190
+ | 'VERIFY_INPUT_INVALID'
191
+ | 'CLAIM_INVALID'
145
192
  >
146
193
 
147
194
  /** The minimal runtime slice the gate chain needs. */
148
195
  export type GatedNativeJevRuntime = Pick<V2JevDecisionRuntime, 'decide'> & {
149
196
  /** Host permission kill-switch (`ctx.permission.assert`), when present. */
150
197
  readonly permissionAssert?: (input: Record<string, unknown>) => Promise<unknown>
198
+ /**
199
+ * Allowlisted specialist callers for explicit-questions mode (parsed from
200
+ * `PANTHEON_JEV_SPECIALIST_CALLERS` by the plugin wiring). Empty/absent =
201
+ * Zeus only. Preset modes stay Zeus-only regardless.
202
+ */
203
+ readonly specialistCallers?: readonly string[]
151
204
  }
152
205
 
153
206
  /** One completed, settled native Jev call: gates passed, usage reconciled. */
@@ -169,6 +222,12 @@ export type GatedNativeJevCallResult =
169
222
  readonly reasonCode: GatedNativeJevFailure
170
223
  /** Sanitized error CLASS only (`TypeError`, …); set for call failures. */
171
224
  readonly detail?: string
225
+ /** Host's provider-layer reason class (`rate_limit`, …); no message text. */
226
+ readonly providerReason?: string
227
+ /** Integer HTTP status from the provider layer, when the host sets one. */
228
+ readonly status?: number
229
+ /** Positive retry window in ms, when the host sets one (rate limits). */
230
+ readonly retryAfterMs?: number
172
231
  }
173
232
 
174
233
  /**
@@ -256,11 +315,37 @@ export async function runGatedNativeJevCall(params: {
256
315
  try {
257
316
  response = await params.runtime.decide(prepared.request)
258
317
  } catch (err) {
259
- return {
318
+ // Provider-layer errors carry bounded, non-content facts that change
319
+ // what the user does next: the host's reason class (`rate_limit` vs
320
+ // auth vs unknown) and, for rate limits, the retry window. The error
321
+ // message text NEVER crosses (it carries URLs and subscription prose).
322
+ const failure: {
323
+ ok: false
324
+ reasonCode: 'DECISION_CALL_FAILED'
325
+ detail: string
326
+ providerReason?: string
327
+ status?: number
328
+ retryAfterMs?: number
329
+ } = {
260
330
  ok: false,
261
331
  reasonCode: 'DECISION_CALL_FAILED',
262
332
  detail: err instanceof Error ? err.name : 'UnknownFailure',
263
333
  }
334
+ const errRecord = err as { reason?: unknown; status?: unknown; retryAfterMs?: unknown }
335
+ if (typeof errRecord.reason === 'string' && /^[a-z_]{1,32}$/i.test(errRecord.reason)) {
336
+ failure.providerReason = errRecord.reason
337
+ }
338
+ if (typeof errRecord.status === 'number' && Number.isInteger(errRecord.status)) {
339
+ failure.status = errRecord.status
340
+ }
341
+ if (
342
+ typeof errRecord.retryAfterMs === 'number' &&
343
+ Number.isFinite(errRecord.retryAfterMs) &&
344
+ errRecord.retryAfterMs > 0
345
+ ) {
346
+ failure.retryAfterMs = Math.round(errRecord.retryAfterMs)
347
+ }
348
+ return failure
264
349
  }
265
350
 
266
351
  const evidence = verifyNativeUsageForReservation(
@@ -344,13 +429,27 @@ export async function runJevDecision(
344
429
  toolContext !== null && typeof toolContext === 'object' && !Array.isArray(toolContext)
345
430
  ? (toolContext as JevToolContext)
346
431
  : undefined
347
- if (context?.agent !== 'zeus') return refusal('CALLER_NOT_ZEUS')
432
+ const caller = context?.agent
433
+ if (typeof caller !== 'string' || caller.length === 0) return refusal('CALLER_NOT_ALLOWED')
434
+ const allowlist = runtime.specialistCallers ?? []
435
+ if (caller !== 'zeus' && !allowlist.includes(caller)) {
436
+ return refusal('CALLER_NOT_ALLOWED')
437
+ }
348
438
 
349
439
  const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
440
+ // Preset modes stay orchestrator-owned even when the flag widens the
441
+ // caller matrix: owner/skill selection and result scoring are
442
+ // orchestration decisions; allowlisted specialists may ask bounded typed
443
+ // questions only.
444
+ if (caller !== 'zeus' && requested.mode !== undefined) {
445
+ return refusal('CALLER_NOT_ALLOWED')
446
+ }
350
447
  // Review mode (J4): the bounded request is built before any gate work, and
351
448
  // an invalid review input is a tool-surface refusal — same class as the
352
- // caller check, never a gate failure.
353
- let reviewRequest: Omit<NativeDecisionRequest, 'model'> | undefined
449
+ // caller check, never a gate failure. The v3.1 rank and verify modes follow
450
+ // the same prebuilt-request pattern (no gate work for a malformed input);
451
+ // neither has a telemetry point — they are tool modes, not shadow gates.
452
+ let prebuilt: Omit<NativeDecisionRequest, 'model'> | undefined
354
453
  if (requested.mode === 'review') {
355
454
  const prepared = buildJevReviewRequest(input ?? {})
356
455
  if (!prepared.ok) {
@@ -365,21 +464,29 @@ export async function runJevDecision(
365
464
  )
366
465
  return refusal(prepared.reasonCode)
367
466
  }
368
- reviewRequest = prepared.request
467
+ prebuilt = prepared.request
468
+ } else if (requested.mode === 'rank') {
469
+ const prepared = buildJevRankRequest(input ?? {})
470
+ if (!prepared.ok) return refusal(prepared.reasonCode)
471
+ prebuilt = prepared.request
472
+ } else if (requested.mode === 'verify') {
473
+ const prepared = buildJevVerifyRequest(input ?? {})
474
+ if (!prepared.ok) return refusal(prepared.reasonCode)
475
+ prebuilt = prepared.request
369
476
  }
370
477
  const result = await runGatedNativeJevCall({
371
478
  sessionID: context?.sessionID,
372
479
  messageID: context?.messageID,
373
- agent: 'zeus',
480
+ agent: caller,
374
481
  runtime,
375
482
  prepare: async (route) =>
376
- reviewRequest !== undefined
483
+ prebuilt !== undefined
377
484
  ? {
378
485
  ok: true as const,
379
486
  request: {
380
487
  model: route.model,
381
- input: reviewRequest.input,
382
- questions: reviewRequest.questions,
488
+ input: prebuilt.input,
489
+ questions: prebuilt.questions,
383
490
  },
384
491
  }
385
492
  : requested.mode === undefined
@@ -407,15 +514,21 @@ export async function runJevDecision(
407
514
  runtime.shadowSink,
408
515
  )
409
516
  }
410
- if (result.detail === undefined) return refusal(result.reasonCode)
411
- // Refusal with the error CLASS only (`TypeError`, `RangeError`, …): the
517
+ if (result.detail === undefined && result.providerReason === undefined) {
518
+ return refusal(result.reasonCode)
519
+ }
520
+ // Refusal with the error CLASS only (`TypeError`, `RangeError`, …) plus
521
+ // the bounded provider facts (`rate_limit`, status, retry window): the
412
522
  // message can carry paths, config or provider detail and never crosses
413
523
  // into the chat.
414
524
  return JSON.stringify({
415
525
  advisory: false,
416
526
  effect: 'none',
417
527
  reasonCode: result.reasonCode,
418
- detail: result.detail,
528
+ ...(result.detail === undefined ? {} : { detail: result.detail }),
529
+ ...(result.providerReason === undefined ? {} : { providerReason: result.providerReason }),
530
+ ...(result.status === undefined ? {} : { status: result.status }),
531
+ ...(result.retryAfterMs === undefined ? {} : { retryAfterMs: result.retryAfterMs }),
419
532
  })
420
533
  }
421
534
 
@@ -443,6 +556,7 @@ export async function runJevDecision(
443
556
  advisory: true,
444
557
  effect: 'none',
445
558
  reason: 'JEV_DECISION',
559
+ caller,
446
560
  route: {
447
561
  providerID: result.call.selection.route.model.providerID,
448
562
  id: result.call.selection.route.model.id,
@@ -458,10 +572,58 @@ export async function runJevDecision(
458
572
  frozen: result.call.frozen,
459
573
  })
460
574
  }
575
+ if (requested.mode === 'rank') {
576
+ // v3.1 rank: the winner choice plus that candidate's fit score. The host
577
+ // API answers one scalar per question, so no runner-up or full ordering is
578
+ // returned — see jev-rank-verify.ts for the honest limitation.
579
+ const rank = consumeJevRankResult(result.call.response, result.call.request)
580
+ return JSON.stringify({
581
+ advisory: true,
582
+ effect: 'none',
583
+ reason: 'JEV_DECISION',
584
+ caller,
585
+ route: {
586
+ providerID: result.call.selection.route.model.providerID,
587
+ id: result.call.selection.route.model.id,
588
+ billing: result.call.selection.route.billing,
589
+ },
590
+ mode: 'rank',
591
+ winner: rank.winner,
592
+ winnerFit: rank.winnerFit,
593
+ answers: advice.answers,
594
+ missing: advice.missing,
595
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
596
+ frozen: result.call.frozen,
597
+ })
598
+ }
599
+ if (requested.mode === 'verify') {
600
+ // v3.1 verify: one PASS/FAIL/BLOCK verdict per claim, fail-closed. The
601
+ // tool never acts on the verdicts; a caller that requires a verdict
602
+ // treats a refusal (which never reaches this branch) as BLOCK.
603
+ const results = consumeJevVerifyResult(result.call.response, result.call.request)
604
+ return JSON.stringify({
605
+ advisory: true,
606
+ effect: 'none',
607
+ reason: 'JEV_DECISION',
608
+ caller,
609
+ route: {
610
+ providerID: result.call.selection.route.model.providerID,
611
+ id: result.call.selection.route.model.id,
612
+ billing: result.call.selection.route.billing,
613
+ },
614
+ mode: 'verify',
615
+ results,
616
+ answers: advice.answers,
617
+ missing: advice.missing,
618
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
619
+ frozen: result.call.frozen,
620
+ })
621
+ }
461
622
  return JSON.stringify({
462
623
  advisory: true,
463
624
  effect: 'none',
464
625
  reason: 'JEV_DECISION',
626
+ caller,
465
627
  route: {
466
628
  providerID: result.call.selection.route.model.providerID,
467
629
  id: result.call.selection.route.model.id,
@@ -477,13 +639,18 @@ export async function runJevDecision(
477
639
 
478
640
  const TOOL_DESCRIPTION =
479
641
  'Zeus-only advisory typed decisions via the host native Jev route (OpenCode Console or a ' +
480
- 'configured decision model). Ways to ask: pass `mode: "skills"` to stack skills for the ' +
642
+ 'configured decision model). Required: schemaVersion: 1 and a non-empty state (<=12000 chars). ' +
643
+ 'Ways to ask: pass `mode: "skills"` to stack skills for the ' +
481
644
  'state text (local prefilter shortlist, catalog fallback, plus every skill installed in the ' +
482
645
  'host), `mode: "delegation"` to pick ' +
483
646
  'a specialist, `mode: "review"` to score a finished delegated result against named criteria ' +
484
647
  '(advisory quality score + needs-review flag; the result content itself is never sent — ' +
485
- 'shape metrics and criteria only), or pass explicit typed `questions` (choice, score, ' +
486
- 'predicate). Returns probabilistic answers with confidence. Requires decision-router egress ' +
648
+ 'shape metrics and criteria only), `mode: "rank"` to pick the best of 2-8 named candidates ' +
649
+ '(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, ' +
652
+ 'predicate). Invalid-input refusals carry a `detail` token naming the exact cause. Returns ' +
653
+ 'probabilistic answers with confidence. Requires decision-router egress ' +
487
654
  'consent and budget caps; asks host permission first. It never dispatches agents, runs ' +
488
655
  'skills, executes tools, blocks, retries, or alters permissions — results are advisory only.'
489
656
 
@@ -536,13 +703,45 @@ const REVIEW_METRICS_SCHEMA = {
536
703
  },
537
704
  } as const
538
705
 
706
+ const RANK_CANDIDATE_SCHEMA = {
707
+ type: 'object',
708
+ additionalProperties: false,
709
+ required: ['id'],
710
+ properties: {
711
+ id: {
712
+ type: 'string',
713
+ minLength: 1,
714
+ maxLength: 64,
715
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
716
+ },
717
+ description: { type: 'string', minLength: 1, maxLength: 500 },
718
+ },
719
+ } as const
720
+
721
+ const VERIFY_CLAIM_SCHEMA = {
722
+ type: 'object',
723
+ additionalProperties: false,
724
+ required: ['name', 'claim'],
725
+ properties: {
726
+ name: {
727
+ type: 'string',
728
+ minLength: 1,
729
+ maxLength: 64,
730
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
731
+ },
732
+ claim: { type: 'string', minLength: 1, maxLength: 200 },
733
+ },
734
+ } as const
735
+
539
736
  /**
540
- * One schema, two disjoint payloads: the state branch (presets and explicit
541
- * questions carry the state text) and the review branch (J4 takes structural
737
+ * One schema, four disjoint payloads: the state branch (presets and explicit
738
+ * questions carry the state text), the review branch (J4 takes structural
542
739
  * shape metrics, a delegate id and named criteria — never a state text, never
543
740
  * result content; the criteria are the only free text, bounded at the DSH
544
- * caps: at most 4, each 1–120 chars). The preparers are the authority; the
545
- * schema is the model-facing contract.
741
+ * caps: at most 4, each 1–120 chars), the rank branch (v3.1: a state plus
742
+ * 2–8 named candidates) and the verify branch (v3.1: 1–4 named claims, no
743
+ * state). The preparers are the authority; the schema is the model-facing
744
+ * contract.
546
745
  */
547
746
  const JEV_INPUT_SCHEMA: Record<string, unknown> = {
548
747
  type: 'object',
@@ -551,11 +750,13 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
551
750
  anyOf: [
552
751
  { required: ['state'] },
553
752
  { required: ['delegateId', 'resultSummaryKind', 'resultMetrics', 'criteria'] },
753
+ { required: ['candidates'] },
754
+ { required: ['claims'] },
554
755
  ],
555
756
  properties: {
556
757
  schemaVersion: { type: 'integer', const: 1 },
557
758
  state: { type: 'string', minLength: 1, maxLength: 12_000 },
558
- mode: { type: 'string', enum: ['skills', 'delegation', 'review'] },
759
+ mode: { type: 'string', enum: ['skills', 'delegation', 'review', 'rank', 'verify'] },
559
760
  questions: { type: 'array', minItems: 1, maxItems: 4, items: questionSchema },
560
761
  delegateId: {
561
762
  type: 'string',
@@ -571,6 +772,18 @@ const JEV_INPUT_SCHEMA: Record<string, unknown> = {
571
772
  maxItems: 4,
572
773
  items: { type: 'string', minLength: 1, maxLength: 120 },
573
774
  },
775
+ candidates: {
776
+ type: 'array',
777
+ minItems: 2,
778
+ maxItems: 8,
779
+ items: RANK_CANDIDATE_SCHEMA,
780
+ },
781
+ claims: {
782
+ type: 'array',
783
+ minItems: 1,
784
+ maxItems: 4,
785
+ items: VERIFY_CLAIM_SCHEMA,
786
+ },
574
787
  },
575
788
  }
576
789
 
@@ -34,7 +34,11 @@ import {
34
34
  /** Config-level providers that have a native host Decisions route. */
35
35
  export type NativeJevProviderId = Extract<
36
36
  DecisionProviderId,
37
- 'typesafe-jev' | 'opencode-console-jev' | 'opencode-console-jev-free'
37
+ | 'typesafe-jev'
38
+ | 'opencode-console-jev'
39
+ | 'openrouter-jev'
40
+ | 'vercel-gateway-jev'
41
+ | 'cloudflare-workers-jev'
38
42
  >
39
43
 
40
44
  /**
@@ -46,7 +50,16 @@ export type NativeJevProviderId = Extract<
46
50
  export const NATIVE_JEV_HOST_PROVIDERS = Object.freeze({
47
51
  'typesafe-jev': 'typesafe-ai',
48
52
  'opencode-console-jev': 'opencode',
49
- 'opencode-console-jev-free': 'opencode',
53
+ // Host-embedded decision modules confirmed in the 2.2.5 binary
54
+ // (providers/<id>/decisions, System One transport — the host normalizes
55
+ // the request/response, so consumers only need the providerID mapping):
56
+ // openrouter (models.dev provider; credential OPENROUTER_API_KEY),
57
+ // vercel-ai-gateway (models.dev provider; AI_GATEWAY_API_KEY),
58
+ // cloudflare-workers-ai (custom entry with accountId; CLOUDFLARE_API_TOKEN),
59
+ // baseten and digitalocean (modules present, decision models undocumented).
60
+ 'openrouter-jev': 'openrouter',
61
+ 'vercel-gateway-jev': 'vercel-ai-gateway',
62
+ 'cloudflare-workers-jev': 'cloudflare-workers-ai',
50
63
  } satisfies Record<NativeJevProviderId, string>)
51
64
 
52
65
  export function isNativeJevProvider(provider: unknown): provider is NativeJevProviderId {
@@ -191,9 +204,33 @@ export type JevDecisionQuestionInput = {
191
204
 
192
205
  export type JevDecisionPreparationFailure = 'STATE_INVALID' | 'QUESTIONS_INVALID' | 'PRESET_INVALID'
193
206
 
207
+ /**
208
+ * Per-cause tokens for the validation bucket. An LLM caller cannot converge
209
+ * on a bare `QUESTIONS_INVALID` (field evidence: nine distinct causes, five
210
+ * blind retries); the tool attaches the specific token as `detail` so the
211
+ * next attempt can be exact.
212
+ */
213
+ export type JevDecisionPreparationDetail =
214
+ | 'QUESTIONS_NOT_A_LIST'
215
+ | 'QUESTION_COUNT_INVALID'
216
+ | 'QUESTION_NOT_AN_OBJECT'
217
+ | 'QUESTION_NAME_INVALID'
218
+ | 'QUESTION_NAME_BAD_PATTERN_OR_DUPLICATE'
219
+ | 'QUESTION_INSTRUCTIONS_INVALID'
220
+ | 'CHOICE_INVALID'
221
+ | 'SCORE_INVALID'
222
+ | 'PREDICATE_HAS_CHOICES_OR_LEVELS'
223
+ | 'QUESTION_TYPE_INVALID'
224
+ | 'SCHEMA_VERSION_INVALID'
225
+ | 'UNKNOWN_INPUT_KEYS'
226
+
194
227
  export type JevDecisionPreparation =
195
228
  | { readonly ok: true; readonly request: NativeDecisionRequest }
196
- | { readonly ok: false; readonly reasonCode: JevDecisionPreparationFailure }
229
+ | {
230
+ readonly ok: false
231
+ readonly reasonCode: JevDecisionPreparationFailure
232
+ readonly detail?: JevDecisionPreparationDetail
233
+ }
197
234
 
198
235
  function isBoundedNonBlankString(value: unknown, max: number): value is string {
199
236
  return typeof value === 'string' && value.trim().length > 0 && value.length <= max
@@ -276,47 +313,74 @@ function readScoreQuestion(
276
313
  */
277
314
  export function prepareJevDecisionRequest(
278
315
  route: ResolvedNativeDecisionRoute,
279
- input: { readonly state?: unknown; readonly questions?: unknown },
316
+ input: {
317
+ readonly schemaVersion?: unknown
318
+ readonly state?: unknown
319
+ readonly questions?: unknown
320
+ },
280
321
  ): JevDecisionPreparation {
322
+ // Envelope enforcement (field report N2/N3): schemaVersion was documented
323
+ // as required but never checked, and unknown keys passed silently to the
324
+ // provider against the declared additionalProperties: false.
325
+ if (input.schemaVersion !== 1) {
326
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'SCHEMA_VERSION_INVALID' }
327
+ }
328
+ const knownKeys = new Set(['schemaVersion', 'state', 'questions'])
329
+ const unknown = Object.keys(input).filter((key) => !knownKeys.has(key))
330
+ if (unknown.length > 0) {
331
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'UNKNOWN_INPUT_KEYS' }
332
+ }
281
333
  const state = input.state
282
334
  if (!isBoundedNonBlankString(state, NATIVE_DECISION_MAX_PROMPT_LENGTH)) {
283
335
  return { ok: false, reasonCode: 'STATE_INVALID' }
284
336
  }
285
337
  const rawQuestions = input.questions
286
- if (!Array.isArray(rawQuestions)) return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
338
+ if (!Array.isArray(rawQuestions)) {
339
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTIONS_NOT_A_LIST' }
340
+ }
287
341
  if (rawQuestions.length < 1 || rawQuestions.length > JEV_DECISION_MAX_QUESTIONS) {
288
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
342
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTION_COUNT_INVALID' }
289
343
  }
290
344
 
291
345
  const names = new Set<string>()
292
346
  const questions: NativeDecisionRequest['questions'][number][] = []
293
347
  for (const raw of rawQuestions) {
294
348
  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
295
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
349
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTION_NOT_AN_OBJECT' }
296
350
  }
297
351
  const question = raw as JevDecisionQuestionInput
298
352
  if (!isBoundedNonBlankString(question.name, JEV_DECISION_MAX_NAME_LENGTH)) {
299
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
353
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTION_NAME_INVALID' }
300
354
  }
301
355
  if (!QUESTION_NAME_PATTERN.test(question.name) || names.has(question.name)) {
302
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
356
+ return {
357
+ ok: false,
358
+ reasonCode: 'QUESTIONS_INVALID',
359
+ detail: 'QUESTION_NAME_BAD_PATTERN_OR_DUPLICATE',
360
+ }
303
361
  }
304
362
  if (!isBoundedNonBlankString(question.instructions, JEV_DECISION_MAX_INSTRUCTIONS_LENGTH)) {
305
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
363
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTION_INSTRUCTIONS_INVALID' }
306
364
  }
307
365
  names.add(question.name)
308
366
 
309
367
  if (question.type === 'choice') {
310
368
  const built = readChoiceQuestion(question)
311
- if (built === null) return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
369
+ if (built === null)
370
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'CHOICE_INVALID' }
312
371
  questions.push(built)
313
372
  } else if (question.type === 'score') {
314
373
  const built = readScoreQuestion(question)
315
- if (built === null) return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
374
+ if (built === null)
375
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'SCORE_INVALID' }
316
376
  questions.push(built)
317
377
  } else if (question.type === 'predicate') {
318
378
  if (question.choices !== undefined || question.levels !== undefined) {
319
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
379
+ return {
380
+ ok: false,
381
+ reasonCode: 'QUESTIONS_INVALID',
382
+ detail: 'PREDICATE_HAS_CHOICES_OR_LEVELS',
383
+ }
320
384
  }
321
385
  questions.push({
322
386
  type: 'predicate',
@@ -324,7 +388,7 @@ export function prepareJevDecisionRequest(
324
388
  instructions: question.instructions,
325
389
  })
326
390
  } else {
327
- return { ok: false, reasonCode: 'QUESTIONS_INVALID' }
391
+ return { ok: false, reasonCode: 'QUESTIONS_INVALID', detail: 'QUESTION_TYPE_INVALID' }
328
392
  }
329
393
  }
330
394