pantheon-opencode 1.6.2-beta.9 → 1.6.3-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 (73) hide show
  1. package/CHANGELOG.md +113 -0
  2. package/README.md +34 -60
  3. package/README.pt-BR.md +10 -12
  4. package/bin/pantheon-init.mjs +23 -33
  5. package/package.json +3 -3
  6. package/plugin.json +1 -1
  7. package/pyproject.toml +1 -1
  8. package/scripts/decision-router-budget.mjs +4 -1
  9. package/scripts/decision-router-v2-egress.mjs +11 -2
  10. package/scripts/decision-router.mjs +64 -56
  11. package/scripts/install/decision-router-config.mjs +110 -1
  12. package/scripts/install/npx-cache-sweep.mjs +103 -0
  13. package/scripts/install/opencode.mjs +7 -7
  14. package/scripts/install/plugin.mjs +4 -3
  15. package/scripts/install/strings.mjs +4 -0
  16. package/scripts/release-gates.mjs +6 -82
  17. package/scripts/secret-scan.mjs +1 -1
  18. package/scripts/sync-tui.mjs +3 -3
  19. package/src/agents/zeus.md +4 -2
  20. package/src/pantheon/jev-decision-tool.ts +455 -117
  21. package/src/pantheon/jev-decisions.ts +72 -25
  22. package/src/pantheon/jev-escalation.ts +639 -0
  23. package/src/pantheon/jev-quality-score.ts +432 -0
  24. package/src/pantheon/jev-risk-gate.ts +479 -0
  25. package/src/pantheon/local-decision-budget.ts +11 -1
  26. package/src/pantheon/local-decision-prompt.ts +12 -18
  27. package/src/pantheon/local-decision-provider-matrix.ts +3 -0
  28. package/src/pantheon/v2-decision-telemetry.ts +14 -4
  29. package/src/pantheon/v2-native-decisions.ts +1 -1
  30. package/src/plugin-v2.ts +204 -24
  31. package/src/plugins/tui/dist/server-v2.d.ts +19 -11
  32. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  33. package/src/plugins/tui/dist/server-v2.js +19 -789
  34. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  35. package/src/plugins/tui/dist/tui-v2.d.ts +12 -331
  36. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  37. package/src/plugins/tui/dist/tui-v2.js +257 -5370
  38. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  39. package/src/plugins/tui/dist/tui.js +1 -1
  40. package/src/plugins/tui/package-lock.json +2 -2
  41. package/src/plugins/tui/package.json +1 -1
  42. package/src/plugins/tui/src/index-v2.tsx +213 -86
  43. package/src/plugins/tui/src/server-v2.ts +18 -982
  44. package/src/plugins/tui/tsconfig.typecheck.json +1 -6
  45. package/src/plugins/tui/tsdown.config.ts +1 -11
  46. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js +0 -749
  47. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js.map +0 -1
  48. package/src/plugins/tui/dist/quota-adapters.d.ts +0 -89
  49. package/src/plugins/tui/dist/quota-adapters.d.ts.map +0 -1
  50. package/src/plugins/tui/dist/quota-adapters.js +0 -1142
  51. package/src/plugins/tui/dist/quota-adapters.js.map +0 -1
  52. package/src/plugins/tui/dist/quota-cli.d.ts +0 -17
  53. package/src/plugins/tui/dist/quota-cli.d.ts.map +0 -1
  54. package/src/plugins/tui/dist/quota-cli.js +0 -184
  55. package/src/plugins/tui/dist/quota-cli.js.map +0 -1
  56. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js +0 -684
  57. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js.map +0 -1
  58. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js +0 -118
  59. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js.map +0 -1
  60. package/src/plugins/tui/dist/usage-history-worker.js +0 -25
  61. package/src/plugins/tui/dist/usage-history-worker.js.map +0 -1
  62. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +0 -100
  63. package/src/plugins/tui/src/go-key-diagnostic.ts +0 -125
  64. package/src/plugins/tui/src/quota-adapters.ts +0 -1598
  65. package/src/plugins/tui/src/quota-cli.ts +0 -237
  66. package/src/plugins/tui/src/quota-rpc.ts +0 -373
  67. package/src/plugins/tui/src/quota-v2-model.ts +0 -1032
  68. package/src/plugins/tui/src/quota-v2.tsx +0 -1238
  69. package/src/plugins/tui/src/usage-history-contract.ts +0 -217
  70. package/src/plugins/tui/src/usage-history-validation.ts +0 -104
  71. package/src/plugins/tui/src/usage-history-view.tsx +0 -236
  72. package/src/plugins/tui/src/usage-history-worker.ts +0 -25
  73. package/src/plugins/tui/src/usage-view-model.ts +0 -272
@@ -12,6 +12,11 @@
12
12
  * preparer. Transport is the host's own provider layer: this module never
