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,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
|
+
}
|