harness-reflex 0.0.0-stage → 0.3.0

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 (164) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +266 -2
  3. package/USER_GUIDE.md +639 -0
  4. package/dist/adapters/agy.d.ts +8 -0
  5. package/dist/adapters/agy.js +80 -0
  6. package/dist/adapters/agy.js.map +1 -0
  7. package/dist/adapters/claude.d.ts +13 -0
  8. package/dist/adapters/claude.js +46 -0
  9. package/dist/adapters/claude.js.map +1 -0
  10. package/dist/adapters/codex.d.ts +139 -0
  11. package/dist/adapters/codex.js +368 -0
  12. package/dist/adapters/codex.js.map +1 -0
  13. package/dist/backend/defaults.d.ts +31 -0
  14. package/dist/backend/defaults.js +32 -0
  15. package/dist/backend/defaults.js.map +1 -0
  16. package/dist/backend/factory.d.ts +11 -0
  17. package/dist/backend/factory.js +40 -0
  18. package/dist/backend/factory.js.map +1 -0
  19. package/dist/backend/jev.d.ts +524 -0
  20. package/dist/backend/jev.js +1486 -0
  21. package/dist/backend/jev.js.map +1 -0
  22. package/dist/backend/mock.d.ts +26 -0
  23. package/dist/backend/mock.js +320 -0
  24. package/dist/backend/mock.js.map +1 -0
  25. package/dist/backend/route-prompt.d.ts +37 -0
  26. package/dist/backend/route-prompt.js +42 -0
  27. package/dist/backend/route-prompt.js.map +1 -0
  28. package/dist/backend/simple-jev.d.ts +35 -0
  29. package/dist/backend/simple-jev.js +273 -0
  30. package/dist/backend/simple-jev.js.map +1 -0
  31. package/dist/backend/types.d.ts +270 -0
  32. package/dist/backend/types.js +5 -0
  33. package/dist/backend/types.js.map +1 -0
  34. package/dist/cli/index.d.ts +2 -0
  35. package/dist/cli/index.js +278 -0
  36. package/dist/cli/index.js.map +1 -0
  37. package/dist/core/calibrate.d.ts +56 -0
  38. package/dist/core/calibrate.js +144 -0
  39. package/dist/core/calibrate.js.map +1 -0
  40. package/dist/core/closing.d.ts +90 -0
  41. package/dist/core/closing.js +111 -0
  42. package/dist/core/closing.js.map +1 -0
  43. package/dist/core/evidence.d.ts +119 -0
  44. package/dist/core/evidence.js +209 -0
  45. package/dist/core/evidence.js.map +1 -0
  46. package/dist/core/gate.d.ts +25 -0
  47. package/dist/core/gate.js +114 -0
  48. package/dist/core/gate.js.map +1 -0
  49. package/dist/core/judge.d.ts +221 -0
  50. package/dist/core/judge.js +251 -0
  51. package/dist/core/judge.js.map +1 -0
  52. package/dist/core/ledger.d.ts +67 -0
  53. package/dist/core/ledger.js +173 -0
  54. package/dist/core/ledger.js.map +1 -0
  55. package/dist/core/orchestrate-closing.d.ts +237 -0
  56. package/dist/core/orchestrate-closing.js +250 -0
  57. package/dist/core/orchestrate-closing.js.map +1 -0
  58. package/dist/core/orchestrate-correction.d.ts +209 -0
  59. package/dist/core/orchestrate-correction.js +141 -0
  60. package/dist/core/orchestrate-correction.js.map +1 -0
  61. package/dist/core/orchestrate-host.d.ts +225 -0
  62. package/dist/core/orchestrate-host.js +80 -0
  63. package/dist/core/orchestrate-host.js.map +1 -0
  64. package/dist/core/orchestrate-stagnation.d.ts +259 -0
  65. package/dist/core/orchestrate-stagnation.js +270 -0
  66. package/dist/core/orchestrate-stagnation.js.map +1 -0
  67. package/dist/core/orchestrate.d.ts +357 -0
  68. package/dist/core/orchestrate.js +418 -0
  69. package/dist/core/orchestrate.js.map +1 -0
  70. package/dist/core/policy.d.ts +122 -0
  71. package/dist/core/policy.js +102 -0
  72. package/dist/core/policy.js.map +1 -0
  73. package/dist/core/prune-plan.d.ts +141 -0
  74. package/dist/core/prune-plan.js +390 -0
  75. package/dist/core/prune-plan.js.map +1 -0
  76. package/dist/core/prune.d.ts +30 -0
  77. package/dist/core/prune.js +73 -0
  78. package/dist/core/prune.js.map +1 -0
  79. package/dist/core/route.d.ts +35 -0
  80. package/dist/core/route.js +39 -0
  81. package/dist/core/route.js.map +1 -0
  82. package/dist/core/score.d.ts +40 -0
  83. package/dist/core/score.js +49 -0
  84. package/dist/core/score.js.map +1 -0
  85. package/dist/core/screen.d.ts +22 -0
  86. package/dist/core/screen.js +117 -0
  87. package/dist/core/screen.js.map +1 -0
  88. package/dist/core/stagnation.d.ts +23 -0
  89. package/dist/core/stagnation.js +93 -0
  90. package/dist/core/stagnation.js.map +1 -0
  91. package/dist/core/text.d.ts +36 -0
  92. package/dist/core/text.js +66 -0
  93. package/dist/core/text.js.map +1 -0
  94. package/dist/hook/cli.d.ts +9 -0
  95. package/dist/hook/cli.js +52 -0
  96. package/dist/hook/cli.js.map +1 -0
  97. package/dist/hook/contract.d.ts +125 -0
  98. package/dist/hook/contract.js +159 -0
  99. package/dist/hook/contract.js.map +1 -0
  100. package/dist/hook/decision.d.ts +97 -0
  101. package/dist/hook/decision.js +955 -0
  102. package/dist/hook/decision.js.map +1 -0
  103. package/dist/hook/memory-store.d.ts +81 -0
  104. package/dist/hook/memory-store.js +157 -0
  105. package/dist/hook/memory-store.js.map +1 -0
  106. package/dist/hook/payload.d.ts +55 -0
  107. package/dist/hook/payload.js +129 -0
  108. package/dist/hook/payload.js.map +1 -0
  109. package/dist/hook/run.d.ts +48 -0
  110. package/dist/hook/run.js +218 -0
  111. package/dist/hook/run.js.map +1 -0
  112. package/dist/hook/store-port.d.ts +72 -0
  113. package/dist/hook/store-port.js +2 -0
  114. package/dist/hook/store-port.js.map +1 -0
  115. package/dist/index.d.ts +18 -0
  116. package/dist/index.js +19 -0
  117. package/dist/index.js.map +1 -0
  118. package/dist/mcp/server.d.ts +12 -0
  119. package/dist/mcp/server.js +368 -0
  120. package/dist/mcp/server.js.map +1 -0
  121. package/dist/ports/audit.d.ts +18 -0
  122. package/dist/ports/audit.js +11 -0
  123. package/dist/ports/audit.js.map +1 -0
  124. package/dist/ports/clock.d.ts +14 -0
  125. package/dist/ports/clock.js +11 -0
  126. package/dist/ports/clock.js.map +1 -0
  127. package/dist/ports/decision.d.ts +75 -0
  128. package/dist/ports/decision.js +2 -0
  129. package/dist/ports/decision.js.map +1 -0
  130. package/dist/ports/index.d.ts +14 -0
  131. package/dist/ports/index.js +2 -0
  132. package/dist/ports/index.js.map +1 -0
  133. package/dist/ports/log.d.ts +22 -0
  134. package/dist/ports/log.js +12 -0
  135. package/dist/ports/log.js.map +1 -0
  136. package/dist/ports/state.d.ts +46 -0
  137. package/dist/ports/state.js +13 -0
  138. package/dist/ports/state.js.map +1 -0
  139. package/dist/state/clock.d.ts +40 -0
  140. package/dist/state/clock.js +43 -0
  141. package/dist/state/clock.js.map +1 -0
  142. package/dist/state/file-store.d.ts +340 -0
  143. package/dist/state/file-store.js +849 -0
  144. package/dist/state/file-store.js.map +1 -0
  145. package/dist/state/paths.d.ts +41 -0
  146. package/dist/state/paths.js +73 -0
  147. package/dist/state/paths.js.map +1 -0
  148. package/docs/USER_GUIDE.en.md +721 -0
  149. package/docs/claude-code.md +281 -0
  150. package/docs/design/v0.2.0-harness-plugins.md +381 -0
  151. package/docs/design/v0.3.0-orchestration-unification.md +580 -0
  152. package/docs/dsh-plugin.md +578 -0
  153. package/docs/reflex-ui-regression-2026-10-20.md +34 -0
  154. package/docs/release-checklist-v0.1.0.md +315 -0
  155. package/docs/release-handbook-porting-notes.md +106 -0
  156. package/docs/release-handbook.md +393 -0
  157. package/docs/release-notes-v0.1.0.md +63 -0
  158. package/docs/release-notes-v0.3.0.md +152 -0
  159. package/docs/research/claude-code-harness.md +607 -0
  160. package/docs/research/pi-harness.md +621 -0
  161. package/experiments/data/calibration_sample.json +14 -0
  162. package/experiments/index.ts +29 -0
  163. package/experiments/runner.ts +156 -0
  164. package/package.json +82 -4