13
13
  * touches fetch, endpoints, or credentials.
14
14
  *
15
+ * The gate chain lives in {@link runGatedNativeJevCall} so a second caller (the
16
+ * J1 risk-score shadow gate in `jev-risk-gate.ts`) reuses the exact same
17
+ * config → route → permission → reserve → decide → reconcile sequence instead
18
+ * of duplicating it; only the request preparer is caller-supplied.
19
+ *
15
20
  * Settlement follows the fetch runner's fail-closed contract: reserve before
16
21
  * the call, reconcile from the host-reported cost after it, and leave the
17
22
  * reservation pending (budget held for the period) when no evidence can be
@@ -21,15 +26,26 @@ import { readUserDecisionRouterConfig } from '../../scripts/install/decision-rou
21
26
  import {
22
27
  consumeJevDecisionResult,
23
28
  isJevDecisionPreset,
24
- type JevDecisionCatalogEntry,
29
+ type JevDecisionPreparation,
25
30
  type JevHostSkill,
26
31
  type NativeJevRouteFailure,
32
+ type NativeJevRouteSelection,
27
33
  prepareJevDecisionRequest,
28
34
  prepareJevPresetRequest,
29
35
  resolveNativeJevRoute,
30
36
  } from './jev-decisions.ts'
37
+ import {
38
+ buildJevReviewRequest,
39
+ encodeQualityScoreReason,
40
+ evaluateQualityScoreDecision,
41
+ J4_QUALITY_SCORE_POINT,
42
+ type QualityScoreEvaluation,
43
+ qualityVerdict,
44
+ } from './jev-quality-score.ts'
45
+ import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
31
46
  import {
32
47
  openLocalDecisionBudgetLedger,
48
+ type ReservationResult,
33
49
  resolveLocalDecisionBudgetDbPath,
34
50
  } from './local-decision-budget.ts'
35
51
  import {
@@ -37,14 +53,26 @@ import {
37
53
  buildDecisionEgressRequest,
38
54
  } from './local-decision-egress-gate.ts'
39
55
  import { verifyNativeUsageForReservation } from './local-decision-usage-evidence.internal.ts'
40
- import type { NativeDecisionRequest } from './v2-native-decisions.ts'
56
+ import { observeShadow, type ShadowSink } from './v2-decision-shadow.ts'
57
+ import type { NativeDecisionRequest, ResolvedNativeDecisionRoute } from './v2-native-decisions.ts'
41
58
  import type { V2ToolDef } from './v2-tools.ts'
42
59
 
43
60
  export interface V2JevDecisionRuntime {
44
- /** Raw host model catalog (`ctx.model.list`); may resolve to anything. */
61
+ /**
62
+ * Raw host model catalog (`ctx.model.list`); still wired, but the route no
63
+ * longer consults it — field evidence (2.2.5): decision models are not chat
64
+ * models and never appear in the catalog. Removed with the 2.0 runtime
65
+ * reshaping.
66
+ */
45
67
  readonly listModels: () => Promise<unknown>
46
68
  /** The host's native Decisions API (`ctx.experimental.generate.decisions`). */
47
69
  readonly decide: (request: NativeDecisionRequest) => Promise<unknown>
70
+ /**
71
+ * Allowlisted specialist callers for explicit-questions mode (parsed from
72
+ * `PANTHEON_JEV_SPECIALIST_CALLERS` by the plugin wiring). Empty/absent =
73
+ * Zeus only. Preset modes stay Zeus-only regardless.
74
+ */
75
+ readonly specialistCallers?: readonly string[]
48
76
  /**
49
77
  * Raw host skill registry (`ctx.skill.list()`); optional. Its entries extend
50
78
  * the skills preset so installed Agent Skills become decidable.
@@ -52,6 +80,13 @@ export interface V2JevDecisionRuntime {
52
80
  readonly listSkills?: () => Promise<unknown>
53
81
  /** Host permission kill-switch (`ctx.permission.assert`), when present. */
54
82
  readonly permissionAssert?: (input: Record<string, unknown>) => Promise<unknown>
83
+ /**
84
+ * Shadow-record sink for the J4 output-quality review telemetry
85
+ * (`jev-quality-score.ts`); optional. The plugin wires the in-memory,
86
+ * bounded telemetry collector here; absent sink → no J4 records, nothing
87
+ * else changes.
88
+ */
89
+ readonly shadowSink?: ShadowSink
55
90
  }
56
91
 
57
92
  /** Logical permission resource: no endpoint URL exists on the native route. */
@@ -59,13 +94,34 @@ export function nativeJevPermissionResource(providerID: string, id: string): str
59
94
  return `pantheon-native-decisions://${providerID}/${id}`
60
95
  }
61
96
 
