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.
Files changed (68) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +34 -60
  3. package/README.pt-BR.md +10 -12
  4. package/bin/pantheon-init.mjs +22 -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/zeus.md +4 -2
  17. package/src/pantheon/jev-decision-tool.ts +366 -114
  18. package/src/pantheon/jev-decisions.ts +11 -13
  19. package/src/pantheon/jev-escalation.ts +639 -0
  20. package/src/pantheon/jev-quality-score.ts +432 -0
  21. package/src/pantheon/jev-risk-gate.ts +479 -0
  22. package/src/pantheon/local-decision-prompt.ts +12 -18
  23. package/src/pantheon/v2-decision-telemetry.ts +14 -4
  24. package/src/pantheon/v2-native-decisions.ts +1 -1
  25. package/src/plugin-v2.ts +201 -24
  26. package/src/plugins/tui/dist/server-v2.d.ts +19 -11
  27. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  28. package/src/plugins/tui/dist/server-v2.js +19 -789
  29. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  30. package/src/plugins/tui/dist/tui-v2.d.ts +12 -331
  31. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  32. package/src/plugins/tui/dist/tui-v2.js +257 -5370
  33. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  34. package/src/plugins/tui/dist/tui.js +1 -1
  35. package/src/plugins/tui/package-lock.json +2 -2
  36. package/src/plugins/tui/package.json +1 -1
  37. package/src/plugins/tui/src/index-v2.tsx +213 -86
  38. package/src/plugins/tui/src/server-v2.ts +18 -982
  39. package/src/plugins/tui/tsconfig.typecheck.json +1 -6
  40. package/src/plugins/tui/tsdown.config.ts +1 -11
  41. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js +0 -749
  42. package/src/plugins/tui/dist/cost-data-CCZUs1aJ.js.map +0 -1
  43. package/src/plugins/tui/dist/quota-adapters.d.ts +0 -89
  44. package/src/plugins/tui/dist/quota-adapters.d.ts.map +0 -1
  45. package/src/plugins/tui/dist/quota-adapters.js +0 -1142
  46. package/src/plugins/tui/dist/quota-adapters.js.map +0 -1
  47. package/src/plugins/tui/dist/quota-cli.d.ts +0 -17
  48. package/src/plugins/tui/dist/quota-cli.d.ts.map +0 -1
  49. package/src/plugins/tui/dist/quota-cli.js +0 -184
  50. package/src/plugins/tui/dist/quota-cli.js.map +0 -1
  51. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js +0 -684
  52. package/src/plugins/tui/dist/quota-rpc-DMmXBhBe.js.map +0 -1
  53. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js +0 -118
  54. package/src/plugins/tui/dist/usage-history-contract-nt1rnBPE.js.map +0 -1
  55. package/src/plugins/tui/dist/usage-history-worker.js +0 -25
  56. package/src/plugins/tui/dist/usage-history-worker.js.map +0 -1
  57. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +0 -100
  58. package/src/plugins/tui/src/go-key-diagnostic.ts +0 -125
  59. package/src/plugins/tui/src/quota-adapters.ts +0 -1598
  60. package/src/plugins/tui/src/quota-cli.ts +0 -237
  61. package/src/plugins/tui/src/quota-rpc.ts +0 -373
  62. package/src/plugins/tui/src/quota-v2-model.ts +0 -1032
  63. package/src/plugins/tui/src/quota-v2.tsx +0 -1238
  64. package/src/plugins/tui/src/usage-history-contract.ts +0 -217
  65. package/src/plugins/tui/src/usage-history-validation.ts +0 -104
  66. package/src/plugins/tui/src/usage-history-view.tsx +0 -236
  67. package/src/plugins/tui/src/usage-history-worker.ts +0 -25
  68. package/src/plugins/tui/src/usage-view-model.ts +0 -272