@@ -0,0 +1,524 @@
1
+ import { ActionStep, BackendHealth, ChoiceOption, ChoiceRequest, ChoiceResponse, DecisionBackend, GateRequest, GateResponse, PruneRequest, PruneResponse, RouteRequest, RouteResponse, StagnationCheckRequest, StagnationCheckResponse } from './types.js';
2
+ export interface JevBackendConfig {
3
+ baseUrl?: string;
4
+ apiKey?: string;
5
+ model?: string;
6
+ timeoutMs?: number;
7
+ /**
8
+ * Character count from which `prune()` judges the payload segment by segment
9
+ * through System One. Below it the deterministic local candidates are used and
10
+ * no request is sent. Defaults to 10000 (or
11
+ * `SYSTEM_ONE_PRUNE_JUDGE_MIN_CHARS`); mirrors
12
+ * `interventions.pruneJudgeMinChars` of the plugin config.
13
+ */
14
+ pruneJudgeMinChars?: number;
15
+ }
16
+ /**
17
+ * One `choice` question of `POST /v1/systemone`.
18
+ *
19
+ * The gateway decides *between criteria*: the dictionary keys are the answers
20
+ * the model may name, the values the descriptions it reads. There is no
21
+ * free-text answer, which is why a caller's option list becomes this dictionary
22
+ * and comes back as `answers[id].probabilities`, keyed exactly like the
23
+ * criteria.
24
+ */
25
+ export interface SystemOneChoiceQuestion {
26
+ type: 'choice';
27
+ instructions: string;
28
+ criteria: Record<string, string>;
29
+ }
30
+ /** One `score` question: `criteria` is a list, and the answer indexes it. */
31
+ export interface SystemOneScoreQuestion {
32
+ type: 'score';
33
+ instructions: string;
34
+ criteria: string[];
35
+ }
36
+ /** A question of the single-endpoint contract; `type` discriminates the union. */
37
+ export type SystemOneQuestion = SystemOneChoiceQuestion | SystemOneScoreQuestion;
38
+ /** Body of the one and only request this backend sends. */
39
+ export interface SystemOneRequest {
40
+ model: string;
41
+ state: Record<string, unknown>;
42
+ questions: Record<string, SystemOneQuestion>;
43
+ }
44
+ /** Answer of a `choice` question: the named criterion plus its distribution. */
45
+ export interface SystemOneChoiceAnswer {
46
+ type?: string;
47
+ /** Criterion key the model named; equals the argmax of `probabilities`. */
48
+ choice?: string;
49
+ /** The gateway's own confidence, distinct from the argmax probability. */
50
+ confidence?: number;
51
+ probabilities?: Record<string, number>;
52
+ }
53
+ /**
54
+ * Answer of a `score` question.
55
+ *
56
+ * `probabilities` is keyed by the *index* of the criteria list and `score` is
57
+ * the probability-weighted mean index (measured against `jev-1.13.0`), so
58
+ * `Math.round(score)` is the argmax index and `legend` names each index.
59
+ */
60
+ export interface SystemOneScoreAnswer {
61
+ type?: string;
62
+ score?: number;
63
+ confidence?: number;
64
+ legend?: Record<string, string>;
65
+ probabilities?: Record<string, number>;
66
+ }
67
+ /** Response envelope of `POST /v1/systemone`. */
68
+ export interface SystemOneResponse {
69
+ model?: string;
70
+ answers?: Record<string, SystemOneChoiceAnswer | SystemOneScoreAnswer>;
71
+ usage?: {
72
+ input_tokens?: number;
73
+ output_tokens?: number;
74
+ };
75
+ }
76
+ /** Path of the one endpoint the current gateway exposes. */
77
+ export declare const SYSTEMONE_ENDPOINT_PATH = "/v1/systemone";
78
+ /** Endpoint used when neither configuration nor environment supplies a base. */
79
+ export declare const DEFAULT_SYSTEMONE_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
80
+ /** Illustration of a choice request, for docs and drift checks. */
81
+ export declare const CHOICE_REQUEST_EXAMPLE: {
82
+ readonly model: "jev-latest";
83
+ readonly state: {};
84
+ readonly questions: {
85
+ readonly q: {
86
+ readonly type: "choice";
87
+ readonly instructions: "Which option is better?";
88
+ readonly criteria: {
89
+ readonly a: "the first option";
90
+ readonly b: "the second option";
91
+ };
92
+ };
93
+ };
94
+ };
95
+ /** Question id of a plain {@link JevDecisionBackend.choice} call. */
96
+ export declare const CHOICE_QUESTION_ID = "choice";
97
+ /** Question id of a {@link JevDecisionBackend.route} call. */
98
+ export declare const ROUTE_QUESTION_ID = "route";
99
+ /** Question id of a {@link JevDecisionBackend.prune} call. */
100
+ export declare const PRUNE_QUESTION_ID = "prune";
101
+ /** Question id of a {@link JevDecisionBackend.checkStagnation} call. */
102
+ export declare const STAGNATION_QUESTION_ID = "stagnation";
103
+ /** Prefix of the per-assertion question ids of a {@link JevDecisionBackend.gate} call. */
104
+ export declare const GATE_QUESTION_PREFIX = "assertion-";
105
+ /** Verdicts the model may name for one gate assertion. Escalation is ours, never its. */
106
+ export type GateVerdict = 'verified' | 'contradicted' | 'not_addressed';
107
+ /** Criteria of a gate assertion, in the order ties are broken. */
108
+ export declare const GATE_VERDICTS: readonly GateVerdict[];
109
+ /** What each gate verdict means to the model. */
110
+ export declare const GATE_VERDICT_CRITERIA: Readonly<Record<GateVerdict, string>>;
111
+ /**
112
+ * Minimum probability on `verified` for a strictness level to claim success.
113
+ * Anything below is escalated: a three-way choice at chance is 1/3, so the
114
+ * lenient floor never accepts a distribution the model did not actually prefer.
115
+ */
116
+ export declare const GATE_CONFIDENCE_FLOOR: Readonly<Record<'high' | 'normal' | 'lenient', number>>;
117
+ /** Patterns a run can be stuck in. */
118
+ export type StagnationPattern = 'repetition' | 'oscillation' | 'failing_retry' | 'zero_progress' | 'none';
119
+ /** Pattern criteria, in the order ties are broken. */
120
+ export declare const STAGNATION_PATTERNS: readonly StagnationPattern[];
121
+ /** What each stagnation pattern means to the model. */
122
+ export declare const STAGNATION_PATTERN_CRITERIA: Readonly<Record<StagnationPattern, string>>;
123
+ /** One-line diagnosis of each pattern. */
124
+ export declare const STAGNATION_DIAGNOSIS: Readonly<Record<StagnationPattern, string>>;
125
+ /** Corrective action recommended for each stuck pattern. */
126
+ export declare const STAGNATION_INTERVENTION: Readonly<Record<StagnationPattern, string>>;
127
+ /** Minimum probability for a stuck pattern to be reported as a real alert. */
128
+ export declare const STAGNATION_STUCK_FLOOR = 0.4;
129
+ /**
130
+ * Resolve the endpoint the single request goes to.
131
+ *
132
+ * Every accepted spelling of the base — the full `…/v1/systemone` URL the docs
133
+ * and `JEV_API_BASE` use, a `/v1` root, or a bare host — collapses onto exactly
134
+ * one URL, so a retired per-capability sub-path can never be appended.
135
+ * @param baseUrl - configured or environment base; empty selects the default.
136
+ * @returns the absolute URL of `POST /v1/systemone`.
137
+ */
138
+ export declare function normalizeSystemOneEndpoint(baseUrl?: string): string;
139
+ /**
140
+ * Turn a list of labels into the unique criteria keys of a choice question.
141
+ *
142
+ * Criteria keys are the option labels themselves, which is what makes the
143
+ * answer's probability dictionary readable as option probabilities. Duplicates
144
+ * (two pool entries with the same name) get a numeric suffix so no option can be
145
+ * lost in the dictionary.
146
+ * @param labels - the option labels, in caller order.
147
+ * @returns one unique key per label, in the same order.
148
+ */
149
+ export declare function uniqueCriteriaKeys(labels: readonly string[]): string[];
150
+ /**
151
+ * Read one answer's distribution against the criteria keys it was asked about.
152
+ * @param probabilities - `answers[id].probabilities`, when present.
153
+ * @param keys - criteria keys of the question, in declared order.
154
+ * @returns every key mapped to its probability (missing keys read 0), or
155
+ * `undefined` when the answer carries no usable distribution at all.
156
+ */
157
+ export declare function readDistribution(probabilities: Record<string, number> | undefined, keys: readonly string[]): Map<string, number> | undefined;
158
+ /**
159
+ * Highest-probability key of a distribution.
160
+ * @param distribution - probabilities keyed by criteria key.
161
+ * @param order - declared key order, used to break ties deterministically.
162
+ * @returns the winning key, or `undefined` for an empty order.
163
+ */
164
+ export declare function argmaxKey(distribution: Map<string, number>, order: readonly string[]): string | undefined;
165
+ /**
166
+ * Build the choice response options from one gateway answer.
167
+ *
168
+ * The distribution is authoritative; the gateway's discrete `choice` only
169
+ * breaks a tie. When the gateway returns no distribution but does name a
170
+ * criterion, the answer is reconstructed around that name and flagged
171
+ * `uncalibrated`, because the probabilities are then ours, not the gateway's.
172
+ * @param labels - option labels in caller order.
173
+ * @param keys - criteria keys, aligned with `labels`.
174
+ * @param distribution - parsed distribution, when the answer had one.
175
+ * @param answer - the raw gateway answer.
176
+ * @returns sorted options plus the uncalibrated flag, or `undefined` when the
177
+ * answer cannot be turned into a distribution at all.
178
+ */
179
+ export declare function toChoiceOptions(labels: readonly string[], keys: readonly string[], distribution: Map<string, number> | undefined, answer: SystemOneChoiceAnswer | undefined): {
180
+ options: ChoiceOption[];
181
+ uncalibrated: boolean;
182
+ } | undefined;
183
+ /**
184
+ * Read the winning criteria index out of a `score` answer.
185
+ * @param answer - the gateway's score answer.
186
+ * @param count - number of criteria the question offered.
187
+ * @returns the argmax index, or `undefined` when the answer is unusable.
188
+ */
189
+ export declare function readScoreIndex(answer: SystemOneScoreAnswer | undefined, count: number): number | undefined;
190
+ /** Instruction block of a route decision; renders the same facts the logits backend scores. */
191
+ export declare function buildRouteInstructions(req: RouteRequest): string;
192
+ /** One deterministic pruning of a raw output. */
193
+ export interface PruneCandidate {
194
+ id: 'aggressive' | 'balanced' | 'conservative';
195
+ /** Human-readable label including the reduction it achieved. */
196
+ label: string;
197
+ text: string;
198
+ /** Segments this candidate kept whole; observability of the selection. */
199
+ keptSegments?: number;
200
+ }
201
+ /**
202
+ * Build the deterministic prunings used below the judging threshold and as the
203
+ * fallback when System One cannot judge the segments.
204
+ *
205
+ * These are the legacy line filters: {@link JevDecisionBackend.prune} no longer
206
+ * uses them as its primary decision for large payloads — the per-segment scores
207
+ * are — so `PROGRESS_ART`/`NOISE_LINE` are one input among two, never the sole
208
+ * basis of a reduction.
209
+ * @param rawOutput - the bulk output to reduce.
210
+ * @param intent - what the caller is looking for.
211
+ * @param maxTokens - optional token budget applied to every candidate.
212
+ * @returns distinct candidates, most aggressive first; empty for empty input.
213
+ */
214
+ export declare function buildPruneCandidates(rawOutput: string, intent: string, maxTokens?: number): PruneCandidate[];
215
+ /**
216
+ * Candidate used when the ranking is unavailable: the balanced filter, which is
217
+ * the safest reduction that still removes noise.
218
+ * @param candidates - candidates of {@link buildPruneCandidates}.
219
+ * @returns the local default, or `undefined` for an empty list.
220
+ */
221
+ export declare function pickLocalPruneCandidate(candidates: readonly PruneCandidate[]): PruneCandidate | undefined;
222
+ /**
223
+ * Reduce one line to the template later lines are compared against.
224
+ *
225
+ * Variable tokens (UUIDs, timestamps, IPs, hex ids, durations, percentages,
226
+ * floats, plain numbers) become placeholders and runs of whitespace collapse,
227
+ * so "progress 001" and "progress 002" share a template while two genuinely
228
+ * different lines do not. The original line is what is printed, never this
229
+ * string.
230
+ * @param line - one line of the output.
231
+ * @returns its shape, whitespace-normalized.
232
+ */
233
+ export declare function templateOfLine(line: string): string;
234
+ /**
235
+ * Compress a bulk output by its line templates, independent of any format.
236
+ *
237
+ * Consecutive lines whose templates match form a run: a run of four or more
238
+ * keeps its first two and its last line and replaces the rest with one marker.
239
+ * Consecutive blank lines collapse to one. The first line, the last line and
240
+ * every diagnostic line survive verbatim. This is the fallback used when System
241
+ * One cannot judge — it never replaces a real decision.
242
+ * @param rawOutput - the bulk output to reduce.
243
+ * @returns the reduced text; never longer than the input.
244
+ */
245
+ export declare function compressByTemplate(rawOutput: string): string;
246
+ /**
247
+ * Character count from which {@link JevDecisionBackend.prune} judges segments
248
+ * with System One. Kept in sync with `interventions.pruneJudgeMinChars`.
249
+ */
250
+ export declare const PRUNE_JUDGE_MIN_CHARS_DEFAULT = 10000;
251
+ /** Upper bound on segments judged by one request; the rest are kept deterministically. */
252
+ export declare const PRUNE_MAX_JUDGED_SEGMENTS = 40;
253
+ /** Prefix of the per-segment question ids of a pruning judgment. */
254
+ export declare const PRUNE_SEGMENT_QUESTION_PREFIX = "prune-seg-";
255
+ /**
256
+ * Resolve the segment-judging character threshold from an explicit value, then
257
+ * the environment, then the documented default.
258
+ * @param value - explicit backend configuration, when supplied.
259
+ * @returns a non-negative finite character count.
260
+ */
261
+ export declare function resolvePruneJudgeMinChars(value?: number): number;
262
+ /** One contiguous run of non-blank lines, the unit System One judges. */
263
+ interface PruneSegment {
264
+ /** Position in the original output, oldest first. */
265
+ index: number;
266
+ /** 0-based inclusive line range in the original output. */
267
+ startLine: number;
268
+ endLine: number;
269
+ /** The segment text exactly as it appears in the output. */
270
+ text: string;
271
+ chars: number;
272
+ /** Absolute line indexes always kept, regardless of the score. */
273
+ forcedLines: number[];
274
+ }
275
+ /**
276
+ * Cut an output into the segments System One judges.
277
+ *
278
+ * Paragraphs are separated by blank lines; a paragraph longer than
279
+ * {@link PRUNE_SEGMENT_MAX_CHARS} is split on line windows, so the model never
280
+ * sees one oversized block and the local replay can reassemble the exact lines.
281
+ * Line order and line numbers are preserved: every segment is a half-open view
282
+ * of the original line array.
283
+ * @param rawOutput - the bulk output.
284
+ * @param intent - what the caller is looking for.
285
+ * @returns segments in original order, with their forced line indexes.
286
+ */
287
+ export declare function segmentPruneOutput(rawOutput: string, intent: string): PruneSegment[];
288
+ /**
289
+ * Read one segment's keep score (0 = omit, 1 = keep) out of its `score` answer.
290
+ * The distribution over the two criteria is authoritative; the weighted `score`
291
+ * is the fallback, and nothing usable reads as `undefined`.
292
+ * @param answer - the gateway's answer for this segment question.
293
+ * @returns the keep score in `[0, 1]`, or `undefined` when unusable.
294
+ */
295
+ export declare function readSegmentKeepScore(answer: SystemOneScoreAnswer | undefined): number | undefined;
296
+ /**
297
+ * Pick the segments a budget keeps from their scores.
298
+ *
299
+ * Segments without a usable score are an unjudged safety margin and are always
300
+ * kept; scored segments are taken from the highest score down until the
301
+ * character budget is spent. Ties follow the original order.
302
+ * @param segments - all segments of the output.
303
+ * @param scores - keep score per segment index, absent for unjudged segments.
304
+ * @param originalChars - character count of the unpruned output.
305
+ * @param ratio - share of the original characters scored segments may use.
306
+ * @returns indexes of the segments this candidate keeps in full.
307
+ */
308
+ export declare function selectPruneSegments(segments: readonly PruneSegment[], scores: ReadonlyMap<number, number>, originalChars: number, ratio: number): Set<number>;
309
+ /**
310
+ * Reassemble one candidate in the original line order.
311
+ *
312
+ * A selected segment is kept whole; an unselected one keeps only its forced
313
+ * lines (first/last anchors, diagnostics, intent matches). Consecutive fully
314
+ * omitted segments collapse into one marker that names how many were dropped.
315
+ * Blank runs between kept lines collapse to a single blank line.
316
+ * @param rawOutput - the original output, for its lines.
317
+ * @param segments - segments in original order.
318
+ * @param selected - segment indexes kept whole.
319
+ * @returns the reduced text.
320
+ */
321
+ export declare function assemblePruneCandidate(rawOutput: string, segments: readonly PruneSegment[], selected: ReadonlySet<number>): string;
322
+ /**
323
+ * Build the three System One–scored prunings from one segment judgment.
324
+ *
325
+ * The segment keep/drop decision is the model's score; the three ids only
326
+ * differ in their character budget, so the ranking the engine used to make is
327
+ * now made per segment.
328
+ * @param rawOutput - the original output.
329
+ * @param segments - segments of that output in original order.
330
+ * @param scores - keep score per segment index.
331
+ * @param maxTokens - optional hard token ceiling applied to every candidate.
332
+ * @returns candidates ordered from aggressive to conservative.
333
+ */
334
+ export declare function buildScoredPruneCandidates(rawOutput: string, segments: readonly PruneSegment[], scores: ReadonlyMap<number, number>, maxTokens?: number): PruneCandidate[];
335
+ /** The scored candidate one segment judgment installs, and why it did. */
336
+ export interface ScoredPrunePick {
337
+ /** The text the segmented path returns: a reducing candidate, or the raw output. */
338
+ text: string;
339
+ /** The candidate that reduced the payload; absent when none did. */
340
+ candidate?: PruneCandidate;
341
+ /** Why no scored candidate was used, when none was. */
342
+ reason?: string;
343
+ }
344
+ /**
345
+ * Pick the first scored candidate strictly smaller than the payload.
346
+ *
347
+ * The balanced budget is tried first because it is the documented default. A
348
+ * payload whose forced lines (anchors, diagnostics, intent matches) already
349
+ * reproduce it verbatim makes even the balanced candidate as large as the
350
+ * original; the tighter and then the wider budget are tried before giving up,
351
+ * so a smaller aggressive candidate is never thrown away by the balanced one.
352
+ * A candidate that does not reduce the payload is never returned as the text:
353
+ * the caller treats that outcome as a judgment that kept everything, unless the
354
+ * judgment produced no usable score at all.
355
+ * @param rawOutput - the original output the candidates were built from.
356
+ * @param candidates - the scored candidates, in any order.
357
+ * @returns the reducing text plus the candidate that produced it, or the raw
358
+ * output plus the reason no candidate was usable.
359
+ */
360
+ export declare function pickScoredPruneCandidate(rawOutput: string, candidates: readonly PruneCandidate[]): ScoredPrunePick;
361
+ /** A local stagnation verdict, used when the gateway cannot supply one. */
362
+ export interface LocalStagnationVerdict {
363
+ isStuck: boolean;
364
+ patternType: StagnationPattern;
365
+ confidence: number;
366
+ diagnosis: string;
367
+ recommendedIntervention?: string;
368
+ }
369
+ /**
370
+ * Deterministic stagnation detector over a recent action window.
371
+ *
372
+ * It is the offline half of {@link JevDecisionBackend.checkStagnation}: the
373
+ * gateway classifies the pattern, and this reads the same history with explicit
374
+ * rules, so a dead gateway degrades the verdict instead of losing it.
375
+ * @param recent - the recent action window, oldest first.
376
+ * @returns the locally detected pattern.
377
+ */
378
+ export declare function detectStagnationLocally(recent: readonly ActionStep[]): LocalStagnationVerdict;
379
+ /**
380
+ * Jev System One Provider Adapter
381
+ *
382
+ * Speaks only the current gateway contract: one `POST /v1/systemone` carrying
383
+ * `{ model, state, questions }`, where every question is a `choice` between
384
+ * criteria or a `score` over a criteria list. The gateway returns discrete
385
+ * distributions, never free text, so the four composite capabilities
386
+ * (`gate`, `prune`, `checkStagnation`, `route`) are expressed as criteria
387
+ * questions and backed by deterministic local fallbacks.
388
+ */
389
+ export declare class JevDecisionBackend implements DecisionBackend {
390
+ readonly name = "system-one-jev";
391
+ readonly model: string;
392
+ /** Absolute URL of the single endpoint; no call appends a sub-path to it. */
393
+ readonly endpoint: string;
394
+ private readonly apiKey;
395
+ private readonly timeoutMs;
396
+ /** Character count from which pruning judges segments through System One. */
397
+ private readonly pruneJudgeMinChars;
398
+ /**
399
+ * Health of the gateway conversation of this backend.
400
+ *
401
+ * Every request updates it; a success clears the failure fields and resets the
402
+ * run. It lives in memory only, so a restarted Host starts healthy.
403
+ */
404
+ private healthState;
405
+ constructor(config?: JevBackendConfig);
406
+ /**
407
+ * Health of the outbound gateway conversation.
408
+ * @returns a copy of the counters, safe to hand to a panel snapshot.
409
+ */
410
+ health(): BackendHealth;
411
+ /** Record one successful request: the backend is available again. */
412
+ private noteSuccess;
413
+ /** Record one failed request and its reason. */
414
+ private noteFailure;
415
+ /**
416
+ * Send one request to the single endpoint.
417
+ * @param questions - questions keyed by id; answers come back under the same ids.
418
+ * @param state - machine-readable situation the questions reason about.
419
+ * @returns the gateway's answer envelope.
420
+ */
421
+ private postSystemOne;
422
+ /**
423
+ * Classify one question into a probability distribution over the options.
424
+ *
425
+ * The options become the `criteria` dictionary (key = option label, value =
426
+ * the description the model reads) and `answers[id].probabilities` — keyed by
427
+ * criterion — becomes the returned option distribution. An answer without a
428
+ * usable distribution fails loudly: the caller asked for a decision, and a
429
+ * fabricated one would be worse than an error.
430
+ * @param req - question, options, optional context.
431
+ * @returns options sorted by probability, plus the winning option.
432
+ */
433
+ choice(req: ChoiceRequest): Promise<ChoiceResponse>;
434
+ /**
435
+ * Verify assertions against evidence, fail-closed.
436
+ *
437
+ * Every assertion becomes one `choice` question in the same request, and the
438
+ * answer's distribution over `verified` / `contradicted` / `not_addressed`
439
+ * becomes the verdict. Anything unusable — a failed call, a missing answer, a
440
+ * distribution below the strictness floor — escalates that assertion; the
441
+ * method never returns a pass it could not observe.
442
+ * @param req - assertions, evidence, strictness.
443
+ * @returns one result per assertion plus the aggregate verdict.
444
+ */
445
+ gate(req: GateRequest): Promise<GateResponse>;
446
+ /** One assertion's outcome from its answer; unusable answers escalate. */
447
+ private gateItem;
448
+ /** Every assertion escalated for one reason — the fail-closed shape. */
449
+ private failClosedGate;
450
+ /**
451
+ * Reduce a bulk output to the segments the intent needs, fail-open.
452
+ *
453
+ * Two paths share one contract. A payload below `pruneJudgeMinChars` is
454
+ * reduced by the deterministic local candidates and sends no request at all.
455
+ * A payload at/above it is cut into segments, and one `score` question per
456
+ * segment lets System One decide what to keep; the three budgets only decide
457
+ * how much of the top-scored material fits. Forced lines (first/last anchors,
458
+ * diagnostics, intent matches) survive either way. Any failure — call,
459
+ * transport, unusable answer — falls back to the local candidates, so pruning
460
+ * never breaks the harness and never returns the raw blob just because the
461
+ * network blinked.
462
+ * @param req - raw output, intent, budget, shadow flag.
463
+ * @returns the pruned text plus its reduction metrics and the path taken.
464
+ */
465
+ prune(req: PruneRequest): Promise<PruneResponse>;
466
+ /** The deterministic candidate text, or the raw output when it does not shrink. */
467
+ private localPruneText;
468
+ /**
469
+ * Reduce the payload when System One cannot judge it.
470
+ *
471
+ * Template compression is format-independent, so it still shrinks output the
472
+ * deterministic line filters cannot (progress art they would drop entirely, a
473
+ * table whose rows differ only by a number). It is only ever used here, on the
474
+ * degraded path, and the smaller of it and the local candidates wins.
475
+ * @param raw - the original output.
476
+ * @param intent - what the caller is looking for.
477
+ * @param maxTokens - optional token budget.
478
+ * @returns the reduced text and which strategy produced it.
479
+ */
480
+ private fallbackPruneText;
481
+ /** The per-segment System One path, with the local candidates as its fallback. */
482
+ private pruneWithSegments;
483
+ /**
484
+ * Judge every segment in one request: one `score` question per segment, with
485
+ * the segment text and the intent in the shared state.
486
+ * @param judged - the segments selected for judging, in original order.
487
+ * @param totalSegments - segment count of the whole output (for the prompt).
488
+ * @param intent - what the caller is looking for.
489
+ * @returns the keep score per segment index (segments without a usable answer
490
+ * are absent) and how many answers were returned but could not be read.
491
+ */
492
+ private scoreSegments;
493
+ /** Shape one pruning as the shared prune response. */
494
+ private pruneResponse;
495
+ /**
496
+ * Classify the recent action window into one execution pattern.
497
+ *
498
+ * One `choice` question over the five patterns; the distribution decides the
499
+ * verdict and its confidence. When the gateway cannot answer, the same window
500
+ * is read by {@link detectStagnationLocally}, so a network failure lowers the
501
+ * quality of the verdict instead of removing it.
502
+ * @param req - action history and optional goal.
503
+ * @returns the pattern, whether it is stuck, and the intervention.
504
+ */
505
+ checkStagnation(req: StagnationCheckRequest): Promise<StagnationCheckResponse>;
506
+ /** The local half of {@link checkStagnation}, annotated with why it ran. */
507
+ private localStagnation;
508
+ /**
509
+ * Rank candidates for a goal with one `choice` question.
510
+ *
511
+ * The criteria are the candidate names carrying their descriptions and the
512
+ * incumbent mark, and the answer's distribution is the ranking. The rendered
513
+ * context block of {@link buildRouteContext} — the same facts the logits
514
+ * backend scores — rides in the instructions, so cache-affinity facts and the
515
+ * policy reach the model. A failing gateway falls back to a local keyword
516
+ * ranking whose reasons say so, keeping routing alive.
517
+ * @param req - goal, candidates, topK, session facts, policy.
518
+ * @returns the ranked candidates, best first.
519
+ */
520
+ route(req: RouteRequest): Promise<RouteResponse>;
521
+ /** Deterministic keyword ranking used when the gateway cannot rank. */
522
+ private localRoute;
523
+ }
524
+ export {};