97
+ export const SPECIALIST_CALLERS_FLAG_ENV = 'PANTHEON_JEV_SPECIALIST_CALLERS'
98
+
99
+ /**
100
+ * 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.
106
+ */
107
+ export function specialistCallerAllowlist(flagValue: string | undefined): readonly string[] {
108
+ const raw = String(flagValue ?? '').trim()
109
+ if (!raw) return []
110
+ const parsed = raw
111
+ .split(',')
112
+ .map((name) => name.trim())
113
+ .filter((name) => /^[a-z][a-z0-9-]{0,31}$/.test(name))
114
+ return [...new Set(parsed)]
115
+ }
116
+
62
117
  export type JevDecisionRunFailure =
63
- | 'CALLER_NOT_ZEUS'
118
+ | 'CALLER_NOT_ALLOWED'
119
+ | 'REVIEW_INPUT_INVALID'
120
+ | 'CRITERIA_INVALID'
64
121
  | 'CONTEXT_UNAVAILABLE'
65
122
  | 'CONFIG_UNAVAILABLE'
66
123
  | 'DISABLED'
67
124
  | 'CONSENT_MISSING'
68
- | 'CATALOG_UNAVAILABLE'
69
125
  | 'CAP_OR_PERIOD_DENIED'
70
126
  | NativeJevRouteFailure
71
127
  | 'PERMISSION_UNAVAILABLE'
@@ -91,103 +147,128 @@ function isNonBlankString(value: unknown): value is string {
91
147
  return typeof value === 'string' && value.trim().length > 0
92
148
  }
93
149
 
150
+ /** Map a review-mode refusal to its telemetry skip token. */
151
+ function reviewRefusalSkipReason(reasonCode: JevDecisionRunFailure): string {
152
+ if (reasonCode === 'REVIEW_INPUT_INVALID') return 'skip-review-input-invalid'
153
+ if (reasonCode === 'CRITERIA_INVALID') return 'skip-criteria-invalid'
154
+ return mapGateFailureToSkipReason(reasonCode)
155
+ }
156
+
157
+ // ─── Shared gate chain ───────────────────────────────────────────────────
158
+
94
159
  /**
95
- * Read the host's installed skills for the stacking preset. Anything that is
96
- * not a plain {id, description?} record is skipped; a missing or hostile
97
- * registry degrades to the catalog-only preset. Reading the registry applies
98
- * no trust: installation already was the user's manual, reviewed act.
160
+ * Every gate-chain failure the shared runner can produce. It is
161
+ * {@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.
99
167
  */
