pantheon-opencode 1.6.2-beta.8 → 1.6.2

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 (81) hide show
  1. package/CHANGELOG.md +121 -3
  2. package/README.md +34 -60
  3. package/README.pt-BR.md +10 -12
  4. package/bin/pantheon-init.mjs +30 -32
  5. package/package.json +3 -3
  6. package/plugin.json +1 -1
  7. package/pyproject.toml +1 -1
  8. package/scripts/decision-router.mjs +41 -56
  9. package/scripts/install/decision-router-config.mjs +67 -1
  10. package/scripts/install/npx-cache-sweep.mjs +103 -0
  11. package/scripts/install/opencode.mjs +7 -7
  12. package/scripts/install/plugin.mjs +4 -3
  13. package/scripts/install/strings.mjs +4 -0
  14. package/scripts/release-gates.mjs +6 -82
  15. package/scripts/sync-tui.mjs +3 -3
  16. package/src/agents/aphrodite.md +1 -1
  17. package/src/agents/apollo.md +1 -0
  18. package/src/agents/athena.md +1 -0
  19. package/src/agents/demeter.md +1 -1
  20. package/src/agents/gaia.md +1 -0
  21. package/src/agents/hephaestus.md +1 -1
  22. package/src/agents/hermes.md +1 -1
  23. package/src/agents/iris.md +1 -1
  24. package/src/agents/mnemosyne.md +1 -0
  25. package/src/agents/nyx.md +1 -1
  26. package/src/agents/prometheus.md +1 -1
  27. package/src/agents/talos.md +1 -1
  28. package/src/agents/themis.md +1 -1
  29. package/src/agents/zeus.md +5 -2
  30. package/src/pantheon/jev-decision-tool.ts +366 -114
  31. package/src/pantheon/jev-decisions.ts +11 -13
  32. package/src/pantheon/jev-escalation.ts +639 -0
  33. package/src/pantheon/jev-quality-score.ts +432 -0
  34. package/src/pantheon/jev-risk-gate.ts +479 -0
  35. package/src/pantheon/local-decision-prompt.ts +12 -18
  36. package/src/pantheon/v2-decision-telemetry.ts +14 -4
  37. package/src/pantheon/v2-native-decisions.ts +1 -1
  38. package/src/plugin-v2.ts +201 -24
  39. package/src/plugins/tui/dist/server-v2.d.ts +19 -11
  40. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  41. package/src/plugins/tui/dist/server-v2.js +19 -789
  42. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  43. package/src/plugins/tui/dist/tui-v2.d.ts +12 -331
  44. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  45. package/src/plugins/tui/dist/tui-v2.js +257 -5370
  46. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  47. package/src/plugins/tui/dist/tui.js +1 -1
  48. package/src/plugins/tui/package-lock.json +2 -2
  49. package/src/plugins/tui/package.json +1 -1
  50. package/src/plugins/tui/src/index-v2.tsx +213 -86
  51. package/src/plugins/tui/src/server-v2.ts +18 -982
  52. package/src/plugins/tui/tsconfig.typecheck.json +1 -6
  53. package/src/plugins/tui/tsdown.config.ts +1 -11
  54. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js +0 -749
  55. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js.map +0 -1
  56. package/src/plugins/tui/dist/quota-adapters.d.ts +0 -89
  57. package/src/plugins/tui/dist/quota-adapters.d.ts.map +0 -1
  58. package/src/plugins/tui/dist/quota-adapters.js +0 -1142
  59. package/src/plugins/tui/dist/quota-adapters.js.map +0 -1
  60. package/src/plugins/tui/dist/quota-cli.d.ts +0 -17
  61. package/src/plugins/tui/dist/quota-cli.d.ts.map +0 -1
  62. package/src/plugins/tui/dist/quota-cli.js +0 -184
  63. package/src/plugins/tui/dist/quota-cli.js.map +0 -1
  64. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js +0 -684
  65. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js.map +0 -1
  66. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js +0 -118
  67. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js.map +0 -1
  68. package/src/plugins/tui/dist/usage-history-worker.js +0 -25
  69. package/src/plugins/tui/dist/usage-history-worker.js.map +0 -1
  70. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +0 -100
  71. package/src/plugins/tui/src/go-key-diagnostic.ts +0 -125
  72. package/src/plugins/tui/src/quota-adapters.ts +0 -1598
  73. package/src/plugins/tui/src/quota-cli.ts +0 -237
  74. package/src/plugins/tui/src/quota-rpc.ts +0 -373
  75. package/src/plugins/tui/src/quota-v2-model.ts +0 -1032
  76. package/src/plugins/tui/src/quota-v2.tsx +0 -1238
  77. package/src/plugins/tui/src/usage-history-contract.ts +0 -217
  78. package/src/plugins/tui/src/usage-history-validation.ts +0 -104
  79. package/src/plugins/tui/src/usage-history-view.tsx +0 -236
  80. package/src/plugins/tui/src/usage-history-worker.ts +0 -25
  81. package/src/plugins/tui/src/usage-view-model.ts +0 -272