@@ -0,0 +1,639 @@
1
+ /**
2
+ * J3 turn-complexity escalation — shadow classification of delegate dispatches
3
+ * through the native Jev route, with an explicit, separately-reviewed
4
+ * activation mechanism.
5
+ *
6
+ * When `PANTHEON_J3_ESCALATION` is enabled, the plugin's `execute.before` hook
7
+ * fires ONE bounded native Jev decision per delegate dispatch (the native
8
+ * `subagent` tool assembling the Brief) through {@link runGatedNativeJevCall}
9
+ * — the SAME gate chain `pantheon_jev_decide` runs (user-level config, egress
10
+ * consent, budget-ledger reservation, the host permission kill-switch on
11
+ * `decision.egress`) — and records the verdict as a shadow record into the
12
+ * decision telemetry sink.
13
+ *
14
+ * ## Shadow contract
15
+ *
16
+ * In this phase the verdict NEVER changes the dispatched model. The override
17
+ * decision is computed and recorded; applying it is the separately-reviewed
18
+ * activation step. The mechanism — set the per-agent override for the delegate
19
+ * BEFORE dispatch through the existing model-override mechanism
20
+ * (`v2-model-overrides.applyV2ModelOverride`), restore the previous model
21
+ * after — is implemented in {@link applyEscalationOverride} and
22
+ * {@link clearEscalationOverride}, and the shadow observer has NO path to
23
+ * them: its options carry no agent draft and its body never calls them. The
24
+ * mechanism is proved by direct exercise in tests only. The cheap target is a
25
+ * compile-time constant ({@link J3_ESCALATION_CHEAP_MODEL}) validated by the
26
+ * same capability table the override mechanism uses; decision models are NOT
27
+ * eligible targets (they are not chat models and never appear in the host
28
+ * catalog — the catalog is never consulted for any decision here).
29
+ *
30
+ * ## Rails (all local, no Jev call involved)
31
+ *
32
+ * Three independent local rails force the verdict to `main` regardless of the
33
+ * reported complexity — mirroring the hermes discipline that a wrong `cheap`
34
+ * costs task quality while a wrong `main` only costs tokens:
35
+ *
36
+ * 1. **Risk words** ({@link J3_RISK_WORDS}, exported as a fixture for tests):
37
+ * a Brief mentioning deploy/migrate/drop/delete/prod/production/payment/
38
+ * secret/credential never goes cheap. Matching is case-insensitive
39
+ * SUBSTRING match on purpose — inflections and plurals rail too, and
40
+ * over-matching biases to the safe direction.
41
+ * 2. **User-pinned model**: an explicit per-agent override for the delegate in
42
+ * the project-scoped model configuration (the same file
43
+ * `pantheon_model` writes) is never overridden. If the configuration cannot
44
+ * be read, the delegate is treated as pinned (fail-safe to main).
45
+ * 3. **Context length**: a Brief longer than {@link J3_CONTEXT_LENGTH_RAIL}
46
+ * never downgrades.
47
+ *
48
+ * ## Fail-safe policy
49
+ *
50
+ * The verdict is PURE policy ({@link escalationVerdict}): complexity at or
51
+ * below the documented threshold AND no rail tripped → `cheap`; anything else
52
+ * — including a null complexity from a malformed, refused or timed-out
53
+ * classification — → `main`. The main model is never downgraded by
54
+ * uncertainty.
55
+ *
56
+ * ## Sanitization contract (identical to J1)
57
+ *
58
+ * The decision request carries NO user content: no Brief text, no task
59
+ * description, no paths. The state text is the exact bounded template over
60
+ * four structural fields — the delegate id (accepted only as a canonical
61
+ * Pantheon agent token; anything else is `INPUT_INVALID`), the sha256 of the
62
+ * Brief text (an opaque correlation value), its character length, and the
63
+ * local risk-word boolean. The Brief text itself never leaves this machine.
64
+ *
65
+ * ## No delay, no retry, no queue
66
+ *
67
+ * The hook fires the observer without awaiting it (fire-and-observe); the
68
+ * observer bounds its own wait at {@link J3_ESCALATION_TIMEOUT_MS} with an
69
+ * AbortController and records `skip-timeout` at the deadline. In a future
70
+ * active phase the same deadline is the dispatch rule: a classification still
71
+ * in flight when the dispatch resolves the model is `main` — dispatch is never
72
+ * delayed. Exactly one call is ever fired: no retry, no queue.
73
+ *
74
+ * @module jev-escalation
75
+ */
76
+
77
+ import { createHash } from 'node:crypto'
78
+ import { type GatedNativeJevRuntime, runGatedNativeJevCall } from './jev-decision-tool.ts'
79
+ import { consumeJevDecisionResult } from './jev-decisions.ts'
80
+ import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
81
+ import { observeShadow, type ShadowSink } from './v2-decision-shadow.ts'
82
+ import { PANTHEON_AGENTS } from './v2-delegation-enforce.ts'
83
+ import { applyV2ModelOverride, readV2ModelConfiguration } from './v2-model-overrides.ts'
84
+ import type { NativeDecisionRequest } from './v2-native-decisions.ts'
85
+
86
+ /** On/off switch read by the plugin wiring. Any other value means off. */
87
+ export const J3_ESCALATION_FLAG_ENV = 'PANTHEON_J3_ESCALATION'
88
+
89
+ /** Telemetry point id for the turn-complexity escalation (J-series). */
90
+ export const J3_ESCALATION_POINT = 'J3'
91
+
92
+ /** Wall-clock bound for one classification. The hook never waits on it. */
93
+ export const J3_ESCALATION_TIMEOUT_MS = 2_000
94
+
95
+ /** Question name of the prepared score question, matched on consumption. */
96
+ export const ESCALATION_QUESTION_NAME = 'complexity'
97
+
98
+ /** Score levels offered to the host: the full 2..10 question bound. */
99
+ export const J3_COMPLEXITY_LEVEL_COUNT = 9
100
+
101
+ /**
102
+ * The cheap threshold — the ONE documented policy knob of the verdict.
103
+ *
104
+ * `complexity ≤ 4` is "confidently easy": the lower third of the offered
105
+ * 9-level scale (1 trivial … 9 sprawling). Deliberately conservative because
106
+ * the failure modes are asymmetric — a wrong `cheap` sends a heavyweight
107
+ * delegation to a weak model (task quality lost), while a wrong `main` only
108
+ * costs tokens. This encodes the reference design's sticky-cheap bias: the
109
+ * classifier must be CONFIDENT before anything goes cheap, and everything
110
+ * else — including every unsure, malformed or timed-out answer — stays on the
111
+ * main model.
112
+ */
113
+ export const J3_ESCALATION_CHEAP_THRESHOLD = 4
114
+
115
+ /**
116
+ * The context-length rail: a Brief longer than this is never downgraded, no
117
+ * matter the score. 8,000 chars (~2/3 of the 12,000-char state bound of
118
+ * `pantheon_jev_decide`) is the documented conservative line — routine briefs
119
+ * sit far below it, and anything near the state ceiling is by construction
120
+ * heavyweight work.
121
+ */
122
+ export const J3_CONTEXT_LENGTH_RAIL = 8_000
123
+
124
+ /**
125
+ * The risk-word fixture (also the runtime word list). Words whose presence in
126
+ * the Brief forces the verdict to `main` regardless of the reported score.
127
+ * Exported so tests exercise exactly the list the policy ships with.
128
+ */
129
+ export const J3_RISK_WORDS: readonly string[] = Object.freeze([
130
+ 'deploy',
131
+ 'migrate',
132
+ 'drop',
133
+ 'delete',
134
+ 'prod',
135
+ 'production',
136
+ 'payment',
137
+ 'secret',
138
+ 'credential',
139
+ ])
140
+
141
+ /**
142
+ * The model a `cheap` verdict dispatches to at activation time. A compile-time
143
+ * constant, NOT a catalog lookup: decision models are not chat models and
144
+ * never appear in `model.list()`, so no decision here ever consults the
145
+ * catalog. `opencode/mimo-v2.6-flash` is the OpenCode Zen free tier's current
146
+ * low-effort model — validated through the same capability table
147
+ * (`presets.capabilityEntry`) the override mechanism applies, which is what
148
+ * makes the override a real, resolvable model choice.
149
+ */
150
+ export const J3_ESCALATION_CHEAP_MODEL = 'opencode/mimo-v2.6-flash'
151
+
152
+ /** Bound for the composed state text (the template is ~320 chars). */
153
+ export const J3_ESCALATION_STATE_MAX_LENGTH = 512
154
+
155
+ const FLAG_ON = new Set(['1', 'on', 'true'])
156
+ const TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
157
+ const SHA256_HEX = /^[0-9a-f]{64}$/
158
+ /** Largest state_chars printed into the template (8 digits). */
159
+ const STATE_LENGTH_MAX = 100_000_000
160
+
161
+ /** Whether the operator explicitly enabled the flag. Absence means off. */
162
+ export function j3EscalationEnabledFromEnv(
163
+ env: Record<string, string | undefined> = process.env,
164
+ ): boolean {
165
+ const raw = (env[J3_ESCALATION_FLAG_ENV] ?? '').trim().toLowerCase()
166
+ return FLAG_ON.has(raw)
167
+ }
168
+
169
+ function isRecord(value: unknown): value is Record<string, unknown> {
170
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
171
+ }
172
+
173
+ /**
174
+ * Whether one Brief text trips the risk-word rail. Case-insensitive substring
175
+ * matching is deliberate: inflections and plurals ('redeployment', 'secrets',
176
+ * 'payments') rail too, and over-matching biases to `main` — the safe
177
+ * direction for a downgrade decision.
178
+ */
179
+ export function containsRiskWord(briefText: unknown): boolean {
180
+ if (typeof briefText !== 'string' || briefText.length === 0) return false
181
+ const haystack = briefText.toLowerCase()
182
+ return J3_RISK_WORDS.some((word) => haystack.includes(word))
183
+ }
184
+
185
+ /**
186
+ * The delegate target of a native `subagent` dispatch event: the canonical
187
+ * lowercase agent id, or `undefined` for anything else (wrong tool, malformed
188
+ * input, non-canonical target). Mirrors the origin registry's own target
189
+ * validation so the observer and the delegation policy agree on what a
190
+ * dispatch is.
191
+ */
192
+ export function subagentDispatchTarget(event: unknown): string | undefined {
193
+ if (!isRecord(event)) return undefined
194
+ if (event.tool !== 'subagent') return undefined
195
+ const input = event.input
196
+ if (!isRecord(input)) return undefined
197
+ const agent = input.agent
198
+ if (typeof agent !== 'string') return undefined
199
+ const normalized = agent.trim().toLowerCase()
200
+ return PANTHEON_AGENTS.has(normalized) ? normalized : undefined
201
+ }
202
+
203
+ /** Whether one event is a delegate dispatch the observer may classify. */
204
+ export function isSubagentDispatchEvent(event: unknown): boolean {
205
+ return subagentDispatchTarget(event) !== undefined
206
+ }
207
+
208
+ /**
209
+ * Extract the Brief text from a dispatch input: the first non-empty string
210
+ * among the host's task-bearing fields, the raw string itself, or (nothing
211
+ * string-shaped) a serialized form of the whole input. The result is hashed,
212
+ * measured and scanned locally — it is never sent anywhere.
213
+ */
214
+ const BRIEF_TEXT_KEYS: readonly string[] = Object.freeze([
215
+ 'prompt',
216
+ 'description',
217
+ 'message',
218
+ 'task',
219
+ 'instructions',
220
+ ])
221
+
222
+ function serializeBrief(brief: unknown): string {
223
+ if (typeof brief === 'string') return brief
224
+ try {
225
+ const json = JSON.stringify(brief)
226
+ return json === undefined ? String(brief) : json
227
+ } catch {
228
+ return 'unserializable-subagent-brief'
229
+ }
230
+ }
231
+
232
+ export function extractBriefText(input: unknown): string {
233
+ if (typeof input === 'string') return input
234
+ if (isRecord(input)) {
235
+ for (const key of BRIEF_TEXT_KEYS) {
236
+ const value = input[key]
237
+ if (typeof value === 'string' && value.length > 0) return value
238
+ }
239
+ }
240
+ return serializeBrief(input)
241
+ }
242
+
243
+ export type EscalationRequestFailure = 'INPUT_INVALID'
244
+
245
+ export type EscalationPreparedRequest =
246
+ | {
247
+ readonly ok: true
248
+ /** The request body; the caller attaches the resolved route's `model`. */
249
+ readonly request: Omit<NativeDecisionRequest, 'model'>
250
+ }
251
+ | { readonly ok: false; readonly reasonCode: EscalationRequestFailure }
252
+
253
+ const COMPLEXITY_LABELS = [
254
+ 'trivial',
255
+ 'simple',
256
+ 'routine',
257
+ 'moderate',
258
+ 'involved',
259
+ 'complex',
260
+ 'heavy',
261
+ 'critical',
262
+ 'sprawling',
263
+ ] as const
264
+
265
+ const COMPLEXITY_LEVELS = Object.freeze(
266
+ Array.from({ length: J3_COMPLEXITY_LEVEL_COUNT }, (_, index) => {
267
+ return Object.freeze({ label: COMPLEXITY_LABELS[index] ?? `level-${index}` })
268
+ }),
269
+ )
270
+
271
+ const COMPLEXITY_INSTRUCTIONS =
272
+ 'Rate how complex this delegated dispatch is for the specialist agent, judging from the ' +
273
+ 'structural hints in the state (dispatch size and risk markers): routine and self-contained ' +
274
+ 'at the low end, broad multi-step work at the high end. Advisory only; nothing is enforced.'
275
+
276
+ const QUESTIONS = Object.freeze([
277
+ Object.freeze({
278
+ type: 'score' as const,
279
+ name: ESCALATION_QUESTION_NAME,
280
+ instructions: COMPLEXITY_INSTRUCTIONS,
281
+ levels: COMPLEXITY_LEVELS,
282
+ }),
283
+ ])
284
+
285
+ /**
286
+ * Build the bounded classification request — the sanitization contract made
287
+ * structural. The state is the exact template over the four admitted fields;
288
+ * the delegate id must already be a canonical Pantheon agent token (paths,
289
+ * metacharacters, prose and unknown agents are `INPUT_INVALID`, never
290
+ * sanitized on the way in); the hash must be lowercase sha256 hex; the length
291
+ * a bounded non-negative integer; the risk flag a boolean. ONE score question
292
+ * only. No file parts, no JSON parts, no extra fields.
293
+ */
294
+ export function classifyTurnComplexity(request: {
295
+ readonly stateHash: string
296
+ readonly stateLength: number
297
+ readonly hasRiskWord: boolean
298
+ readonly delegateId: string
299
+ }): EscalationPreparedRequest {
300
+ const input = isRecord(request) ? request : undefined
301
+ const delegateId = input?.delegateId
302
+ if (
303
+ typeof delegateId !== 'string' ||
304
+ !TOKEN_PATTERN.test(delegateId) ||
305
+ !PANTHEON_AGENTS.has(delegateId)
306
+ ) {
307
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
308
+ }
309
+ const stateHash = input?.stateHash
310
+ if (typeof stateHash !== 'string' || !SHA256_HEX.test(stateHash)) {
311
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
312
+ }
313
+ const stateLength = input?.stateLength
314
+ if (
315
+ typeof stateLength !== 'number' ||
316
+ !Number.isInteger(stateLength) ||
317
+ stateLength < 0 ||
318
+ stateLength > STATE_LENGTH_MAX
319
+ ) {
320
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
321
+ }
322
+ const hasRiskWord = input?.hasRiskWord
323
+ if (typeof hasRiskWord !== 'boolean') {
324
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
325
+ }
326
+ const state =
327
+ 'Advisory complexity probe for one delegated dispatch. ' +
328
+ `delegate: ${delegateId}. state_sha256: ${stateHash}. state_chars: ${stateLength}. ` +
329
+ `risk_word_present: ${hasRiskWord ? 'yes' : 'no'}. ` +
330
+ 'The request carries no task content; the Brief text never leaves this machine; ' +
331
+ 'judge from the structural fields alone.'
332
+ if (state.length > J3_ESCALATION_STATE_MAX_LENGTH) {
333
+ return { ok: false, reasonCode: 'INPUT_INVALID' }
334
+ }
335
+ return {
336
+ ok: true,
337
+ request: Object.freeze({
338
+ input: Object.freeze([Object.freeze({ type: 'text' as const, text: state })]),
339
+ questions: QUESTIONS,
340
+ }),
341
+ }
342
+ }
343
+
344
+ export interface EscalationEvaluation {
345
+ /**
346
+ * The host's score for the `complexity` question; `null` when the answer is
347
+ * missing, mistyped, duplicated or an error. A raw ordinal on the prepared
348
+ * scale, not a probability.
349
+ */
350
+ readonly complexity: number | null
351
+ }
352
+
353
+ /**
354
+ * Consume a host Decisions response against the prepared request.
355
+ *
356
+ * Validation is strict and borrowed wholesale from the tool's own consumer
357
+ * (`consumeJevDecisionResult`): the answer counts only when its name and type
358
+ * match the prepared question, the score is a non-negative finite number, and
359
+ * duplicates become errors. Anything else — and any unknown response shape —
360
+ * is `null`, never a guess. Extra fields on answers never cross into the
361
+ * evaluation.
362
+ */
363
+ export function evaluateEscalationDecision(
364
+ response: unknown,
365
+ request: NativeDecisionRequest,
366
+ ): EscalationEvaluation {
367
+ const advice = consumeJevDecisionResult(response, request)
368
+ let complexity: number | null = null
369
+ for (const answer of advice.answers) {
370
+ if (answer.type === 'error') continue
371
+ if (answer.type === 'score' && answer.name === ESCALATION_QUESTION_NAME) {
372
+ complexity = answer.score ?? null
373
+ }
374
+ }
375
+ return { complexity }
376
+ }
377
+
378
+ export type EscalationVerdict = 'cheap' | 'main'
379
+
380
+ /** The three local rails, computed by the caller before the verdict. */
381
+ export interface EscalationRails {
382
+ readonly hasRiskWord: boolean
383
+ readonly pinnedModel: boolean
384
+ readonly stateLength: number
385
+ }
386
+
387
+ /**
388
+ * The PURE policy. Any rail tripped → `main`, regardless of the score (risk
389
+ * words never cheap, pinned models never overridden, large context never
390
+ * downgrades). A null complexity — unsure, malformed, refused, timed out — is
391
+ * `main`: the main model is never downgraded by uncertainty. Otherwise
392
+ * `complexity ≤ J3_ESCALATION_CHEAP_THRESHOLD` (inclusive) is `cheap` and
393
+ * everything above is `main`.
394
+ */
395
+ export function escalationVerdict(input: {
396
+ readonly complexity: number | null
397
+ readonly rails: EscalationRails
398
+ }): EscalationVerdict {
399
+ if (input.complexity === null) return 'main'
400
+ if (input.rails.hasRiskWord) return 'main'
401
+ if (input.rails.pinnedModel) return 'main'
402
+ if (input.rails.stateLength > J3_CONTEXT_LENGTH_RAIL) return 'main'
403
+ return input.complexity <= J3_ESCALATION_CHEAP_THRESHOLD ? 'cheap' : 'main'
404
+ }
405
+
406
+ const REASON_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
407
+
408
+ function formatScoreToken(value: number): string {
409
+ if (!Number.isFinite(value) || value < 0 || value > 1000) return 'na'
410
+ const text = String(Math.round(value * 100) / 100)
411
+ return TOKEN_PATTERN.test(text) ? text : 'na'
412
+ }
413
+
414
+ /**
415
+ * Encode the verdict into ONE telemetry reason token (the sink's allowlist has
416
+ * no slot for structured fields, and that is its strength): e.g.
417
+ * `esc-cheap-c2`, `esc-main-c7`, `esc-main-c-na`. Always a bounded
418
+ * `[A-Za-z0-9._:-]` token; a score outside 0..1000 or not finitely
419
+ * representable encodes as `c-na`.
420
+ */
421
+ export function encodeEscalationReason(input: {
422
+ readonly verdict: EscalationVerdict | null
423
+ readonly complexity: number | null
424
+ }): string {
425
+ const verdict = input.verdict === 'cheap' ? 'esc-cheap' : 'esc-main'
426
+ const score = input.complexity === null ? 'na' : formatScoreToken(input.complexity)
427
+ const reason = score === 'na' ? `${verdict}-c-na` : `${verdict}-c${score}`
428
+ return REASON_TOKEN.test(reason) ? reason : 'invalid-reason'
429
+ }
430
+
431
+ // ─── The activation mechanism (NOT reachable from the shadow path) ──────
432
+
433
+ /**
434
+ * One applied escalation override: the agent it was set on and the model that
435
+ * was there before, so the caller can restore it after the dispatch resolved.
436
+ */
437
+ export interface EscalationOverrideHandle {
438
+ readonly agentId: string
439
+ readonly previousModel: unknown
440
+ }
441
+
442
+ /**
443
+ * The ACTIVATION mechanism — never called by the shadow observer. Rides the
444
+ * existing per-agent model-override mechanism
445
+ * (`v2-model-overrides.applyV2ModelOverride`): for a `cheap` verdict, sets the
446
+ * delegate's model to {@link J3_ESCALATION_CHEAP_MODEL} on the agent draft
447
+ * BEFORE dispatch, exactly the way a project preset or `pantheon_model` does,
448
+ * and returns a handle carrying the previous model. Any other verdict — and
449
+ * any agent the override mechanism refuses (unknown id, unsupported model) —
450
+ * touches nothing and returns no handle. The parent model is never touched:
451
+ * the override applies only to the delegate's own draft entry.
452
+ */
453
+ export function applyEscalationOverride(
454
+ agent: { readonly id: string; model?: unknown },
455
+ verdict: EscalationVerdict | undefined,
456
+ ): EscalationOverrideHandle | undefined {
457
+ if (verdict !== 'cheap') return undefined
458
+ if (agent === null || typeof agent !== 'object') return undefined
459
+ const previousModel = agent.model
460
+ applyV2ModelOverride(agent, { model: J3_ESCALATION_CHEAP_MODEL })
461
+ // The mechanism refuses unknown agents and unsupported models by leaving
462
+ // the draft untouched; only a real application returns a handle.
463
+ if (agent.model === previousModel) return undefined
464
+ return { agentId: agent.id, previousModel }
465
+ }
466
+
467
+ /**
468
+ * The clear half of the activation mechanism: restore the model the delegate
469
+ * had before {@link applyEscalationOverride} ran. A mismatched or absent
470
+ * handle is a no-op, so a stale handle can never clobber another agent.
471
+ */
472
+ export function clearEscalationOverride(
473
+ agent: { readonly id: string; model?: unknown },
474
+ handle: EscalationOverrideHandle | undefined,
475
+ ): void {
476
+ if (handle === undefined) return
477
+ if (agent === null || typeof agent !== 'object') return
478
+ if (agent.id !== handle.agentId) return
479
+ agent.model = handle.previousModel
480
+ }
481
+
482
+ /**
483
+ * Whether the user pinned a model for the delegate in the project-scoped
484
+ * model configuration (the same file `pantheon_model` writes and the agent
485
+ * transform reads). A configuration that cannot be read counts as pinned —
486
+ * fail-safe to main, never cheap on uncertainty.
487
+ */
488
+ function defaultIsPinnedModel(delegateId: string): boolean {
489
+ try {
490
+ const configuration = readV2ModelConfiguration()
491
+ return Object.hasOwn(configuration.overrides, delegateId)
492
+ } catch {
493
+ return true
494
+ }
495
+ }
496
+
497
+ /** The `execute.before` fields the observer reads; `input` is hashed, never sent. */
498
+ interface J3SubagentEvent {
499
+ tool?: unknown
500
+ sessionID?: unknown
501
+ messageID?: unknown
502
+ agent?: unknown
503
+ input?: unknown
504
+ }
505
+
506
+ export interface J3EscalationObserverOptions {
507
+ /** The same runtime the `pantheon_jev_decide` tool uses. */
508
+ readonly runtime: GatedNativeJevRuntime
509
+ /** Shadow-record sink (the plugin wraps it with the telemetry mode). */
510
+ readonly sink?: ShadowSink
511
+ readonly timeoutMs?: number
512
+ /**
513
+ * The pinned-model rail. Defaults to the project-scoped model-override
514
+ * reader; tests inject the seam.
515
+ */
516
+ readonly isPinnedModel?: (delegateId: string) => boolean
517
+ }
518
+
519
+ function recordSkip(sink: ShadowSink | undefined, skipReason: string): void {
520
+ observeShadow(
521
+ J3_ESCALATION_POINT,
522
+ skipReason,
523
+ () => ({
524
+ decision: 'unavailable',
525
+ reason: skipReason,
526
+ }),
527
+ sink,
528
+ )
529
+ }
530
+
531
+ function abortDeadline(signal: AbortSignal): Promise<'timeout'> {
532
+ return new Promise((resolve) => {
533
+ if (signal.aborted) {
534
+ resolve('timeout')
535
+ return
536
+ }
537
+ signal.addEventListener('abort', () => resolve('timeout'), { once: true })
538
+ })
539
+ }
540
+
541
+ /**
542
+ * Create the J3 observer: one async, self-bounding classification per delegate
543
+ * dispatch. The returned function NEVER throws and NEVER records more than one
544
+ * shadow record per event; a non-dispatch or malformed event records nothing
545
+ * at all.
546
+ *
547
+ * The gate chain runs unawaited races against the deadline; on timeout the
548
+ * observer records `skip-timeout` and abandons while the abandoned chain
549
+ * settles its own ledger reservation in the background (settlement of an
550
+ * already-fired call — not a retry, and it writes no record).
551
+ *
552
+ * SHADOW CONTRACT: the verdict computed here is recorded and nothing else.
553
+ * The observer carries no agent draft, and nothing in this function or its
554
+ * options can reach {@link applyEscalationOverride} — the dispatched model
555
+ * cannot change in this phase.
556
+ */
557
+ export function createJ3EscalationObserver(
558
+ options: J3EscalationObserverOptions,
559
+ ): (event: unknown) => Promise<void> {
560
+ const timeoutMs = options.timeoutMs ?? J3_ESCALATION_TIMEOUT_MS
561
+ const sink = options.sink
562
+ const isPinnedModel = options.isPinnedModel ?? defaultIsPinnedModel
563
+ return async (event: unknown): Promise<void> => {
564
+ try {
565
+ const delegateId = subagentDispatchTarget(event)
566
+ if (delegateId === undefined) return
567
+ const payload = (event ?? {}) as J3SubagentEvent
568
+ const briefText = extractBriefText(payload.input)
569
+ const stateLength = briefText.length
570
+ const hasRiskWord = containsRiskWord(briefText)
571
+ const built = classifyTurnComplexity({
572
+ delegateId,
573
+ stateHash: createHash('sha256').update(briefText, 'utf8').digest('hex'),
574
+ stateLength,
575
+ hasRiskWord,
576
+ })
577
+ if (!built.ok) {
578
+ recordSkip(sink, 'skip-input-invalid')
579
+ return
580
+ }
581
+ const rails: EscalationRails = {
582
+ hasRiskWord,
583
+ pinnedModel: isPinnedModel(delegateId),
584
+ stateLength,
585
+ }
586
+ const controller = new AbortController()
587
+ const timer = setTimeout(() => controller.abort(), timeoutMs)
588
+ if (typeof timer === 'object' && typeof timer.unref === 'function') timer.unref()
589
+ try {
590
+ const outcome = await Promise.race([
591
+ runGatedNativeJevCall({
592
+ sessionID: payload.sessionID,
593
+ messageID: payload.messageID,
594
+ agent: typeof payload.agent === 'string' ? payload.agent : undefined,
595
+ runtime: options.runtime,
596
+ prepare: (route) => ({
597
+ ok: true as const,
598
+ request: {
599
+ model: route.model,
600
+ input: built.request.input,
601
+ questions: built.request.questions,
602
+ },
603
+ }),
604
+ }),
605
+ abortDeadline(controller.signal),
606
+ ])
607
+ if (outcome === 'timeout') {
608
+ recordSkip(sink, 'skip-timeout')
609
+ return
610
+ }
611
+ if (!outcome.ok) {
612
+ recordSkip(sink, mapGateFailureToSkipReason(outcome.reasonCode))
613
+ return
614
+ }
615
+ const evaluation = evaluateEscalationDecision(outcome.call.response, outcome.call.request)
616
+ const verdict = escalationVerdict({ complexity: evaluation.complexity, rails })
617
+ observeShadow(
618
+ J3_ESCALATION_POINT,
619
+ evaluation,
620
+ (isolated) => ({
621
+ decision: 'observe',
622
+ reason: encodeEscalationReason({
623
+ verdict,
624
+ complexity: (isolated as EscalationEvaluation).complexity,
625
+ }),
626
+ }),
627
+ sink,
628
+ )
629
+ } finally {
630
+ clearTimeout(timer)
631
+ }
632
+ } catch {
633
+ // Fail-open: the gate chain rejects only when the budget ledger cannot
634
+ // be opened; any other unexpected failure lands here too. One skip
635
+ // record, no detail, no propagation into the dispatch.
636
+ recordSkip(sink, 'skip-gate-unavailable')
637
+ }
638
+ }
639
+ }