100
- async function readHostSkills(runtime: V2JevDecisionRuntime): Promise<JevHostSkill[] | undefined> {
101
- if (typeof runtime.listSkills !== 'function') return undefined
102
- let raw: unknown
103
- try {
104
- raw = await runtime.listSkills()
105
- } catch {
106
- return undefined
107
- }
108
- if (!Array.isArray(raw)) return undefined
109
- const skills: JevHostSkill[] = []
110
- for (const entry of raw) {
111
- if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
112
- const record = entry as { id?: unknown; description?: unknown }
113
- if (typeof record.id !== 'string' || record.id.length === 0) continue
114
- skills.push({
115
- id: record.id,
116
- ...(typeof record.description === 'string' && record.description.length > 0
117
- ? { description: record.description }
118
- : {}),
119
- })
120
- }
121
- return skills
168
+ export type GatedNativeJevFailure = Exclude<
169
+ JevDecisionRunFailure,
170
+ 'CALLER_NOT_ALLOWED' | 'REVIEW_INPUT_INVALID' | 'CRITERIA_INVALID'
171
+ >
172
+
173
+ /** The minimal runtime slice the gate chain needs. */
174
+ export type GatedNativeJevRuntime = Pick<V2JevDecisionRuntime, 'decide'> & {
175
+ /** Host permission kill-switch (`ctx.permission.assert`), when present. */
176
+ readonly permissionAssert?: (input: Record<string, unknown>) => Promise<unknown>
177
+ /**
178
+ * Allowlisted specialist callers for explicit-questions mode (parsed from
179
+ * `PANTHEON_JEV_SPECIALIST_CALLERS` by the plugin wiring). Empty/absent =
180
+ * Zeus only. Preset modes stay Zeus-only regardless.
181
+ */
182
+ readonly specialistCallers?: readonly string[]
122
183
  }
123
184
 
124
- async function readCatalog(runtime: V2JevDecisionRuntime): Promise<JevDecisionCatalogEntry[]> {
125
- const raw = await runtime.listModels()
126
- if (!Array.isArray(raw)) throw new TypeError('Model catalog is not a list')
127
- const entries: JevDecisionCatalogEntry[] = []
128
- for (const model of raw) {
129
- if (model === null || typeof model !== 'object' || Array.isArray(model)) continue
130
- const record = model as Record<string, unknown>
131
- if (!isNonBlankString(record.providerID) || !isNonBlankString(record.id)) continue
132
- if (typeof record.type !== 'string') continue
133
- entries.push({
134
- providerID: record.providerID,
135
- id: record.id,
136
- type: record.type,
137
- } as JevDecisionCatalogEntry)
138
- }
139
- return entries
185
+ /** One completed, settled native Jev call: gates passed, usage reconciled. */
186
+ export interface GatedNativeJevCall {
187
+ /** The route the config + ledger gates selected. */
188
+ readonly selection: NativeJevRouteSelection
189
+ /** The prepared, bounded request this call ran. */
190
+ readonly request: NativeDecisionRequest
191
+ /** The raw host response; consume it through `consumeJevDecisionResult`. */
192
+ readonly response: unknown
193
+ /** The frozen ledger reconciliation state. */
194
+ readonly frozen: boolean
140
195
  }
141
196
 
197
+ export type GatedNativeJevCallResult =
198
+ | { readonly ok: true; readonly call: GatedNativeJevCall }
199
+ | {
200
+ readonly ok: false
201
+ readonly reasonCode: GatedNativeJevFailure
202
+ /** Sanitized error CLASS only (`TypeError`, …); set for call failures. */
203
+ readonly detail?: string
204
+ /** Host's provider-layer reason class (`rate_limit`, …); no message text. */
205
+ readonly providerReason?: string
206
+ /** Integer HTTP status from the provider layer, when the host sets one. */
207
+ readonly status?: number
208
+ /** Positive retry window in ms, when the host sets one (rate limits). */
209
+ readonly retryAfterMs?: number
210
+ }
211
+
142
212
  /**
143
- * Run one explicit, gate-checked native Jev decision. Every failure path
144
- * returns a bounded refusal JSON; the only caller-visible success output is
145
- * the validated advice with `effect: 'none'`.
213
+ * Run ONE native Jev decision through the full gate chain — the exact chain
214
+ * `runJevDecision` has always run, extracted so a second caller (the J1
215
+ * risk-score shadow gate) reuses it instead of duplicating it:
216
+ * user-level config (`enabled`, `egress_consent`) → route via
217
+ * `resolveNativeJevRoute` with the ledger's admission check → host permission
218
+ * kill-switch on `decision.egress` → caller-supplied request preparation →
219
+ * reservation → the single host call → usage verification and reconciliation.
220
+ *
221
+ * The request preparer is injected because the two callers prepare differently
222
+ * (the tool from model input, J1 from a prebuilt bounded request); everything
223
+ * before and after it is shared. Settlement keeps the fetch runner's
224
+ * fail-closed contract: reserve before the call, reconcile from the
225
+ * host-reported cost after it, leave the reservation pending when no evidence
226
+ * can be minted.
227
+ *
228
+ * Rejects only when the budget ledger itself cannot be opened (the explicit
229
+ * tool surface propagates that as a tool error, unchanged); every gate failure
230
+ * is a structured `{ ok: false }` result, never a throw.
146
231
  */
147
- export async function runJevDecision(
148
- input: unknown,
149
- toolContext: unknown,
150
- runtime: V2JevDecisionRuntime,
151
- ): Promise<string> {
152
- const context =
153
- toolContext !== null && typeof toolContext === 'object' && !Array.isArray(toolContext)
154
- ? (toolContext as JevToolContext)
155
- : undefined
156
- if (context?.agent !== 'zeus') return refusal('CALLER_NOT_ZEUS')
157
- const sessionID = context?.sessionID
158
- const messageID = context?.messageID
159
- if (!isNonBlankString(sessionID) || !isNonBlankString(messageID)) {
160
- return refusal('CONTEXT_UNAVAILABLE')
232
+ export async function runGatedNativeJevCall(params: {
233
+ readonly sessionID: unknown
234
+ readonly messageID: unknown
235
+ /** Current agent, only when the caller actually knows it. */
236
+ readonly agent?: unknown
237
+ readonly runtime: GatedNativeJevRuntime
238
+ readonly prepare: (
239
+ route: ResolvedNativeDecisionRoute,
240
+ ) => JevDecisionPreparation | Promise<JevDecisionPreparation>
241
+ }): Promise<GatedNativeJevCallResult> {
242
+ if (!isNonBlankString(params.sessionID) || !isNonBlankString(params.messageID)) {
243
+ return { ok: false, reasonCode: 'CONTEXT_UNAVAILABLE' }
161
244
  }
245
+ const sessionID = params.sessionID
246
+ const messageID = params.messageID
247
+ const agent =
248
+ typeof params.agent === 'string' && params.agent.trim().length > 0 ? params.agent : undefined
162
249
 
163
250
  let config: ReturnType<typeof readUserDecisionRouterConfig>
164
251
  try {
165
252
  config = readUserDecisionRouterConfig()
166
253
  } catch {
167
- return refusal('CONFIG_UNAVAILABLE')
168
- }
169
- if (!config.enabled) return refusal('DISABLED')
170
- if (!config.egress_consent) return refusal('CONSENT_MISSING')
171
-
172
- let catalog: JevDecisionCatalogEntry[]
173
- try {
174
- catalog = await readCatalog(runtime)
175
- } catch {
176
- return refusal('CATALOG_UNAVAILABLE')
254
+ return { ok: false, reasonCode: 'CONFIG_UNAVAILABLE' }
177
255
  }
256
+ if (!config.enabled) return { ok: false, reasonCode: 'DISABLED' }
257
+ if (!config.egress_consent) return { ok: false, reasonCode: 'CONSENT_MISSING' }
178
258
 
179
259
  const ledger = openLocalDecisionBudgetLedger({ dbPath: resolveLocalDecisionBudgetDbPath() })
180
260
  try {
181
261
  const selection = resolveNativeJevRoute(
182
262
  config,
183
- catalog,
184
263
  (provider, model) => ledger.canReserve(provider, model).status === 'eligible',
185
264
  )
186
- if (!selection.ok) return refusal(selection.reasonCode)
265
+ if (!selection.ok) return { ok: false, reasonCode: selection.reasonCode }
187
266
 
188
- if (typeof runtime.permissionAssert !== 'function') return refusal('PERMISSION_UNAVAILABLE')
267
+ if (typeof params.runtime.permissionAssert !== 'function') {
268
+ return { ok: false, reasonCode: 'PERMISSION_UNAVAILABLE' }
269
+ }
189
270
  const assertion = await assertDecisionEgressPermission(
190
- runtime.permissionAssert,
271
+ params.runtime.permissionAssert,
191
272
  buildDecisionEgressRequest({
192
273
  sessionID,
193
274
  messageID,
@@ -195,36 +276,55 @@ export async function runJevDecision(
195
276
  selection.selection.route.model.providerID,
196
277
  selection.selection.route.model.id,
197
278
  ),
198
- agent: 'zeus',
279
+ ...(agent === undefined ? {} : { agent }),
199
280
  }),
200
281
  )
201
- if (assertion === 'deny') return refusal('PERMISSION_DENIED')
202
-
203
- const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
204
- const prepared =
205
- requested.mode === undefined
206
- ? prepareJevDecisionRequest(selection.selection.route, input ?? {})
207
- : isJevDecisionPreset(requested.mode)
208
- ? prepareJevPresetRequest(
209
- selection.selection.route,
210
- requested.mode,
211
- input ?? {},
212
- requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
213
- )
214
- : { ok: false as const, reasonCode: 'PRESET_INVALID' as const }
215
- if (!prepared.ok) return refusal(prepared.reasonCode)
216
-
217
- const reservation = ledger.reserve(
282
+ if (assertion === 'deny') return { ok: false, reasonCode: 'PERMISSION_DENIED' }
283
+
284
+ const prepared = await params.prepare(selection.selection.route)
285
+ if (!prepared.ok) return { ok: false, reasonCode: prepared.reasonCode }
286
+
287
+ const reservation: ReservationResult = ledger.reserve(
218
288
  selection.selection.accountingProvider,
219
289
  selection.selection.model,
220
290
  )
221
- if (reservation.status !== 'reserved') return refusal('RESERVATION_DENIED')
291
+ if (reservation.status !== 'reserved') return { ok: false, reasonCode: 'RESERVATION_DENIED' }
222
292
 
223
293
  let response: unknown
224
294
  try {
225
- response = await runtime.decide(prepared.request)
226
- } catch {
227
- return refusal('DECISION_CALL_FAILED')
295
+ response = await params.runtime.decide(prepared.request)
296
+ } catch (err) {
297
+ // Provider-layer errors carry bounded, non-content facts that change
298
+ // what the user does next: the host's reason class (`rate_limit` vs
299
+ // auth vs unknown) and, for rate limits, the retry window. The error
300
+ // message text NEVER crosses (it carries URLs and subscription prose).
301
+ const failure: {
302
+ ok: false
303
+ reasonCode: 'DECISION_CALL_FAILED'
304
+ detail: string
305
+ providerReason?: string
306
+ status?: number
307
+ retryAfterMs?: number
308
+ } = {
309
+ ok: false,
310
+ reasonCode: 'DECISION_CALL_FAILED',
311
+ detail: err instanceof Error ? err.name : 'UnknownFailure',
312
+ }
313
+ const errRecord = err as { reason?: unknown; status?: unknown; retryAfterMs?: unknown }
314
+ if (typeof errRecord.reason === 'string' && /^[a-z_]{1,32}$/i.test(errRecord.reason)) {
315
+ failure.providerReason = errRecord.reason
316
+ }
317
+ if (typeof errRecord.status === 'number' && Number.isInteger(errRecord.status)) {
318
+ failure.status = errRecord.status
319
+ }
320
+ if (
321
+ typeof errRecord.retryAfterMs === 'number' &&
322
+ Number.isFinite(errRecord.retryAfterMs) &&
323
+ errRecord.retryAfterMs > 0
324
+ ) {
325
+ failure.retryAfterMs = Math.round(errRecord.retryAfterMs)
326
+ }
327
+ return failure
228
328
  }
229
329
 
230
330
  const evidence = verifyNativeUsageForReservation(
@@ -236,40 +336,242 @@ export async function runJevDecision(
236
336
  },
237
337
  response,
238
338
  )
239
- if (evidence === null) return refusal('USAGE_UNRECONCILED')
339
+ if (evidence === null) return { ok: false, reasonCode: 'USAGE_UNRECONCILED' }
240
340
  const reconciliation = ledger.reconcileVerified(reservation.reservationId, evidence)
241
- if (reconciliation.status !== 'reconciled') return refusal('USAGE_UNRECONCILED')
341
+ if (reconciliation.status !== 'reconciled') {
342
+ return { ok: false, reasonCode: 'USAGE_UNRECONCILED' }
343
+ }
242
344
 
243
- const advice = consumeJevDecisionResult(response, prepared.request)
345
+ return {
346
+ ok: true,
347
+ call: {
348
+ selection: selection.selection,
349
+ request: prepared.request,
350
+ response,
351
+ frozen: reconciliation.frozen,
352
+ },
353
+ }
354
+ } finally {
355
+ ledger.close()
356
+ }
357
+ }
358
+
359
+ /**
360
+ * Read the host's installed skills for the stacking preset. Anything that is
361
+ * not a plain {id, description?} record is skipped; a missing or hostile
362
+ * registry degrades to the catalog-only preset. Reading the registry applies
363
+ * no trust: installation already was the user's manual, reviewed act.
364
+ */
365
+ async function readHostSkills(runtime: V2JevDecisionRuntime): Promise<JevHostSkill[] | undefined> {
366
+ if (typeof runtime.listSkills !== 'function') return undefined
367
+ let raw: unknown
368
+ try {
369
+ raw = await runtime.listSkills()
370
+ } catch {
371
+ return undefined
372
+ }
373
+ if (!Array.isArray(raw)) return undefined
374
+ const skills: JevHostSkill[] = []
375
+ for (const entry of raw) {
376
+ if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
377
+ const record = entry as { id?: unknown; description?: unknown }
378
+ if (typeof record.id !== 'string' || record.id.length === 0) continue
379
+ skills.push({
380
+ id: record.id,
381
+ ...(typeof record.description === 'string' && record.description.length > 0
382
+ ? { description: record.description }
383
+ : {}),
384
+ })
385
+ }
386
+ return skills
387
+ }
388
+
389
+ /**
390
+ * Run one explicit, gate-checked native Jev decision. Every failure path
391
+ * returns a bounded refusal JSON; the only caller-visible success output is
392
+ * the validated advice with `effect: 'none'`.
393
+ *
394
+ * The `mode: "review"` branch (J4 output-quality scoring, advisory only)
395
+ * validates and builds its bounded request BEFORE the gate chain — the same
396
+ * prebuilt-request pattern the J1/J3 observers use — so a malformed review
397
+ * never spends gate work, and its failure codes stay tool-surface properties.
398
+ * It records ONE J4 telemetry record per run (q-token on an answered review,
399
+ * skip tokens on every refusal path) and returns the evaluation plus the
400
+ * verdict flag; the verdict never blocks, retries, or alters anything.
401
+ */
402
+ export async function runJevDecision(
403
+ input: unknown,
404
+ toolContext: unknown,
405
+ runtime: V2JevDecisionRuntime,
406
+ ): Promise<string> {
407
+ const context =
408
+ toolContext !== null && typeof toolContext === 'object' && !Array.isArray(toolContext)
409
+ ? (toolContext as JevToolContext)
410
+ : undefined
411
+ const caller = context?.agent
412
+ if (typeof caller !== 'string' || caller.length === 0) return refusal('CALLER_NOT_ALLOWED')
413
+ const allowlist = runtime.specialistCallers ?? []
414
+ if (caller !== 'zeus' && !allowlist.includes(caller)) {
415
+ return refusal('CALLER_NOT_ALLOWED')
416
+ }
417
+
418
+ const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
419
+ // Preset modes stay orchestrator-owned even when the flag widens the
420
+ // caller matrix: owner/skill selection and result scoring are
421
+ // orchestration decisions; allowlisted specialists may ask bounded typed
422
+ // questions only.
423
+ if (caller !== 'zeus' && requested.mode !== undefined) {
424
+ return refusal('CALLER_NOT_ALLOWED')
425
+ }
426
+ // Review mode (J4): the bounded request is built before any gate work, and
427
+ // 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
430
+ if (requested.mode === 'review') {
431
+ const prepared = buildJevReviewRequest(input ?? {})
432
+ if (!prepared.ok) {
433
+ observeShadow(
434
+ J4_QUALITY_SCORE_POINT,
435
+ prepared.reasonCode,
436
+ () => ({
437
+ decision: 'unavailable',
438
+ reason: reviewRefusalSkipReason(prepared.reasonCode),
439
+ }),
440
+ runtime.shadowSink,
441
+ )
442
+ return refusal(prepared.reasonCode)
443
+ }
444
+ reviewRequest = prepared.request
445
+ }
446
+ const result = await runGatedNativeJevCall({
447
+ sessionID: context?.sessionID,
448
+ messageID: context?.messageID,
449
+ agent: caller,
450
+ runtime,
451
+ prepare: async (route) =>
452
+ reviewRequest !== undefined
453
+ ? {
454
+ ok: true as const,
455
+ request: {
456
+ model: route.model,
457
+ input: reviewRequest.input,
458
+ questions: reviewRequest.questions,
459
+ },
460
+ }
461
+ : requested.mode === undefined
462
+ ? prepareJevDecisionRequest(route, input ?? {})
463
+ : isJevDecisionPreset(requested.mode)
464
+ ? prepareJevPresetRequest(
465
+ route,
466
+ requested.mode,
467
+ input ?? {},
468
+ requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
469
+ )
470
+ : { ok: false as const, reasonCode: 'PRESET_INVALID' as const },
471
+ })
472
+ if (!result.ok) {
473
+ if (requested.mode === 'review') {
474
+ // The review observed a gate refusal: one skip record, the refusal
475
+ // itself is unchanged.
476
+ observeShadow(
477
+ J4_QUALITY_SCORE_POINT,
478
+ result.reasonCode,
479
+ () => ({
480
+ decision: 'unavailable',
481
+ reason: reviewRefusalSkipReason(result.reasonCode),
482
+ }),
483
+ runtime.shadowSink,
484
+ )
485
+ }
486
+ if (result.detail === undefined && result.providerReason === undefined) {
487
+ return refusal(result.reasonCode)
488
+ }
489
+ // Refusal with the error CLASS only (`TypeError`, `RangeError`, …) plus
490
+ // the bounded provider facts (`rate_limit`, status, retry window): the
491
+ // message can carry paths, config or provider detail and never crosses
492
+ // into the chat.
493
+ return JSON.stringify({
494
+ advisory: false,
495
+ effect: 'none',
496
+ reasonCode: result.reasonCode,
497
+ ...(result.detail === undefined ? {} : { detail: result.detail }),
498
+ ...(result.providerReason === undefined ? {} : { providerReason: result.providerReason }),
499
+ ...(result.status === undefined ? {} : { status: result.status }),
500
+ ...(result.retryAfterMs === undefined ? {} : { retryAfterMs: result.retryAfterMs }),
501
+ })
502
+ }
503
+
504
+ const advice = consumeJevDecisionResult(result.call.response, result.call.request)
505
+ if (requested.mode === 'review') {
506
+ // J4 advisory evaluation: strict validation, the verdict is telemetry
507
+ // plus a returned flag — it never blocks, retries, or alters the result.
508
+ const evaluation: QualityScoreEvaluation = evaluateQualityScoreDecision(
509
+ result.call.response,
510
+ result.call.request,
511
+ )
512
+ observeShadow(
513
+ J4_QUALITY_SCORE_POINT,
514
+ evaluation,
515
+ (isolated) => {
516
+ const scored = isolated as QualityScoreEvaluation
517
+ return {
518
+ decision: qualityVerdict(scored),
519
+ reason: encodeQualityScoreReason(scored),
520
+ }
521
+ },
522
+ runtime.shadowSink,
523
+ )
244
524
  return JSON.stringify({
245
525
  advisory: true,
246
526
  effect: 'none',
247
527
  reason: 'JEV_DECISION',
528
+ caller,
248
529
  route: {
249
- providerID: selection.selection.route.model.providerID,
250
- id: selection.selection.route.model.id,
251
- billing: selection.selection.route.billing,
530
+ providerID: result.call.selection.route.model.providerID,
531
+ id: result.call.selection.route.model.id,
532
+ billing: result.call.selection.route.billing,
252
533
  },
253
- ...(requested.mode === undefined ? {} : { preset: requested.mode }),
534
+ mode: 'review',
535
+ quality: evaluation.quality,
536
+ needsReview: evaluation.needsReview,
537
+ verdict: qualityVerdict(evaluation),
254
538
  answers: advice.answers,
255
539
  missing: advice.missing,
256
540
  usage: { costUsd: advice.costUsd, tokens: advice.tokens },
257
- frozen: reconciliation.frozen,
541
+ frozen: result.call.frozen,
258
542
  })
259
- } finally {
260
- ledger.close()
261
543
  }
544
+ return JSON.stringify({
545
+ advisory: true,
546
+ effect: 'none',
547
+ reason: 'JEV_DECISION',
548
+ caller,
549
+ route: {
550
+ providerID: result.call.selection.route.model.providerID,
551
+ id: result.call.selection.route.model.id,
552
+ billing: result.call.selection.route.billing,
553
+ },
554
+ ...(requested.mode === undefined ? {} : { preset: requested.mode }),
555
+ answers: advice.answers,
556
+ missing: advice.missing,
557
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
558
+ frozen: result.call.frozen,
559
+ })
262
560
  }
263
561
 
264
562
  const TOOL_DESCRIPTION =
265
563
  'Zeus-only advisory typed decisions via the host native Jev route (OpenCode Console or a ' +
266
- 'configured decision model). Two ways to ask: pass `mode: "skills"` to stack skills for the ' +
564
+ 'configured decision model). Required: schemaVersion: 1 and a non-empty state (<=12000 chars). ' +
565
+ 'Ways to ask: pass `mode: "skills"` to stack skills for the ' +
267
566
  'state text (local prefilter shortlist, catalog fallback, plus every skill installed in the ' +
268
567
  'host), `mode: "delegation"` to pick ' +
269
- 'a specialist, or pass explicit typed `questions` (choice, score, predicate). Returns ' +
270
- 'probabilistic answers with confidence. Requires decision-router egress consent and budget ' +
271
- 'caps; asks host permission first. It never dispatches agents, runs skills, executes tools, ' +
272
- 'or alters permissions — results are advisory only.'
568
+ 'a specialist, `mode: "review"` to score a finished delegated result against named criteria ' +
569
+ '(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, ' +
571
+ 'predicate). Invalid-input refusals carry a `detail` token naming the exact cause. Returns ' +
572
+ 'probabilistic answers with confidence. Requires decision-router egress ' +
573
+ 'consent and budget caps; asks host permission first. It never dispatches agents, runs ' +
574
+ 'skills, executes tools, blocks, retries, or alters permissions — results are advisory only.'
273
575
 
274
576
  const questionSchema = {
275
577
  type: 'object',
@@ -310,15 +612,51 @@ const questionSchema = {
310
612
  },
311
613
  }
312
614
 
615
+ const REVIEW_METRICS_SCHEMA = {
616
+ type: 'object',
617
+ additionalProperties: false,
618
+ required: ['outputChars', 'taskDurationMs'],
619
+ properties: {
620
+ outputChars: { type: 'integer', minimum: 0, maximum: 100_000_000 },
621
+ taskDurationMs: { type: ['integer', 'null'], minimum: 0, maximum: 100_000_000 },
622
+ },
623
+ } as const
624
+
625
+ /**
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
628
+ * shape metrics, a delegate id and named criteria — never a state text, never
629
+ * 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.
632
+ */
313
633
  const JEV_INPUT_SCHEMA: Record<string, unknown> = {
314
634
  type: 'object',
315
635
  additionalProperties: false,
316
- required: ['schemaVersion', 'state'],
636
+ required: ['schemaVersion'],
637
+ anyOf: [
638
+ { required: ['state'] },
639
+ { required: ['delegateId', 'resultSummaryKind', 'resultMetrics', 'criteria'] },
640
+ ],
317
641
  properties: {
318
642
  schemaVersion: { type: 'integer', const: 1 },
319
643
  state: { type: 'string', minLength: 1, maxLength: 12_000 },
320
- mode: { type: 'string', enum: ['skills', 'delegation'] },
644
+ mode: { type: 'string', enum: ['skills', 'delegation', 'review'] },
321
645
  questions: { type: 'array', minItems: 1, maxItems: 4, items: questionSchema },
646
+ delegateId: {
647
+ type: 'string',
648
+ minLength: 1,
649
+ maxLength: 64,
650
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
651
+ },
652
+ resultSummaryKind: { type: 'string', enum: ['ok', 'empty', 'error'] },
653
+ resultMetrics: REVIEW_METRICS_SCHEMA,
654
+ criteria: {
655
+ type: 'array',
656
+ minItems: 1,
657
+ maxItems: 4,
658
+ items: { type: 'string', minLength: 1, maxLength: 120 },
659
+ },
322
660
  },
323
661
  }
324
662