pantheon-opencode 1.6.2-beta.9 → 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.
- package/CHANGELOG.md +101 -0
- package/README.md +34 -60
- package/README.pt-BR.md +10 -12
- package/bin/pantheon-init.mjs +22 -32
- package/package.json +3 -3
- package/plugin.json +1 -1
- package/pyproject.toml +1 -1
- package/scripts/decision-router.mjs +41 -56
- package/scripts/install/decision-router-config.mjs +67 -1
- package/scripts/install/npx-cache-sweep.mjs +103 -0
- package/scripts/install/opencode.mjs +7 -7
- package/scripts/install/plugin.mjs +4 -3
- package/scripts/install/strings.mjs +4 -0
- package/scripts/release-gates.mjs +6 -82
- package/scripts/sync-tui.mjs +3 -3
- package/src/agents/zeus.md +4 -2
- package/src/pantheon/jev-decision-tool.ts +366 -114
- package/src/pantheon/jev-decisions.ts +11 -13
- package/src/pantheon/jev-escalation.ts +639 -0
- package/src/pantheon/jev-quality-score.ts +432 -0
- package/src/pantheon/jev-risk-gate.ts +479 -0
- package/src/pantheon/local-decision-prompt.ts +12 -18
- package/src/pantheon/v2-decision-telemetry.ts +14 -4
- package/src/pantheon/v2-native-decisions.ts +1 -1
- package/src/plugin-v2.ts +201 -24
- package/src/plugins/tui/dist/server-v2.d.ts +19 -11
- package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
- package/src/plugins/tui/dist/server-v2.js +19 -789
- package/src/plugins/tui/dist/server-v2.js.map +1 -1
- package/src/plugins/tui/dist/tui-v2.d.ts +12 -331
- package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
- package/src/plugins/tui/dist/tui-v2.js +257 -5370
- package/src/plugins/tui/dist/tui-v2.js.map +1 -1
- package/src/plugins/tui/dist/tui.js +1 -1
- package/src/plugins/tui/package-lock.json +2 -2
- package/src/plugins/tui/package.json +1 -1
- package/src/plugins/tui/src/index-v2.tsx +213 -86
- package/src/plugins/tui/src/server-v2.ts +18 -982
- package/src/plugins/tui/tsconfig.typecheck.json +1 -6
- package/src/plugins/tui/tsdown.config.ts +1 -11
- package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js +0 -749
- package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js.map +0 -1
- package/src/plugins/tui/dist/quota-adapters.d.ts +0 -89
- package/src/plugins/tui/dist/quota-adapters.d.ts.map +0 -1
- package/src/plugins/tui/dist/quota-adapters.js +0 -1142
- package/src/plugins/tui/dist/quota-adapters.js.map +0 -1
- package/src/plugins/tui/dist/quota-cli.d.ts +0 -17
- package/src/plugins/tui/dist/quota-cli.d.ts.map +0 -1
- package/src/plugins/tui/dist/quota-cli.js +0 -184
- package/src/plugins/tui/dist/quota-cli.js.map +0 -1
- package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js +0 -684
- package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js.map +0 -1
- package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js +0 -118
- package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js.map +0 -1
- package/src/plugins/tui/dist/usage-history-worker.js +0 -25
- package/src/plugins/tui/dist/usage-history-worker.js.map +0 -1
- package/src/plugins/tui/src/go-key-diagnostic-ui.ts +0 -100
- package/src/plugins/tui/src/go-key-diagnostic.ts +0 -125
- package/src/plugins/tui/src/quota-adapters.ts +0 -1598
- package/src/plugins/tui/src/quota-cli.ts +0 -237
- package/src/plugins/tui/src/quota-rpc.ts +0 -373
- package/src/plugins/tui/src/quota-v2-model.ts +0 -1032
- package/src/plugins/tui/src/quota-v2.tsx +0 -1238
- package/src/plugins/tui/src/usage-history-contract.ts +0 -217
- package/src/plugins/tui/src/usage-history-validation.ts +0 -104
- package/src/plugins/tui/src/usage-history-view.tsx +0 -236
- package/src/plugins/tui/src/usage-history-worker.ts +0 -25
- 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
|
+
}
|