pantheon-opencode 1.6.2-beta.4 → 1.6.2-beta.6
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 +27 -0
- package/README.md +202 -29
- package/README.pt-BR.md +9 -0
- package/bin/pantheon-init.mjs +6 -1
- package/package.json +2 -1
- package/plugin.json +1 -1
- package/pyproject.toml +1 -1
- package/scripts/decision-router-budget.mjs +7 -8
- package/scripts/decision-router-v2-budget.mjs +218 -0
- package/scripts/decision-router-v2-egress.mjs +272 -0
- package/scripts/decision-router.mjs +268 -46
- package/scripts/docs-check-changelog.mjs +5 -3
- package/scripts/install/decision-layer-preview.mjs +376 -0
- package/scripts/install/decision-router-config.mjs +162 -34
- package/scripts/mcp_resources.py +11 -9
- package/scripts/release-notes.mjs +30 -7
- package/scripts/versioning.mjs +41 -5
- package/src/mcp/eval_store.py +11 -4
- package/src/mcp/mcp_resources.py +11 -9
- package/src/mcp/memory_mcp.py +293 -150
- package/src/pantheon/jev-decision-tool.ts +336 -0
- package/src/pantheon/jev-decisions.ts +625 -0
- package/src/pantheon/local-decision-budget.ts +4 -1
- package/src/pantheon/local-decision-egress-gate.ts +16 -136
- package/src/pantheon/local-decision-prompt.ts +184 -45
- package/src/pantheon/local-decision-provider-matrix.ts +14 -62
- package/src/pantheon/local-decision-skills.ts +115 -5
- package/src/pantheon/local-decision-tool.ts +35 -1
- package/src/pantheon/local-decision-turn.ts +15 -252
- package/src/pantheon/local-decision-usage-evidence.internal.ts +80 -119
- package/src/pantheon/v2-decision-budget.ts +456 -0
- package/src/pantheon/v2-decision-contracts.ts +300 -0
- package/src/pantheon/v2-decision-egress.ts +203 -0
- package/src/pantheon/v2-decision-events.ts +180 -0
- package/src/pantheon/v2-decision-heuristic.ts +121 -0
- package/src/pantheon/v2-decision-points/p1-agent.ts +91 -0
- package/src/pantheon/v2-decision-points/p10-claims.ts +243 -0
- package/src/pantheon/v2-decision-points/p11-catalog.ts +220 -0
- package/src/pantheon/v2-decision-points/p2-skill.ts +83 -0
- package/src/pantheon/v2-decision-points/p3-complexity.ts +108 -0
- package/src/pantheon/v2-decision-points/p4-memory.ts +137 -0
- package/src/pantheon/v2-decision-points/p5-themis-verify.ts +190 -0
- package/src/pantheon/v2-decision-points/p6-council.ts +161 -0
- package/src/pantheon/v2-decision-points/p7-loop.ts +263 -0
- package/src/pantheon/v2-decision-points/p8-guardrail.ts +367 -0
- package/src/pantheon/v2-decision-points/p9-memory-compaction.ts +304 -0
- package/src/pantheon/v2-decision-points.ts +242 -0
- package/src/pantheon/v2-decision-policy.ts +166 -0
- package/src/pantheon/v2-decision-premises.ts +146 -0
- package/src/pantheon/v2-decision-prompt-surface.ts +115 -0
- package/src/pantheon/v2-decision-rank.ts +91 -0
- package/src/pantheon/v2-decision-registry.ts +391 -0
- package/src/pantheon/v2-decision-resource-ids.ts +127 -0
- package/src/pantheon/v2-decision-shadow.ts +123 -0
- package/src/pantheon/v2-decision-telemetry.ts +214 -0
- package/src/pantheon/v2-decision-verify.ts +51 -0
- package/src/pantheon/v2-native-decisions.ts +365 -0
- package/src/pantheon/v2-tools.ts +24 -2
- package/src/plugin-v2.ts +360 -14
- package/src/plugins/tui/dist/tui-v2.js +3 -3
- 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/pantheon/local-decision-provider-protocol.ts +0 -335
- package/src/pantheon/local-decision-provider.internal.ts +0 -260
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* V2 decision policy — deterministic selection, gates, shadow/active and budget.
|
|
3
|
+
*
|
|
4
|
+
* The policy is deliberately separate from the heuristic: it answers "may this
|
|
5
|
+
* point be evaluated at all, and in which mode?" and never inspects prompt,
|
|
6
|
+
* response or any other content. It uses no clock, no randomness and no
|
|
7
|
+
* network, so the same request always yields the same decision.
|
|
8
|
+
*
|
|
9
|
+
* This phase has no effect path. Even an admitted decision reports
|
|
10
|
+
* `effect: 'none'`; activation, any observable effect and the wiring of the
|
|
11
|
+
* points that have no production call site belong to later phases and are not
|
|
12
|
+
* implemented here.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import {
|
|
16
|
+
DECISION_POINT_IDS,
|
|
17
|
+
type DecisionPointId,
|
|
18
|
+
type DecisionPointMode,
|
|
19
|
+
type DecisionPointStatus,
|
|
20
|
+
} from './v2-decision-registry.ts'
|
|
21
|
+
|
|
22
|
+
export const DECISION_POLICY_VERSION = 'v2-decision-policy/1'
|
|
23
|
+
export const DEFAULT_DECISIONS_PER_TURN = 32
|
|
24
|
+
|
|
25
|
+
export type PolicyMode = 'shadow' | 'active'
|
|
26
|
+
|
|
27
|
+
export type PolicyDenialReason =
|
|
28
|
+
| 'UNKNOWN_POINT'
|
|
29
|
+
| 'DEFERRED_POINT'
|
|
30
|
+
| 'MIGRATION_NOT_SHADOW'
|
|
31
|
+
| 'POINT_OFF'
|
|
32
|
+
| 'GATE_CLOSED'
|
|
33
|
+
| 'ACTIVE_NOT_ALLOWED'
|
|
34
|
+
| 'BUDGET_EXHAUSTED'
|
|
35
|
+
|
|
36
|
+
export type PolicyReasonCode = 'SHADOW' | 'ACTIVE' | PolicyDenialReason
|
|
37
|
+
|
|
38
|
+
export interface DecisionBudgetSnapshot {
|
|
39
|
+
readonly maxPerTurn: number
|
|
40
|
+
readonly used: number
|
|
41
|
+
readonly remaining: number
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Per-turn decision budget. Deterministic: no clock, no persistence. */
|
|
45
|
+
export interface DecisionBudget {
|
|
46
|
+
tryConsume(): boolean
|
|
47
|
+
remaining(): number
|
|
48
|
+
resetTurn(): void
|
|
49
|
+
snapshot(): DecisionBudgetSnapshot
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export function createDecisionBudget(
|
|
53
|
+
maxPerTurn: number = DEFAULT_DECISIONS_PER_TURN,
|
|
54
|
+
): DecisionBudget {
|
|
55
|
+
if (!Number.isInteger(maxPerTurn) || maxPerTurn < 0 || maxPerTurn > 10_000) {
|
|
56
|
+
throw new RangeError('maxPerTurn must be an integer in 0..10000')
|
|
57
|
+
}
|
|
58
|
+
let used = 0
|
|
59
|
+
return {
|
|
60
|
+
tryConsume() {
|
|
61
|
+
if (used >= maxPerTurn) return false
|
|
62
|
+
used += 1
|
|
63
|
+
return true
|
|
64
|
+
},
|
|
65
|
+
remaining() {
|
|
66
|
+
return maxPerTurn - used
|
|
67
|
+
},
|
|
68
|
+
resetTurn() {
|
|
69
|
+
used = 0
|
|
70
|
+
},
|
|
71
|
+
snapshot() {
|
|
72
|
+
return Object.freeze({ maxPerTurn, used, remaining: maxPerTurn - used })
|
|
73
|
+
},
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export interface DecisionPolicyConfig {
|
|
78
|
+
/** Global mode. Defaults to shadow; `active` also requires `allowActive`. */
|
|
79
|
+
readonly mode?: PolicyMode
|
|
80
|
+
readonly allowActive?: boolean
|
|
81
|
+
readonly budget?: DecisionBudget
|
|
82
|
+
/** Condition ids (C6, C7, …) that are currently closed. */
|
|
83
|
+
readonly closedGates?: readonly string[]
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export interface DecisionPolicyRequest {
|
|
87
|
+
readonly point: string
|
|
88
|
+
readonly pointMode: DecisionPointMode
|
|
89
|
+
readonly status: DecisionPointStatus
|
|
90
|
+
readonly requiredGates?: readonly string[]
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export interface PolicyDecision {
|
|
94
|
+
readonly version: typeof DECISION_POLICY_VERSION
|
|
95
|
+
readonly point: string
|
|
96
|
+
readonly admitted: boolean
|
|
97
|
+
readonly mode: PolicyMode
|
|
98
|
+
readonly effect: 'none'
|
|
99
|
+
readonly reasonCode: PolicyReasonCode
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Whether a string names a registry point. */
|
|
103
|
+
export function isDecisionPointId(value: unknown): value is DecisionPointId {
|
|
104
|
+
return typeof value === 'string' && (DECISION_POINT_IDS as readonly string[]).includes(value)
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function deny(point: string, mode: PolicyMode, reasonCode: PolicyDenialReason): PolicyDecision {
|
|
108
|
+
return Object.freeze({
|
|
109
|
+
version: DECISION_POLICY_VERSION,
|
|
110
|
+
point,
|
|
111
|
+
admitted: false,
|
|
112
|
+
mode,
|
|
113
|
+
effect: 'none',
|
|
114
|
+
reasonCode,
|
|
115
|
+
})
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Decide whether a point may be evaluated in this turn.
|
|
120
|
+
*
|
|
121
|
+
* Order is fixed so the outcome is reproducible: unknown point, deferred
|
|
122
|
+
* status, migration mode, off mode, closed gate, activation permission, budget.
|
|
123
|
+
* `effect` is always `none` — admission is not an effect.
|
|
124
|
+
*/
|
|
125
|
+
export function evaluateDecisionPolicy(
|
|
126
|
+
config: DecisionPolicyConfig,
|
|
127
|
+
request: DecisionPolicyRequest,
|
|
128
|
+
): PolicyDecision {
|
|
129
|
+
const requestedMode: PolicyMode = config.mode === 'active' ? 'active' : 'shadow'
|
|
130
|
+
|
|
131
|
+
if (!isDecisionPointId(request.point)) {
|
|
132
|
+
return deny(request.point, requestedMode, 'UNKNOWN_POINT')
|
|
133
|
+
}
|
|
134
|
+
if (request.status === 'deferred') {
|
|
135
|
+
return deny(request.point, requestedMode, 'DEFERRED_POINT')
|
|
136
|
+
}
|
|
137
|
+
if (request.pointMode === 'migration') {
|
|
138
|
+
return deny(request.point, requestedMode, 'MIGRATION_NOT_SHADOW')
|
|
139
|
+
}
|
|
140
|
+
if (request.pointMode === 'off') {
|
|
141
|
+
return deny(request.point, requestedMode, 'POINT_OFF')
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
const closed = new Set(config.closedGates ?? [])
|
|
145
|
+
for (const gate of request.requiredGates ?? []) {
|
|
146
|
+
if (closed.has(gate)) return deny(request.point, requestedMode, 'GATE_CLOSED')
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
if (requestedMode === 'active' && config.allowActive !== true) {
|
|
150
|
+
return deny(request.point, requestedMode, 'ACTIVE_NOT_ALLOWED')
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
const budget = config.budget
|
|
154
|
+
if (budget && !budget.tryConsume()) {
|
|
155
|
+
return deny(request.point, requestedMode, 'BUDGET_EXHAUSTED')
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return Object.freeze({
|
|
159
|
+
version: DECISION_POLICY_VERSION,
|
|
160
|
+
point: request.point,
|
|
161
|
+
admitted: true,
|
|
162
|
+
mode: requestedMode,
|
|
163
|
+
effect: 'none',
|
|
164
|
+
reasonCode: requestedMode === 'active' ? 'ACTIVE' : 'SHADOW',
|
|
165
|
+
})
|
|
166
|
+
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Premise register — PM-03…PM-18 plus PRE-01/PRE-02, referenced by id from the
|
|
3
|
+
* registry. The canonical text lives in `STATUS.md` § Premissas; this file
|
|
4
|
+
* keeps the ids, their state and their blocking targets close to the audit
|
|
5
|
+
* that checks them.
|
|
6
|
+
*
|
|
7
|
+
* `status: 'closed'` means the premise was retired by a measurement, and the
|
|
8
|
+
* statement records the residual scope that measurement left open. It never
|
|
9
|
+
* means the measurement closed the *effect* question for a point that cites it.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
export interface PremiseEntry {
|
|
13
|
+
readonly id: string
|
|
14
|
+
readonly statement: string
|
|
15
|
+
readonly blocks: string
|
|
16
|
+
/** `closed` only when a named measurement retired the premise. */
|
|
17
|
+
readonly status: 'open' | 'closed'
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** PM-03…PM-18 plus PRE-01/PRE-02, referenced by id from the registry. */
|
|
21
|
+
export const PREMISE_REGISTER: readonly PremiseEntry[] = Object.freeze([
|
|
22
|
+
Object.freeze({
|
|
23
|
+
id: 'PRE-01',
|
|
24
|
+
statement:
|
|
25
|
+
'P7 by event was a premise with a negative signal until the channel form was measured; PROBE-D closed C7, and the residual `session.idle`/`session.compacted` negative signal stays measured',
|
|
26
|
+
blocks: 'nothing — historical record (C7 closed by PROBE-D)',
|
|
27
|
+
status: 'closed',
|
|
28
|
+
}),
|
|
29
|
+
Object.freeze({
|
|
30
|
+
id: 'PRE-02',
|
|
31
|
+
statement:
|
|
32
|
+
'prompt.skills absent makes filterSkills a no-op; P2 does not filter on the default path',
|
|
33
|
+
blocks: 'P2b activation (PM-07)',
|
|
34
|
+
status: 'open',
|
|
35
|
+
}),
|
|
36
|
+
Object.freeze({
|
|
37
|
+
id: 'PM-03',
|
|
38
|
+
statement: 'Origin of the Phase 0a carrier divergence is a hypothesis (2.1.4 session.id)',
|
|
39
|
+
blocks: 'nothing — historical record',
|
|
40
|
+
status: 'open',
|
|
41
|
+
}),
|
|
42
|
+
Object.freeze({
|
|
43
|
+
id: 'PM-04',
|
|
44
|
+
statement:
|
|
45
|
+
'reason:"overflow" was not inducible in 6 error shapes; child-session compaction is measured (3/3) but its checkpoint reinjection is not',
|
|
46
|
+
blocks: 'P9 / Phase 3 (C9)',
|
|
47
|
+
status: 'open',
|
|
48
|
+
}),
|
|
49
|
+
Object.freeze({
|
|
50
|
+
id: 'PM-05',
|
|
51
|
+
statement:
|
|
52
|
+
'Exclusivity of the system channel is unproven; the messages mode was never exercised',
|
|
53
|
+
blocks: 'P9 / Phase 3',
|
|
54
|
+
status: 'open',
|
|
55
|
+
}),
|
|
56
|
+
Object.freeze({
|
|
57
|
+
id: 'PM-06',
|
|
58
|
+
statement:
|
|
59
|
+
'Skill and tool catalogs with Pantheon installed were measured (F-26: ctx.skill, tool.transform draft). ctx.agent.transform was never exercised',
|
|
60
|
+
blocks: 'P11 (Phase 6) for agents only',
|
|
61
|
+
status: 'closed',
|
|
62
|
+
}),
|
|
63
|
+
Object.freeze({
|
|
64
|
+
id: 'PM-07',
|
|
65
|
+
statement: 'Populated prompt.skills / prompt.agents were never observed',
|
|
66
|
+
blocks: 'P1/P2b activation',
|
|
67
|
+
status: 'open',
|
|
68
|
+
}),
|
|
69
|
+
Object.freeze({
|
|
70
|
+
id: 'PM-08',
|
|
71
|
+
statement: 'ctx.model / ctx.provider were never exercised as a catalog source',
|
|
72
|
+
blocks: 'P11 / Phase 6',
|
|
73
|
+
status: 'open',
|
|
74
|
+
}),
|
|
75
|
+
Object.freeze({
|
|
76
|
+
id: 'PM-09',
|
|
77
|
+
statement: 'permission.evaluate and execute.before were registered but never fired',
|
|
78
|
+
blocks: 'P5/P8 (C8)',
|
|
79
|
+
status: 'open',
|
|
80
|
+
}),
|
|
81
|
+
Object.freeze({
|
|
82
|
+
id: 'PM-10',
|
|
83
|
+
statement: 'Package/venv idempotence and clean-room reproducibility were not measured',
|
|
84
|
+
blocks: 'D7 / Phase 7',
|
|
85
|
+
status: 'open',
|
|
86
|
+
}),
|
|
87
|
+
Object.freeze({
|
|
88
|
+
id: 'PM-11',
|
|
89
|
+
statement: 'The 1–8 setup multiplicity per run is unexplained and unanalysed',
|
|
90
|
+
blocks: 'P7/P9 duplication risk',
|
|
91
|
+
status: 'open',
|
|
92
|
+
}),
|
|
93
|
+
Object.freeze({
|
|
94
|
+
id: 'PM-12',
|
|
95
|
+
statement:
|
|
96
|
+
'Child/background coverage by session.execution.succeeded was not measured; closed by PROBE-D (F-18–F-21: 13/13 child sessions). Nested depth >= 2, background image jobs and execution.failed/.interrupted in a child remain unmeasured',
|
|
97
|
+
blocks: 'nothing — C7 closed by PROBE-D',
|
|
98
|
+
status: 'closed',
|
|
99
|
+
}),
|
|
100
|
+
Object.freeze({
|
|
101
|
+
id: 'PM-13',
|
|
102
|
+
statement:
|
|
103
|
+
'The installer "Change plan" is not a preview: it announces creates that do not occur',
|
|
104
|
+
blocks: 'D7 / Phase 7',
|
|
105
|
+
status: 'open',
|
|
106
|
+
}),
|
|
107
|
+
Object.freeze({
|
|
108
|
+
id: 'PM-14',
|
|
109
|
+
statement: 'Current V2 dispatch reads an envelope field absent from the measured shape (I-01)',
|
|
110
|
+
blocks: 'Phase 4 payload reading',
|
|
111
|
+
status: 'open',
|
|
112
|
+
}),
|
|
113
|
+
Object.freeze({
|
|
114
|
+
id: 'PM-15',
|
|
115
|
+
statement: 'Installer backups accumulate credential material without warning',
|
|
116
|
+
blocks: 'D7 / Phase 7',
|
|
117
|
+
status: 'open',
|
|
118
|
+
}),
|
|
119
|
+
Object.freeze({
|
|
120
|
+
id: 'PM-16',
|
|
121
|
+
statement:
|
|
122
|
+
'Honouring of the effect write is unmeasured: if the host assigns event.effect only after permission.evaluate, P8 reads no baseline, denies and never narrows — and with the result discarded, "on and inert" is indistinguishable from "on and working"',
|
|
123
|
+
blocks: 'P8 activation (C8 / PH5-1, PH5-5)',
|
|
124
|
+
status: 'open',
|
|
125
|
+
}),
|
|
126
|
+
Object.freeze({
|
|
127
|
+
id: 'PM-17',
|
|
128
|
+
statement:
|
|
129
|
+
'The 12-execution P7 cap has no measured reset surface: reset() exists but no user-input signal was wired to it, which is why the cap is advisory',
|
|
130
|
+
blocks: 'nothing today — P7 effect is none; blocks any claim about the cap',
|
|
131
|
+
status: 'open',
|
|
132
|
+
}),
|
|
133
|
+
Object.freeze({
|
|
134
|
+
id: 'PM-18',
|
|
135
|
+
statement:
|
|
136
|
+
'BM25 versus embeddings was not run (offline environment, no embedding model); BM25 stays the baseline and no gain or loss may be quoted',
|
|
137
|
+
blocks: 'any retrieval/token gain claim in P4/P11',
|
|
138
|
+
status: 'open',
|
|
139
|
+
}),
|
|
140
|
+
])
|
|
141
|
+
|
|
142
|
+
export const PREMISE_IDS = [
|
|
143
|
+
'PRE-01',
|
|
144
|
+
'PRE-02',
|
|
145
|
+
...Array.from({ length: 16 }, (_, index) => `PM-${String(index + 3).padStart(2, '0')}`),
|
|
146
|
+
] as const
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Prompt-surface shadow wiring — P1 and P2 share one hook payload.
|
|
3
|
+
*
|
|
4
|
+
* Both read the same admission event at `session.hook('prompt')`. This module
|
|
5
|
+
* constructs each adapter once per invocation and hands it a projection of the
|
|
6
|
+
* payload that contains **only** `prompt.agents` and `prompt.skills`:
|
|
7
|
+
*
|
|
8
|
+
* - prompt text, files and metadata never enter shadow, so no content can
|
|
9
|
+
* reach a shadow record or telemetry;
|
|
10
|
+
* - cloning a prompt-sized payload twice per turn would be a cost this no-op
|
|
11
|
+
* must not impose, and the invariant is "no delay".
|
|
12
|
+
*
|
|
13
|
+
* Shadow is a no-op by construction: `observeShadow` clones and freezes the
|
|
14
|
+
* projection, every record says `effect: 'none'`, and no failure — adapter,
|
|
15
|
+
* projection or sink — is rethrown into the hook. Nothing here mutates
|
|
16
|
+
* admission; in particular P2 stays advisory and the projection carries no
|
|
17
|
+
* draft list, so it can neither filter skills nor claim to.
|
|
18
|
+
*
|
|
19
|
+
* The other points once wired here are gone. P3 declares `tool.invoke` and is
|
|
20
|
+
* now constructed at the tool that actually carries `complexity` and
|
|
21
|
+
* `gateStatus` (`local-decision-tool.ts`); P6 and P10 declared this hook but
|
|
22
|
+
* this payload never carries council candidates or counsellor claims, so they
|
|
23
|
+
* are not constructed at all (`wired: false`) instead of recording a permanent
|
|
24
|
+
* refusal from a surface that cannot feed them.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
import type { SkillsSource } from './local-decision-prompt.ts'
|
|
28
|
+
import { evaluateAgentPoint } from './v2-decision-points/p1-agent.ts'
|
|
29
|
+
import { evaluateSkillPoint } from './v2-decision-points/p2-skill.ts'
|
|
30
|
+
import type { ShadowRecord, ShadowSink } from './v2-decision-shadow.ts'
|
|
31
|
+
|
|
32
|
+
/** Registry ids wired at the prompt hook by this module. */
|
|
33
|
+
export const PROMPT_SURFACE_POINT_IDS = Object.freeze(['P1', 'P2'] as const)
|
|
34
|
+
|
|
35
|
+
/** Registry mode every point above declares; telemetry must carry it. */
|
|
36
|
+
export const PROMPT_SURFACE_MODE = 'shadow' as const
|
|
37
|
+
|
|
38
|
+
export interface PromptSurfaceObservation {
|
|
39
|
+
readonly records: readonly ShadowRecord[]
|
|
40
|
+
/** P2a observation only: which source the skill list came from, and why. */
|
|
41
|
+
readonly skills: {
|
|
42
|
+
readonly skillsSource: SkillsSource
|
|
43
|
+
readonly reason: string
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface PromptSurfacePayload {
|
|
48
|
+
readonly prompt?: Readonly<Record<string, unknown>>
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const PROJECTED_PROMPT_KEYS = ['agents', 'skills'] as const
|
|
52
|
+
|
|
53
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
54
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Project the admission payload down to the fields the adapters may read.
|
|
59
|
+
*
|
|
60
|
+
* Exported so the no-op test can prove the projection carries no prompt text,
|
|
61
|
+
* no file bytes and no metadata.
|
|
62
|
+
*/
|
|
63
|
+
export function projectPromptSurfacePayload(admission: unknown): PromptSurfacePayload {
|
|
64
|
+
if (!isRecord(admission) || !isRecord(admission.prompt)) return {}
|
|
65
|
+
const prompt = admission.prompt
|
|
66
|
+
const projected: Record<string, unknown> = {}
|
|
67
|
+
for (const key of PROJECTED_PROMPT_KEYS) {
|
|
68
|
+
if (Object.hasOwn(prompt, key)) projected[key] = prompt[key]
|
|
69
|
+
}
|
|
70
|
+
return Object.freeze({ prompt: Object.freeze(projected) })
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Observe the two prompt-surface points in shadow.
|
|
75
|
+
*
|
|
76
|
+
* @param admission Host admission payload. Read only; never mutated.
|
|
77
|
+
* @param sink Optional observer of the shadow records.
|
|
78
|
+
*/
|
|
79
|
+
export function observePromptSurface(
|
|
80
|
+
admission: unknown,
|
|
81
|
+
sink?: ShadowSink,
|
|
82
|
+
): PromptSurfaceObservation {
|
|
83
|
+
const payload = projectPromptSurfacePayload(admission)
|
|
84
|
+
const records: ShadowRecord[] = []
|
|
85
|
+
const collect: ShadowSink = (record) => {
|
|
86
|
+
records.push(record)
|
|
87
|
+
if (sink === undefined) return
|
|
88
|
+
try {
|
|
89
|
+
sink(record)
|
|
90
|
+
} catch {
|
|
91
|
+
// An observer failure must not become an admission failure.
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
let skills: PromptSurfaceObservation['skills'] = {
|
|
96
|
+
skillsSource: 'none',
|
|
97
|
+
reason: 'decision_error',
|
|
98
|
+
}
|
|
99
|
+
const observers: readonly (() => void)[] = [
|
|
100
|
+
() => evaluateAgentPoint(payload, collect),
|
|
101
|
+
() => {
|
|
102
|
+
const skillPoint = evaluateSkillPoint(payload, collect)
|
|
103
|
+
skills = { skillsSource: skillPoint.skillsSource, reason: skillPoint.reason }
|
|
104
|
+
},
|
|
105
|
+
]
|
|
106
|
+
for (const observe of observers) {
|
|
107
|
+
try {
|
|
108
|
+
observe()
|
|
109
|
+
} catch {
|
|
110
|
+
// One point's failure must not silence the other.
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
return { records: Object.freeze(records), skills }
|
|
115
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* V2 ranking contract — deterministic order with per-item justification.
|
|
3
|
+
*
|
|
4
|
+
* Score descending, then id ascending, so the same candidates always produce
|
|
5
|
+
* the same order. The output is plain JSON-serialisable data.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
|
|
9
|
+
|
|
10
|
+
export interface RankCandidate {
|
|
11
|
+
readonly id: string
|
|
12
|
+
readonly score: number
|
|
13
|
+
readonly justification: string
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface RankedCandidate extends RankCandidate {
|
|
17
|
+
readonly rank: number
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export type RankFailure =
|
|
21
|
+
| 'NO_CANDIDATES'
|
|
22
|
+
| 'INVALID_SHAPE'
|
|
23
|
+
| 'DUPLICATE_ID'
|
|
24
|
+
| 'INVALID_ID'
|
|
25
|
+
| 'INVALID_SCORE'
|
|
26
|
+
| 'MISSING_JUSTIFICATION'
|
|
27
|
+
|
|
28
|
+
export type RankResult =
|
|
29
|
+
| { readonly ok: true; readonly ordered: readonly RankedCandidate[] }
|
|
30
|
+
| { readonly ok: false; readonly code: RankFailure; readonly detail: string }
|
|
31
|
+
|
|
32
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
33
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function isNonEmptyString(value: unknown): value is string {
|
|
37
|
+
return typeof value === 'string' && value.trim().length > 0
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function isToken(value: unknown): value is string {
|
|
41
|
+
return typeof value === 'string' && TOKEN.test(value)
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Rank candidates deterministically: score descending, then id ascending.
|
|
46
|
+
* Every candidate carries its own justification; ties are stable and therefore
|
|
47
|
+
* replayable by the harness.
|
|
48
|
+
*/
|
|
49
|
+
export function rankCandidates(candidates: unknown): RankResult {
|
|
50
|
+
if (!Array.isArray(candidates)) {
|
|
51
|
+
return { ok: false, code: 'INVALID_SHAPE', detail: 'candidates must be an array' }
|
|
52
|
+
}
|
|
53
|
+
if (candidates.length === 0) {
|
|
54
|
+
return { ok: false, code: 'NO_CANDIDATES', detail: 'at least one candidate is required' }
|
|
55
|
+
}
|
|
56
|
+
const ids = new Set<string>()
|
|
57
|
+
const valid: RankCandidate[] = []
|
|
58
|
+
for (const candidate of candidates) {
|
|
59
|
+
if (!isRecord(candidate)) {
|
|
60
|
+
return { ok: false, code: 'INVALID_SHAPE', detail: 'candidate must be an object' }
|
|
61
|
+
}
|
|
62
|
+
if (!isToken(candidate.id)) {
|
|
63
|
+
return { ok: false, code: 'INVALID_ID', detail: 'candidate id must be a short token' }
|
|
64
|
+
}
|
|
65
|
+
if (ids.has(candidate.id)) {
|
|
66
|
+
return { ok: false, code: 'DUPLICATE_ID', detail: 'candidate ids must be unique' }
|
|
67
|
+
}
|
|
68
|
+
ids.add(candidate.id)
|
|
69
|
+
if (typeof candidate.score !== 'number' || !Number.isFinite(candidate.score)) {
|
|
70
|
+
return { ok: false, code: 'INVALID_SCORE', detail: 'score must be a finite number' }
|
|
71
|
+
}
|
|
72
|
+
if (!isNonEmptyString(candidate.justification)) {
|
|
73
|
+
return {
|
|
74
|
+
ok: false,
|
|
75
|
+
code: 'MISSING_JUSTIFICATION',
|
|
76
|
+
detail: 'every candidate needs a justification',
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
valid.push({
|
|
80
|
+
id: candidate.id,
|
|
81
|
+
score: candidate.score,
|
|
82
|
+
justification: candidate.justification,
|
|
83
|
+
})
|
|
84
|
+
}
|
|
85
|
+
const sorted = [...valid].sort((left, right) => {
|
|
86
|
+
if (right.score !== left.score) return right.score - left.score
|
|
87
|
+
return left.id < right.id ? -1 : left.id > right.id ? 1 : 0
|
|
88
|
+
})
|
|
89
|
+
const ordered = sorted.map((candidate, index) => ({ ...candidate, rank: index + 1 }))
|
|
90
|
+
return { ok: true, ordered: Object.freeze(ordered) }
|
|
91
|
+
}
|