pantheon-opencode 1.6.2-beta.1 → 1.6.2-beta.10

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 (144) hide show
  1. package/CHANGELOG.md +163 -0
  2. package/README.md +236 -60
  3. package/README.pt-BR.md +19 -1
  4. package/bin/pantheon-init.mjs +195 -13
  5. package/package.json +11 -3
  6. package/plugin.json +1 -1
  7. package/prompts/README.md +58 -0
  8. package/prompts/debug-issue.prompt.md +46 -0
  9. package/prompts/dynamic/agora-generated.txt +38 -0
  10. package/prompts/dynamic/orchestrate-generated.txt +51 -0
  11. package/prompts/focus.prompt.md +42 -0
  12. package/prompts/implement-feature.prompt.md +39 -0
  13. package/prompts/optimize-database.prompt.md +58 -0
  14. package/prompts/orchestrate-with-zeus.prompt.md +441 -0
  15. package/prompts/plan-architecture.prompt.md +59 -0
  16. package/prompts/quick-discovery-large-codebase.prompt.md +294 -0
  17. package/prompts/quick-plan-large-feature.prompt.md +197 -0
  18. package/prompts/semantic-summarize.md +50 -0
  19. package/prompts/sketch.prompt.md +91 -0
  20. package/prompts/subtask.prompt.md +131 -0
  21. package/pyproject.toml +1 -1
  22. package/scripts/decision-router-budget.mjs +780 -0
  23. package/scripts/decision-router-v2-budget.mjs +218 -0
  24. package/scripts/decision-router-v2-egress.mjs +272 -0
  25. package/scripts/decision-router.mjs +758 -0
  26. package/scripts/docs-check-changelog.mjs +5 -3
  27. package/scripts/install/component-selection.mjs +9 -4
  28. package/scripts/install/decision-layer-preview.mjs +376 -0
  29. package/scripts/install/decision-router-config.mjs +560 -0
  30. package/scripts/install/health-check.mjs +20 -11
  31. package/scripts/install/interactive.mjs +103 -14
  32. package/scripts/install/interrupt.mjs +4 -3
  33. package/scripts/install/migrate.mjs +123 -72
  34. package/scripts/install/opencode.mjs +178 -122
  35. package/scripts/install/plan.mjs +8 -1
  36. package/scripts/install/plugin.mjs +4 -3
  37. package/scripts/install/state.mjs +12 -0
  38. package/scripts/install/strings.mjs +22 -0
  39. package/scripts/install/venv.mjs +34 -17
  40. package/scripts/mcp_resources.py +11 -9
  41. package/scripts/release-notes.mjs +30 -7
  42. package/scripts/restore.mjs +22 -10
  43. package/scripts/sync-tui.mjs +3 -3
  44. package/scripts/test-opencode-v2-sandbox.sh +10 -6
  45. package/scripts/versioning.mjs +41 -5
  46. package/src/agents/aphrodite.md +6 -1
  47. package/src/agents/apollo.md +1 -0
  48. package/src/agents/athena.md +1 -0
  49. package/src/agents/demeter.md +1 -1
  50. package/src/agents/gaia.md +1 -0
  51. package/src/agents/hephaestus.md +1 -1
  52. package/src/agents/hermes.md +8 -10
  53. package/src/agents/iris.md +1 -1
  54. package/src/agents/mnemosyne.md +1 -0
  55. package/src/agents/nyx.md +1 -1
  56. package/src/agents/prometheus.md +1 -1
  57. package/src/agents/talos.md +6 -1
  58. package/src/agents/themis.md +1 -1
  59. package/src/agents/zeus.md +52 -62
  60. package/src/mcp/eval_store.py +11 -4
  61. package/src/mcp/mcp_resources.py +11 -9
  62. package/src/mcp/memory_mcp.py +293 -150
  63. package/src/pantheon/cost-command.ts +30 -133
  64. package/src/pantheon/jev-decision-tool.ts +347 -0
  65. package/src/pantheon/jev-decisions.ts +625 -0
  66. package/src/pantheon/local-decision-agents.ts +170 -0
  67. package/src/pantheon/local-decision-budget.ts +1046 -0
  68. package/src/pantheon/local-decision-egress-gate.ts +144 -0
  69. package/src/pantheon/local-decision-prompt.ts +256 -0
  70. package/src/pantheon/local-decision-provider-matrix.ts +44 -0
  71. package/src/pantheon/local-decision-router.ts +225 -0
  72. package/src/pantheon/local-decision-skills.ts +281 -0
  73. package/src/pantheon/local-decision-tool.ts +160 -0
  74. package/src/pantheon/local-decision-turn.ts +101 -0
  75. package/src/pantheon/local-decision-usage-evidence.internal.ts +168 -0
  76. package/src/pantheon/local-orchestration.ts +322 -0
  77. package/src/pantheon/model-pricing.ts +1 -536
  78. package/src/pantheon/pantheon-decision-catalog.ts +101 -0
  79. package/src/pantheon/v2-decision-budget.ts +456 -0
  80. package/src/pantheon/v2-decision-contracts.ts +300 -0
  81. package/src/pantheon/v2-decision-egress.ts +203 -0
  82. package/src/pantheon/v2-decision-events.ts +180 -0
  83. package/src/pantheon/v2-decision-heuristic.ts +121 -0
  84. package/src/pantheon/v2-decision-points/p1-agent.ts +91 -0
  85. package/src/pantheon/v2-decision-points/p10-claims.ts +243 -0
  86. package/src/pantheon/v2-decision-points/p11-catalog.ts +220 -0
  87. package/src/pantheon/v2-decision-points/p2-skill.ts +83 -0
  88. package/src/pantheon/v2-decision-points/p3-complexity.ts +108 -0
  89. package/src/pantheon/v2-decision-points/p4-memory.ts +137 -0
  90. package/src/pantheon/v2-decision-points/p5-themis-verify.ts +190 -0
  91. package/src/pantheon/v2-decision-points/p6-council.ts +161 -0
  92. package/src/pantheon/v2-decision-points/p7-loop.ts +263 -0
  93. package/src/pantheon/v2-decision-points/p8-guardrail.ts +367 -0
  94. package/src/pantheon/v2-decision-points/p9-memory-compaction.ts +304 -0
  95. package/src/pantheon/v2-decision-points.ts +242 -0
  96. package/src/pantheon/v2-decision-policy.ts +166 -0
  97. package/src/pantheon/v2-decision-premises.ts +146 -0
  98. package/src/pantheon/v2-decision-prompt-surface.ts +115 -0
  99. package/src/pantheon/v2-decision-rank.ts +91 -0
  100. package/src/pantheon/v2-decision-registry.ts +391 -0
  101. package/src/pantheon/v2-decision-resource-ids.ts +127 -0
  102. package/src/pantheon/v2-decision-shadow.ts +123 -0
  103. package/src/pantheon/v2-decision-telemetry.ts +214 -0
  104. package/src/pantheon/v2-decision-verify.ts +51 -0
  105. package/src/pantheon/v2-hook-engine.ts +307 -0
  106. package/src/pantheon/v2-native-decisions.ts +365 -0
  107. package/src/pantheon/v2-shell-hooks.ts +66 -2
  108. package/src/pantheon/v2-tools.ts +38 -15
  109. package/src/plugin-v2.ts +419 -26
  110. package/src/plugin.ts +4 -0
  111. package/src/plugins/tui/THIRD_PARTY_NOTICES.md +24 -0
  112. package/src/plugins/tui/dist/server-v2.d.ts +19 -11
  113. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  114. package/src/plugins/tui/dist/server-v2.js +19 -666
  115. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  116. package/src/plugins/tui/dist/tui-v2.d.ts +11 -203
  117. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  118. package/src/plugins/tui/dist/tui-v2.js +187 -1917
  119. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  120. package/src/plugins/tui/dist/tui.js +1 -1
  121. package/src/plugins/tui/package-lock.json +17 -2
  122. package/src/plugins/tui/package.json +4 -2
  123. package/src/plugins/tui/src/cost-data.ts +607 -0
  124. package/src/plugins/tui/src/index-v2.tsx +213 -54
  125. package/src/plugins/tui/src/model-pricing.ts +536 -0
  126. package/src/plugins/tui/src/server-v2.ts +18 -838
  127. package/src/plugins/tui/tsdown.config.ts +28 -6
  128. package/src/plugins/tui/dist/quota-adapters.d.ts +0 -89
  129. package/src/plugins/tui/dist/quota-adapters.d.ts.map +0 -1
  130. package/src/plugins/tui/dist/quota-adapters.js +0 -1142
  131. package/src/plugins/tui/dist/quota-adapters.js.map +0 -1
  132. package/src/plugins/tui/dist/quota-cli.d.ts +0 -17
  133. package/src/plugins/tui/dist/quota-cli.d.ts.map +0 -1
  134. package/src/plugins/tui/dist/quota-cli.js +0 -184
  135. package/src/plugins/tui/dist/quota-cli.js.map +0 -1
  136. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js +0 -390
  137. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js.map +0 -1
  138. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +0 -100
  139. package/src/plugins/tui/src/go-key-diagnostic.ts +0 -125
  140. package/src/plugins/tui/src/quota-adapters.ts +0 -1598
  141. package/src/plugins/tui/src/quota-cli.ts +0 -237
  142. package/src/plugins/tui/src/quota-rpc.ts +0 -209
  143. package/src/plugins/tui/src/quota-v2-model.ts +0 -1032
  144. package/src/plugins/tui/src/quota-v2.tsx +0 -986
@@ -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
+ }