@@ -0,0 +1,432 @@
1
+ /**
2
+ * J4 output-quality scoring — advisory, on-demand review of a delegated
3
+ * result through the native Jev route (the jev-dsh-decision pattern).
4
+ *
5
+ * After a delegation completes, Zeus can explicitly request a review through
6
+ * the `pantheon_jev_decide` tool's `mode: "review"`: ONE typed round-trip that
7
+ * asks TWO questions — a `score` ("quality of this delegated result against
8
+ * the criteria", the full 2..10 rubric bound) and a `predicate` (`noul`,
9
+ * "does this result need human review?") — through the SAME gate chain every
10
+ * other consumer runs (user-level config, egress consent, budget-ledger
11
+ * reservation, the host permission kill-switch on `decision.egress`).
12
+ *
13
+ * ## Advisory contract
14
+ *
15
+ * The verdict ({@link qualityVerdict}) is PURE policy and its
16
+ * `flag-for-review` outcome is advisory telemetry plus a flag the tool output
17
+ * may surface — it NEVER blocks, retries, or alters the delegated result. The
18
+ * verdict follows the host's explicit review answer only: a LOW quality score
19
+ * with an explicit no-review answer records without flagging (the score is
20
+ * surfaced for Zeus to weigh; this module does not second-guess it). There is
21
+ * no automatic hook: review happens when Zeus asks, matching the reference
22
+ * design's on-demand scoring.
23
+ *
24
+ * ## Sanitization contract (J1/J3 discipline, one step stricter)
25
+ *
26
+ * The result itself NEVER leaves the machine — the request has NO content
27
+ * field at all (structural, not a scrub): the state is an exact bounded
28
+ * template over shape metrics only (the delegate id, the result kind
29
+ * `ok|empty|error`, the output character count, the task duration, the
30
+ * criteria count), and the criteria are the ONLY free text admitted, riding
31
+ * the score question's instructions. Criteria are caller-provided instruction
32
+ * strings (1–120 chars each, at most {@link J4_MAX_CRITERIA} of them) that
33
+ * come from the tool schema, never user text; hostile shapes — paths, path
34
+ * separators, credential assignments and key material, control characters,
35
+ * over-length — are rejected `CRITERIA_INVALID`, never sanitized on the way
36
+ * in. The delegate id must be a canonical Pantheon agent token; the metrics
37
+ * must be bounded non-negative integers (a `null` duration means "unknown").
38
+ *
39
+ * ## DSH hard caps, mirrored
40
+ *
41
+ * The reference design's request bounds are mirrored where this surface can
42
+ * enforce them: at most 4 criteria per call ({@link J4_MAX_CRITERIA}), each a
43
+ * bounded 1–120-char instruction string, ONE request per review (no retry, no
44
+ * queue — settlement is the shared runner's fail-closed contract), and
45
+ * redacted errors everywhere (gate failures surface reason codes; call
46
+ * failures carry the error CLASS only — the host's message text never crosses
47
+ * into the tool output).
48
+ *
49
+ * "The agent's explanation is not Jev's raw output": the consumer reuses the
50
+ * tool's strict validation (`consumeJevDecisionResult`) — an answer counts
51
+ * only when its name and type match the prepared questions, duplicates become
52
+ * errors, and unbounded host metadata never reaches the evaluation.
53
+ *
54
+ * @module jev-quality-score
55
+ */
56
+
57
+ import { consumeJevDecisionResult } from './jev-decisions.ts'
58
+ import { PANTHEON_AGENTS } from './v2-delegation-enforce.ts'
59
+ import type { NativeDecisionRequest, ResolvedNativeDecisionRoute } from './v2-native-decisions.ts'
60
+
61
+ /** Telemetry point id for the output-quality review (J-series: Jev uplift). */
62
+ export const J4_QUALITY_SCORE_POINT = 'J4'
63
+
64
+ /** Question names of the two prepared questions, matched on consumption. */
65
+ export const QUALITY_QUESTION_NAME = 'quality'
66
+ export const REVIEW_QUESTION_NAME = 'noul'
67
+
68
+ /** DSH hard-cap mirror: at most 4 criteria per review request. */
69
+ export const J4_MAX_CRITERIA = 4
70
+ /** A rubric needs at least one named criterion. */
71
+ export const J4_MIN_CRITERIA = 1
72
+ /** Each criterion is a bounded instruction string (1–120 chars). */
73
+ export const J4_CRITERIA_MAX_LENGTH = 120
74
+
75
+ /** Rubric levels offered to the host: the full 2..10 score-question bound. */
76
+ export const J4_QUALITY_LEVEL_COUNT = 9
77
+
78
+ /**
79
+ * Predicate probability at or above which `noul` counts as "needs review".
80
+ */
81
+ export const J4_REVIEW_THRESHOLD = 0.5
82
+
83
+ /** Bound for the composed state text (the template is ~370 chars at worst). */
84
+ export const J4_QUALITY_SCORE_STATE_MAX_LENGTH = 512
85
+
86
+ /** Upper bound for the structural metrics printed into the template. */
87
+ const METRICS_MAX = 100_000_000
88
+
89
+ export type QualityScoreResultKind = 'ok' | 'empty' | 'error'
90
+
91
+ const RESULT_KINDS: ReadonlySet<string> = new Set(['ok', 'empty', 'error'])
92
+
93
+ const TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
94
+
95
+ export interface QualityScoreRequestInput {
96
+ /** The canonical Pantheon agent id whose result is being reviewed. */
97
+ readonly delegateId: string
98
+ /** The result's shape class — the only "what happened" that crosses. */
99
+ readonly resultSummaryKind: QualityScoreResultKind
100
+ /** Structural metrics only: never content. */
101
+ readonly resultMetrics: {
102
+ readonly outputChars: number
103
+ readonly taskDurationMs: number | null
104
+ }
105
+ /** Named criteria; the ONLY free text the request admits. */
106
+ readonly criteria: readonly string[]
107
+ }
108
+
109
+ export type QualityScoreRequestFailure = 'CRITERIA_INVALID' | 'INPUT_INVALID'
110
+
111
+ export type QualityScorePreparedRequest =
112
+ | {
113
+ readonly ok: true
114
+ /** The request body; the caller attaches the resolved route's `model`. */
115
+ readonly request: Omit<NativeDecisionRequest, 'model'>
116
+ }
117
+ | { readonly ok: false; readonly reasonCode: QualityScoreRequestFailure }
118
+
119
+ const QUALITY_LABELS = [
120
+ 'unusable',
121
+ 'poor',
122
+ 'weak',
123
+ 'fair',
124
+ 'adequate',
125
+ 'good',
126
+ 'strong',
127
+ 'excellent',
128
+ 'exemplary',
129
+ ] as const
130
+
131
+ const QUALITY_INSTRUCTIONS_PREFIX =
132
+ 'Rate the quality of this delegated result against the criteria listed below; the criteria ' +
133
+ 'are required and the structural metrics in the state are context only. Judge the result ' +
134
+ 'itself, not the delegation that produced it. Advisory only; nothing is enforced.'
135
+
136
+ const REVIEW_INSTRUCTIONS =
137
+ 'Does this delegated result need human review before it is used? Answer as a probability: ' +
138
+ 'higher means review is more warranted. A yes is advisory only; it never blocks, retries, ' +
139
+ 'or alters the result.'
140
+
141
+ /** Path separators in any position: a criterion is prose, never a location. */
142
+ const PATH_PATTERN = /[/\\]/
143
+
144
+ /**
145
+ * Control characters (C0 and DEL — newlines and tabs included): criteria are
146
+ * single-line prose. An explicit code-point scan, not a regex, so the hostile
147
+ * input check stays lint-clean without a rule suppression.
148
+ */
149
+ function hasControlCharacter(value: string): boolean {
150
+ for (let index = 0; index < value.length; index += 1) {
151
+ const code = value.charCodeAt(index)
152
+ if (code <= 0x1f || code === 0x7f) return true
153
+ }
154
+ return false
155
+ }
156
+ /** Key material shapes: PEM headers, AWS/SDK/Git token literals, key files. */
157
+ const KEY_MATERIAL_PATTERNS: readonly RegExp[] = Object.freeze([
158
+ /-----BEGIN/,
159
+ /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
160
+ /\bsk-[A-Za-z0-9_-]{16,}\b/,
161
+ /\bgh[pousr]_[A-Za-z0-9]{20,}\b/,
162
+ /\b[a-z0-9._-]+\.(?:key|pem|p12|pfx|kdbx)\b/i,
163
+ ])
164
+ /**
165
+ * Credential ASSIGNMENT shapes only: naming a concept is prose ("handles
166
+ * secrets without echoing them" stays admissible); binding a value to it
167
+ * ("password=hunter2") is a credential shape and is rejected.
168
+ */
169
+ const CREDENTIAL_ASSIGNMENT_PATTERN =
170
+ /\b(?:password|passwd|secret|token|api[-_]?key|credential)s?\s*[:=]\s*\S+/i
171
+
172
+ function isRecord(value: unknown): value is Record<string, unknown> {
173
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
174
+ }
175
+
176
+ function isBoundedCount(value: unknown): value is number {
177
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= METRICS_MAX
178
+ }
179
+
180
+ /** Whether one criterion is a hostile shape (rejected, never scrubbed). */
181
+ function isHostileCriterion(criterion: string): boolean {
182
+ if (PATH_PATTERN.test(criterion)) return true
183
+ if (hasControlCharacter(criterion)) return true
184
+ if (KEY_MATERIAL_PATTERNS.some((pattern) => pattern.test(criterion))) return true
185
+ return CREDENTIAL_ASSIGNMENT_PATTERN.test(criterion)
186
+ }
187
+
188
+ /**
189
+ * Build the bounded review request — the sanitization contract made
190
+ * structural. One text part (the exact metrics template), ONE score question
191
+ * (the 2..10 quality rubric, criteria listed in its instructions) and ONE
192
+ * predicate question (`noul`). No file parts, no JSON parts, no content
193
+ * field. Hostile input is rejected, never sanitized on the way in.
194
+ */
195
+ export function buildQualityScoreRequest(
196
+ input: QualityScoreRequestInput,
197
+ ): QualityScorePreparedRequest {
198
+ const record = isRecord(input) ? input : undefined
199
+ const delegateId = record?.delegateId
200
+ if (
201
+ typeof delegateId !== 'string' ||
202
+ !TOKEN_PATTERN.test(delegateId) ||
203
+ !PANTHEON_AGENTS.has(delegateId)
204
+ ) {
205
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
206
+ }
207
+ const resultSummaryKind = record?.resultSummaryKind
208
+ if (typeof resultSummaryKind !== 'string' || !RESULT_KINDS.has(resultSummaryKind)) {
209
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
210
+ }
211
+ const metrics = record?.resultMetrics
212
+ if (!isRecord(metrics)) return { ok: false, reasonCode: 'INPUT_INVALID' }
213
+ if (!isBoundedCount(metrics.outputChars)) return { ok: false, reasonCode: 'INPUT_INVALID' }
214
+ const taskDurationMs = metrics.taskDurationMs
215
+ if (taskDurationMs !== null && !isBoundedCount(taskDurationMs)) {
216
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
217
+ }
218
+ const criteria = record?.criteria
219
+ if (!Array.isArray(criteria)) return { ok: false, reasonCode: 'CRITERIA_INVALID' }
220
+ if (criteria.length < J4_MIN_CRITERIA || criteria.length > J4_MAX_CRITERIA) {
221
+ return { ok: false, reasonCode: 'CRITERIA_INVALID' }
222
+ }
223
+ for (const criterion of criteria) {
224
+ if (
225
+ typeof criterion !== 'string' ||
226
+ criterion.length < 1 ||
227
+ criterion.length > J4_CRITERIA_MAX_LENGTH ||
228
+ criterion.trim().length === 0 ||
229
+ isHostileCriterion(criterion)
230
+ ) {
231
+ return { ok: false, reasonCode: 'CRITERIA_INVALID' }
232
+ }
233
+ }
234
+
235
+ const state =
236
+ 'Advisory quality review of one delegated result. ' +
237
+ `delegate: ${delegateId}. result_kind: ${resultSummaryKind}. output_chars: ${metrics.outputChars}. ` +
238
+ `task_duration_ms: ${taskDurationMs === null ? 'na' : String(taskDurationMs)}. ` +
239
+ `criteria_count: ${criteria.length}. ` +
240
+ 'The result content never leaves this machine; the criteria are listed in the quality ' +
241
+ 'question; judge from the structural fields and the criteria alone.'
242
+ if (state.length > J4_QUALITY_SCORE_STATE_MAX_LENGTH) {
243
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
244
+ }
245
+ const qualityInstructions =
246
+ QUALITY_INSTRUCTIONS_PREFIX +
247
+ ` Criteria: ${criteria.map((criterion, index) => `(${index + 1}) ${criterion}`).join('; ')}.`
248
+ return {
249
+ ok: true,
250
+ request: Object.freeze({
251
+ input: Object.freeze([Object.freeze({ type: 'text' as const, text: state })]),
252
+ questions: Object.freeze([
253
+ Object.freeze({
254
+ type: 'score' as const,
255
+ name: QUALITY_QUESTION_NAME,
256
+ instructions: qualityInstructions,
257
+ levels: Object.freeze(QUALITY_LABELS.map((label) => Object.freeze({ label }))),
258
+ }),
259
+ Object.freeze({
260
+ type: 'predicate' as const,
261
+ name: REVIEW_QUESTION_NAME,
262
+ instructions: REVIEW_INSTRUCTIONS,
263
+ }),
264
+ ]),
265
+ }),
266
+ }
267
+ }
268
+
269
+ export interface QualityScoreEvaluation {
270
+ /**
271
+ * The host's score for the `quality` question; `null` when the answer is
272
+ * missing, mistyped, duplicated or an error. A raw ordinal on the prepared
273
+ * 2..10 rubric, surfaced for Zeus to weigh — never a gate.
274
+ */
275
+ readonly quality: number | null
276
+ /**
277
+ * Whether the `noul` predicate holds (probability ≥ 0.5); `null` under the
278
+ * same failures.
279
+ */
280
+ readonly needsReview: boolean | null
281
+ }
282
+
283
+ /**
284
+ * Consume a host Decisions response against the prepared request.
285
+ *
286
+ * Validation is strict and borrowed wholesale from the tool's own consumer
287
+ * (`consumeJevDecisionResult`): an answer counts only when its name and type
288
+ * match the prepared questions, score answers carry a non-negative finite
289
+ * score, predicate answers a probability in [0, 1], and duplicates become
290
+ * errors. Anything else — and any unknown response shape — is `null`, never a
291
+ * guess. Extra fields on answers never cross into the evaluation.
292
+ */
293
+ export function evaluateQualityScoreDecision(
294
+ response: unknown,
295
+ prepared: NativeDecisionRequest,
296
+ ): QualityScoreEvaluation {
297
+ const advice = consumeJevDecisionResult(response, prepared)
298
+ let quality: number | null = null
299
+ let needsReview: boolean | null = null
300
+ for (const answer of advice.answers) {
301
+ if (answer.type === 'error') continue
302
+ if (answer.type === 'score' && answer.name === QUALITY_QUESTION_NAME) {
303
+ quality = answer.score ?? null
304
+ } else if (answer.type === 'predicate' && answer.name === REVIEW_QUESTION_NAME) {
305
+ needsReview = (answer.probability ?? 0) >= J4_REVIEW_THRESHOLD
306
+ }
307
+ }
308
+ return { quality, needsReview }
309
+ }
310
+
311
+ /**
312
+ * The verdict of one review: `recorded` or `flag-for-review`. PURE and
313
+ * advisory — the flag is telemetry plus a tool-output field the caller may
314
+ * surface; nothing is ever blocked, retried, or altered. An affirmative
315
+ * `needsReview` is the ONE flagging condition; a negative or absent answer
316
+ * records, and the quality score never flags on its own.
317
+ */
318
+ export type QualityVerdict = 'recorded' | 'flag-for-review'
319
+
320
+ export function qualityVerdict(input: {
321
+ readonly quality: number | null
322
+ readonly needsReview: boolean | null
323
+ }): QualityVerdict {
324
+ void input.quality // the score is surfaced, never enforced
325
+ return input.needsReview === true ? 'flag-for-review' : 'recorded'
326
+ }
327
+
328
+ const REASON_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
329
+
330
+ function formatScoreToken(value: number): string {
331
+ if (!Number.isFinite(value) || value < 0 || value > 1000) return 'na'
332
+ const text = String(Math.round(value * 100) / 100)
333
+ return TOKEN_PATTERN.test(text) ? text : 'na'
334
+ }
335
+
336
+ /**
337
+ * Encode the evaluation into ONE telemetry reason token (the sink's allowlist
338
+ * has no slot for structured fields, and that is its strength): e.g.
339
+ * `q-7-review-yes`, `q-na-review-na`. Always a bounded token; a score outside
340
+ * 0..1000 or not finitely representable encodes as `na`.
341
+ */
342
+ export function encodeQualityScoreReason(input: {
343
+ readonly quality: number | null
344
+ readonly needsReview: boolean | null
345
+ }): string {
346
+ const score = input.quality === null ? 'na' : formatScoreToken(input.quality)
347
+ const review = input.needsReview === null ? 'na' : input.needsReview ? 'yes' : 'no'
348
+ const reason = `q-${score}-review-${review}`
349
+ return REASON_TOKEN.test(reason) ? reason : 'invalid-reason'
350
+ }
351
+
352
+ // ─── Tool-surface preparation (the review mode) ──────────────────────────
353
+
354
+ /**
355
+ * The review tool input's envelope: the mode selector plus the review fields.
356
+ * ANY other key — `state`, `questions`, or a smuggled content field — refuses
357
+ * the preparation, so no content slot exists even at the input boundary.
358
+ */
359
+ const REVIEW_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
360
+ 'schemaVersion',
361
+ 'mode',
362
+ 'delegateId',
363
+ 'resultSummaryKind',
364
+ 'resultMetrics',
365
+ 'criteria',
366
+ ])
367
+
368
+ export type JevReviewPreparationFailure = 'REVIEW_INPUT_INVALID' | 'CRITERIA_INVALID'
369
+
370
+ export type JevReviewBuild =
371
+ | { readonly ok: true; readonly request: Omit<NativeDecisionRequest, 'model'> }
372
+ | { readonly ok: false; readonly reasonCode: JevReviewPreparationFailure }
373
+
374
+ export type JevReviewPreparation =
375
+ | { readonly ok: true; readonly request: NativeDecisionRequest }
376
+ | { readonly ok: false; readonly reasonCode: JevReviewPreparationFailure }
377
+
378
+ /**
379
+ * Validate the review tool input and build the model-less request. The
380
+ * tool-surface failure code for a malformed review is
381
+ * {@link JevReviewPreparationFailure} — `REVIEW_INPUT_INVALID` for the
382
+ * envelope and the structural fields (the review mode takes NO state text),
383
+ * `CRITERIA_INVALID` for hostile criteria, so Zeus can tell the criteria are
384
+ * the problem. The casts only bridge the untyped tool input: the builder
385
+ * re-validates every field at runtime.
386
+ */
387
+ export function buildJevReviewRequest(input: unknown): JevReviewBuild {
388
+ if (!isRecord(input)) return { ok: false, reasonCode: 'REVIEW_INPUT_INVALID' }
389
+ for (const key of Object.keys(input)) {
390
+ if (!REVIEW_ENVELOPE_KEYS.has(key)) return { ok: false, reasonCode: 'REVIEW_INPUT_INVALID' }
391
+ }
392
+ // A MISSING review field is a malformed review (REVIEW_INPUT_INVALID); a
393
+ // PRESENT-but-hostile criteria array keeps its precise CRITERIA_INVALID.
394
+ for (const key of ['delegateId', 'resultSummaryKind', 'resultMetrics', 'criteria']) {
395
+ if (input[key] === undefined) return { ok: false, reasonCode: 'REVIEW_INPUT_INVALID' }
396
+ }
397
+ const built = buildQualityScoreRequest({
398
+ delegateId: input.delegateId as string,
399
+ resultSummaryKind: input.resultSummaryKind as QualityScoreResultKind,
400
+ resultMetrics: input.resultMetrics as QualityScoreRequestInput['resultMetrics'],
401
+ criteria: input.criteria as readonly string[],
402
+ })
403
+ if (!built.ok) {
404
+ return {
405
+ ok: false,
406
+ reasonCode:
407
+ built.reasonCode === 'CRITERIA_INVALID' ? 'CRITERIA_INVALID' : 'REVIEW_INPUT_INVALID',
408
+ }
409
+ }
410
+ return { ok: true, request: built.request }
411
+ }
412
+
413
+ /**
414
+ * Prepare the review request — the `prepareJevPresetRequest` contract: the
415
+ * resolved route plus the tool input in, the bounded `NativeDecisionRequest`
416
+ * (model attached) or a structured failure out.
417
+ */
418
+ export function prepareJevReviewRequest(
419
+ route: ResolvedNativeDecisionRoute,
420
+ input: unknown,
421
+ ): JevReviewPreparation {
422
+ const built = buildJevReviewRequest(input)
423
+ if (!built.ok) return built
424
+ return {
425
+ ok: true,
426
+ request: {
427
+ model: route.model,
428
+ input: built.request.input,
429
+ questions: built.request.questions,
430
+ },
431
+ }
432
+ }