dsh-harness-reflex 0.1.0 → 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.
- package/README.md +20 -6
- package/client.js +3511 -185
- package/dist/attribution.d.ts +266 -0
- package/dist/attribution.js +238 -0
- package/dist/attribution.js.map +1 -0
- package/dist/bridge.d.ts +311 -13
- package/dist/bridge.js +714 -42
- package/dist/bridge.js.map +1 -1
- package/dist/client-bundle.js +4 -1
- package/dist/client-bundle.js.map +1 -1
- package/dist/command.js +10 -0
- package/dist/command.js.map +1 -1
- package/dist/config.d.ts +530 -22
- package/dist/config.js +808 -27
- package/dist/config.js.map +1 -1
- package/dist/delegation-dispatch.d.ts +132 -0
- package/dist/delegation-dispatch.js +186 -0
- package/dist/delegation-dispatch.js.map +1 -0
- package/dist/delegation-health.d.ts +131 -0
- package/dist/delegation-health.js +97 -0
- package/dist/delegation-health.js.map +1 -0
- package/dist/delegation.d.ts +148 -0
- package/dist/delegation.js +186 -0
- package/dist/delegation.js.map +1 -0
- package/dist/effort-delegation.d.ts +144 -0
- package/dist/effort-delegation.js +280 -0
- package/dist/effort-delegation.js.map +1 -0
- package/dist/effort.d.ts +141 -0
- package/dist/effort.js +251 -9
- package/dist/effort.js.map +1 -1
- package/dist/host-patch.d.ts +156 -0
- package/dist/host-patch.js +534 -0
- package/dist/host-patch.js.map +1 -0
- package/dist/index.d.ts +12 -3
- package/dist/index.js +99 -7
- package/dist/index.js.map +1 -1
- package/dist/interventions.d.ts +98 -373
- package/dist/interventions.js +442 -1702
- package/dist/interventions.js.map +1 -1
- package/dist/panel-api.d.ts +328 -4
- package/dist/panel-api.js +322 -15
- package/dist/panel-api.js.map +1 -1
- package/dist/panel-mount.d.ts +81 -22
- package/dist/panel-mount.js +228 -7
- package/dist/panel-mount.js.map +1 -1
- package/dist/routing.d.ts +23 -18
- package/dist/routing.js +471 -153
- package/dist/routing.js.map +1 -1
- package/dist/session-audit.d.ts +70 -0
- package/dist/session-audit.js +73 -0
- package/dist/session-audit.js.map +1 -1
- package/dist/systemone-probe.d.ts +114 -0
- package/dist/systemone-probe.js +383 -0
- package/dist/systemone-probe.js.map +1 -0
- package/dist/testing.d.ts +212 -7
- package/dist/testing.js +333 -27
- package/dist/testing.js.map +1 -1
- package/dist/tools.d.ts +109 -3
- package/dist/tools.js +103 -4
- package/dist/tools.js.map +1 -1
- package/dist/unconfigured-backend.d.ts +72 -0
- package/dist/unconfigured-backend.js +94 -0
- package/dist/unconfigured-backend.js.map +1 -0
- package/dist/vendor/harness-reflex/backend/factory.d.ts +31 -1
- package/dist/vendor/harness-reflex/backend/factory.js +18 -3
- package/dist/vendor/harness-reflex/backend/factory.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/jev.d.ts +20 -0
- package/dist/vendor/harness-reflex/backend/jev.js +11 -4
- package/dist/vendor/harness-reflex/backend/jev.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/simple-jev.d.ts +16 -0
- package/dist/vendor/harness-reflex/backend/simple-jev.js +17 -6
- package/dist/vendor/harness-reflex/backend/simple-jev.js.map +1 -1
- package/dist/vendor/harness-reflex/core/closing.d.ts +90 -0
- package/dist/vendor/harness-reflex/core/closing.js +111 -0
- package/dist/vendor/harness-reflex/core/closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/evidence.d.ts +119 -0
- package/dist/vendor/harness-reflex/core/evidence.js +209 -0
- package/dist/vendor/harness-reflex/core/evidence.js.map +1 -0
- package/dist/vendor/harness-reflex/core/judge.d.ts +221 -0
- package/dist/vendor/harness-reflex/core/judge.js +251 -0
- package/dist/vendor/harness-reflex/core/judge.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.d.ts +237 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js +250 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.d.ts +209 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js +141 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.d.ts +225 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js +80 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js +270 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate.d.ts +357 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js +418 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js.map +1 -0
- package/dist/vendor/harness-reflex/core/policy.d.ts +122 -0
- package/dist/vendor/harness-reflex/core/policy.js +102 -0
- package/dist/vendor/harness-reflex/core/policy.js.map +1 -0
- package/dist/vendor/harness-reflex/core/prune-plan.d.ts +141 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js +390 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js.map +1 -0
- package/dist/vendor/harness-reflex/core/text.d.ts +36 -0
- package/dist/vendor/harness-reflex/core/text.js +66 -0
- package/dist/vendor/harness-reflex/core/text.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/audit.d.ts +18 -0
- package/dist/vendor/harness-reflex/ports/audit.js +11 -0
- package/dist/vendor/harness-reflex/ports/audit.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/clock.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/clock.js +11 -0
- package/dist/vendor/harness-reflex/ports/clock.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/decision.d.ts +75 -0
- package/dist/vendor/harness-reflex/ports/decision.js +2 -0
- package/dist/vendor/harness-reflex/ports/decision.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/index.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/index.js +2 -0
- package/dist/vendor/harness-reflex/ports/index.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/log.d.ts +22 -0
- package/dist/vendor/harness-reflex/ports/log.js +12 -0
- package/dist/vendor/harness-reflex/ports/log.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/state.d.ts +46 -0
- package/dist/vendor/harness-reflex/ports/state.js +13 -0
- package/dist/vendor/harness-reflex/ports/state.js.map +1 -0
- package/package.json +25 -13
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { spendJudgment, usefulVerdict } from './policy.js';
|
|
2
|
+
import { estimateTokens } from './text.js';
|
|
3
|
+
/**
|
|
4
|
+
* Count the identical trailing repeats of one signature.
|
|
5
|
+
* @param steps - observed steps, oldest first.
|
|
6
|
+
* @param signature - the identity to count.
|
|
7
|
+
* @returns the length of the trailing run of that signature.
|
|
8
|
+
*/
|
|
9
|
+
export function countTrailingRepeats(steps, signature) {
|
|
10
|
+
let count = 0;
|
|
11
|
+
for (let index = steps.length - 1; index >= 0; index -= 1) {
|
|
12
|
+
if (steps[index].signature !== signature)
|
|
13
|
+
break;
|
|
14
|
+
count += 1;
|
|
15
|
+
}
|
|
16
|
+
return count;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Count the trailing consecutive failures.
|
|
20
|
+
* @param steps - observed steps, oldest first.
|
|
21
|
+
* @returns the length of the trailing run of failing steps.
|
|
22
|
+
*/
|
|
23
|
+
export function countTrailingFailures(steps) {
|
|
24
|
+
let count = 0;
|
|
25
|
+
for (let index = steps.length - 1; index >= 0; index -= 1) {
|
|
26
|
+
if (!steps[index].failed)
|
|
27
|
+
break;
|
|
28
|
+
count += 1;
|
|
29
|
+
}
|
|
30
|
+
return count;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Whether the window's tail alternates between exactly two call identities.
|
|
34
|
+
*
|
|
35
|
+
* `A B A B` is the cheapest loop to miss and among the most wasteful to run:
|
|
36
|
+
* neither call repeats consecutively, so a consecutive-repeat trigger never
|
|
37
|
+
* fires.
|
|
38
|
+
* @param steps - observed steps, oldest first.
|
|
39
|
+
* @param window - how many trailing steps to inspect.
|
|
40
|
+
* @returns whether the tail oscillates.
|
|
41
|
+
*/
|
|
42
|
+
export function detectOscillation(steps, window) {
|
|
43
|
+
const tail = steps.slice(Math.max(0, steps.length - window));
|
|
44
|
+
if (tail.length < 4)
|
|
45
|
+
return false;
|
|
46
|
+
const signatures = new Set(tail.map((step) => step.signature));
|
|
47
|
+
if (signatures.size !== 2)
|
|
48
|
+
return false;
|
|
49
|
+
for (let index = 2; index < tail.length; index += 1) {
|
|
50
|
+
if (tail[index].signature !== tail[index - 2].signature)
|
|
51
|
+
return false;
|
|
52
|
+
}
|
|
53
|
+
return true;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Decide, locally and deterministically, whether a judgment is worth spending.
|
|
57
|
+
*
|
|
58
|
+
* This is the cost gate of the whole surface: the expensive path is a System 1
|
|
59
|
+
* call, and it only opens when the *cheap* path already sees a pattern. A single
|
|
60
|
+
* distinctive call is never judged, however large its output.
|
|
61
|
+
*
|
|
62
|
+
* @param steps - observed steps, oldest first.
|
|
63
|
+
* @param options - thresholds, window, and the current call identity.
|
|
64
|
+
* @returns the suspicion, with `suspicious: false` when nothing justifies a call.
|
|
65
|
+
*/
|
|
66
|
+
export function suspicionOf(steps, options) {
|
|
67
|
+
const window = steps.slice(Math.max(0, steps.length - options.window));
|
|
68
|
+
const repeats = countTrailingRepeats(window, options.signature);
|
|
69
|
+
if (repeats >= options.repeatThreshold) {
|
|
70
|
+
return { suspicious: true, pattern: 'repetition', note: `identical call repeated ${repeats}x`, repeats };
|
|
71
|
+
}
|
|
72
|
+
const failures = countTrailingFailures(window);
|
|
73
|
+
if (failures >= options.failureThreshold) {
|
|
74
|
+
return { suspicious: true, pattern: 'failing_retry', note: `${failures} consecutive failing steps`, repeats: failures };
|
|
75
|
+
}
|
|
76
|
+
if (detectOscillation(window, options.window)) {
|
|
77
|
+
return { suspicious: true, pattern: 'oscillation', note: `two calls alternating over ${window.length} steps`, repeats: window.length };
|
|
78
|
+
}
|
|
79
|
+
return { suspicious: false, note: 'no local pattern', repeats: 0 };
|
|
80
|
+
}
|
|
81
|
+
/** The verdict that stands in when no judgment could be spent. */
|
|
82
|
+
export const EMPTY_VERDICT = { isStuck: false, confidence: 0, latencyMs: 0 };
|
|
83
|
+
/** A fresh, zeroed cost bucket. */
|
|
84
|
+
export function emptyBucket() {
|
|
85
|
+
return {
|
|
86
|
+
plans: 0,
|
|
87
|
+
applied: 0,
|
|
88
|
+
judgments: 0,
|
|
89
|
+
memoHits: 0,
|
|
90
|
+
localLatencyMs: 0,
|
|
91
|
+
remoteLatencyMs: 0,
|
|
92
|
+
judgeTokens: 0,
|
|
93
|
+
originalTokens: 0,
|
|
94
|
+
candidateTokens: 0,
|
|
95
|
+
potentialSavedTokens: 0,
|
|
96
|
+
actualSavedTokens: 0,
|
|
97
|
+
injectedTokens: 0
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Add one charge to one bucket.
|
|
102
|
+
*
|
|
103
|
+
* Every counter has exactly one writer, so a reader can add the parts up without
|
|
104
|
+
* meeting a number twice.
|
|
105
|
+
* @param bucket - the bucket to bill.
|
|
106
|
+
* @param plans - decisions planned by this charge.
|
|
107
|
+
* @param applied - decisions applied by this charge.
|
|
108
|
+
* @param charge - the token/latency/decision counts.
|
|
109
|
+
*/
|
|
110
|
+
export function applyCharge(bucket, plans, applied, charge) {
|
|
111
|
+
bucket.plans += plans;
|
|
112
|
+
bucket.applied += applied;
|
|
113
|
+
bucket.judgments += charge.judgments ?? 0;
|
|
114
|
+
bucket.memoHits += charge.memoHits ?? 0;
|
|
115
|
+
bucket.localLatencyMs += charge.localLatencyMs ?? 0;
|
|
116
|
+
bucket.remoteLatencyMs += charge.remoteLatencyMs ?? 0;
|
|
117
|
+
bucket.judgeTokens += charge.judgeTokens ?? 0;
|
|
118
|
+
bucket.originalTokens += charge.originalTokens ?? 0;
|
|
119
|
+
bucket.candidateTokens += charge.candidateTokens ?? 0;
|
|
120
|
+
bucket.potentialSavedTokens += charge.potentialSavedTokens ?? 0;
|
|
121
|
+
bucket.actualSavedTokens += charge.actualSavedTokens ?? 0;
|
|
122
|
+
bucket.injectedTokens += charge.injectedTokens ?? 0;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* The memo key of one judgment: the question plus the trailing window it is
|
|
126
|
+
* asked about.
|
|
127
|
+
* @param goal - the wait/context question, when one was asked.
|
|
128
|
+
* @param steps - the window.
|
|
129
|
+
* @param repeatThreshold - how many trailing signatures identify the window.
|
|
130
|
+
* @returns a stable key.
|
|
131
|
+
*/
|
|
132
|
+
export function judgmentKey(goal, steps, repeatThreshold) {
|
|
133
|
+
return `${goal ?? ''}\u0000${steps
|
|
134
|
+
.slice(-Math.max(1, repeatThreshold))
|
|
135
|
+
.map((step) => step.signature)
|
|
136
|
+
.join('|')}`;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* The one purchase a judgment makes, from whichever channel the caller used.
|
|
140
|
+
* @param buy - the current channel: one call, one step.
|
|
141
|
+
* @param backend - the deprecated channel: the service itself.
|
|
142
|
+
* @returns the purchase to run.
|
|
143
|
+
* @throws Error when a caller supplied neither, which is a programming error.
|
|
144
|
+
*/
|
|
145
|
+
function purchaseOf(buy, backend) {
|
|
146
|
+
if (buy !== undefined)
|
|
147
|
+
return buy;
|
|
148
|
+
if (backend === undefined) {
|
|
149
|
+
throw new Error('runJudgment needs a purchase: pass buy(step)');
|
|
150
|
+
}
|
|
151
|
+
return (step) => backend.check(step.goal, step.history);
|
|
152
|
+
}
|
|
153
|
+
/** The zero-cost verdict of a judgment that could not be spent. */
|
|
154
|
+
function noJudgment(skip) {
|
|
155
|
+
return {
|
|
156
|
+
useful: false,
|
|
157
|
+
paid: false,
|
|
158
|
+
reused: false,
|
|
159
|
+
judgeTokens: 0,
|
|
160
|
+
localLatencyMs: 0,
|
|
161
|
+
remoteLatencyMs: 0,
|
|
162
|
+
skip,
|
|
163
|
+
response: EMPTY_VERDICT
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Ask for one stagnation verdict, reusing this turn's answer when the window is
|
|
168
|
+
* the same one.
|
|
169
|
+
*
|
|
170
|
+
* The question is the trailing window plus the context it is asked in, so the
|
|
171
|
+
* answer is cached against both: the same episode is never judged twice, while
|
|
172
|
+
* a *different* episode or a different wait context in the same turn is a new
|
|
173
|
+
* question — and therefore subject to the turn's budget.
|
|
174
|
+
*
|
|
175
|
+
* The purchase is this function's, not the host's: `buy` is called only after
|
|
176
|
+
* the memo missed, after both budgets admitted the question, and after
|
|
177
|
+
* {@link spendJudgment} booked the slot. A host that was handed the transport
|
|
178
|
+
* instead would have to reproduce that order, and the one place a wrong answer is
|
|
179
|
+
* a model-visible regression is the place the type would stop helping.
|
|
180
|
+
*
|
|
181
|
+
* @param args - state, policy, the host's `buy`, clock, window, question, and
|
|
182
|
+
* abort signal.
|
|
183
|
+
* @returns the outcome, including why a judgment was refused.
|
|
184
|
+
*/
|
|
185
|
+
export async function runJudgment(args) {
|
|
186
|
+
const { state, policy, clock, steps, goal, signal } = args;
|
|
187
|
+
const buy = purchaseOf(args.buy, args.backend);
|
|
188
|
+
const key = judgmentKey(goal, steps, policy.repeatThreshold);
|
|
189
|
+
const cached = state.verdictTurn === state.turn && state.verdictKey === key ? state.verdict : undefined;
|
|
190
|
+
if (cached) {
|
|
191
|
+
return {
|
|
192
|
+
useful: usefulVerdict(cached, policy),
|
|
193
|
+
paid: false,
|
|
194
|
+
reused: true,
|
|
195
|
+
judgeTokens: 0,
|
|
196
|
+
localLatencyMs: 0,
|
|
197
|
+
remoteLatencyMs: 0,
|
|
198
|
+
response: cached
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
if (state.judgmentsCount >= policy.maxJudgmentsPerTurn)
|
|
202
|
+
return noJudgment('judgment-turn-cap');
|
|
203
|
+
if (state.judgmentsSession >= policy.maxJudgmentsPerSession)
|
|
204
|
+
return noJudgment('judgment-session-cap');
|
|
205
|
+
if (signal?.aborted)
|
|
206
|
+
return noJudgment('aborted');
|
|
207
|
+
spendJudgment(state, policy);
|
|
208
|
+
const history = steps.map((step) => ({
|
|
209
|
+
tool: step.tool,
|
|
210
|
+
input: step.input,
|
|
211
|
+
...(step.output ? { output: step.output } : {}),
|
|
212
|
+
...(step.error ? { error: step.error } : {}),
|
|
213
|
+
timestamp: step.at
|
|
214
|
+
}));
|
|
215
|
+
const judgeTokens = history.reduce((sum, step) => sum + estimateTokens(`${step.tool}${step.input}${step.output ?? ''}${step.error ?? ''}`), 0);
|
|
216
|
+
const started = clock.now();
|
|
217
|
+
const response = await buy({ goal, history });
|
|
218
|
+
const remoteLatencyMs = Number.isFinite(response.latencyMs) ? response.latencyMs : 0;
|
|
219
|
+
state.verdict = response;
|
|
220
|
+
state.verdictTurn = state.turn;
|
|
221
|
+
state.verdictKey = key;
|
|
222
|
+
return {
|
|
223
|
+
useful: usefulVerdict(response, policy),
|
|
224
|
+
paid: true,
|
|
225
|
+
reused: false,
|
|
226
|
+
judgeTokens,
|
|
227
|
+
localLatencyMs: Math.max(0, clock.now() - started - remoteLatencyMs),
|
|
228
|
+
remoteLatencyMs,
|
|
229
|
+
response
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* The charge of one judgment, so every judgment is billed exactly once.
|
|
234
|
+
* @param verdict - the outcome of the judgment call.
|
|
235
|
+
* @param started - clock reading at hook entry.
|
|
236
|
+
* @param finished - clock reading now.
|
|
237
|
+
* @returns the charge.
|
|
238
|
+
*/
|
|
239
|
+
export function judgmentCharge(verdict, started, finished) {
|
|
240
|
+
if (!verdict.paid) {
|
|
241
|
+
return { judgments: 0, memoHits: verdict.reused ? 1 : 0, localLatencyMs: 0, remoteLatencyMs: 0, judgeTokens: 0 };
|
|
242
|
+
}
|
|
243
|
+
return {
|
|
244
|
+
judgments: 1,
|
|
245
|
+
memoHits: 0,
|
|
246
|
+
localLatencyMs: Math.max(verdict.localLatencyMs, Math.max(0, finished - started - verdict.remoteLatencyMs)),
|
|
247
|
+
remoteLatencyMs: verdict.remoteLatencyMs,
|
|
248
|
+
judgeTokens: verdict.judgeTokens
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
//# sourceMappingURL=judge.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"judge.js","sourceRoot":"","sources":["../../../../src/vendor/harness-reflex/core/judge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The deterministic pre-trigger, the judgment call, and the cost accounting.\n *\n * The expensive path of every capability is one System 1 judgment. This module\n * owns the cheap path that decides whether a judgment is worth buying, the\n * once-per-turn call itself (memoized by the window it is about), and the\n * bookkeeping that bills exactly one judgment per call. The transport arrives as\n * one `buy(step)` callback and never as the service itself; the clock is a\n * {@link ClockPort}; neither is imported from a host.\n *\n * @module core/judge\n */\nimport type { ActionStep, StagnationCheckResponse } from '../backend/types.js';\nimport type { ClockPort } from '../ports/clock.js';\nimport type { StagnationBackendPort } from '../ports/decision.js';\nimport type { JudgmentState, JudgmentStep } from './orchestrate-host.js';\nimport type { PolicySnapshot } from './policy.js';\nimport { spendJudgment, usefulVerdict } from './policy.js';\nimport { estimateTokens } from './text.js';\n\n/** One step of one agent's detection window. */\nexport interface ObservedStep {\n /** `tool:argumentsDigest` — the identity a repetition is measured on. */\n signature: string;\n tool: string;\n input: string;\n output: string;\n error: string;\n failed: boolean;\n turn: number;\n at: number;\n /** Whether the step was a legitimate wait query rather than progress. */\n wait?: boolean;\n}\n\n/** Why a deterministic pre-trigger wants a judgment. */\nexport interface StagnationSuspicion {\n suspicious: boolean;\n /** The pattern the trigger suspects, before System 1 confirms it. */\n pattern?: 'repetition' | 'oscillation' | 'failing_retry';\n /** Human-readable trigger facts, for the audit record. */\n note: string;\n /** How many steps the pattern was measured on. */\n repeats: number;\n}\n\n/**\n * Count the identical trailing repeats of one signature.\n * @param steps - observed steps, oldest first.\n * @param signature - the identity to count.\n * @returns the length of the trailing run of that signature.\n */\nexport function countTrailingRepeats(steps: readonly ObservedStep[], signature: string): number {\n let count = 0;\n for (let index = steps.length - 1; index >= 0; index -= 1) {\n if (steps[index]!.signature !== signature) break;\n count += 1;\n }\n return count;\n}\n\n/**\n * Count the trailing consecutive failures.\n * @param steps - observed steps, oldest first.\n * @returns the length of the trailing run of failing steps.\n */\nexport function countTrailingFailures(steps: readonly ObservedStep[]): number {\n let count = 0;\n for (let index = steps.length - 1; index >= 0; index -= 1) {\n if (!steps[index]!.failed) break;\n count += 1;\n }\n return count;\n}\n\n/**\n * Whether the window's tail alternates between exactly two call identities.\n *\n * `A B A B` is the cheapest loop to miss and among the most wasteful to run:\n * neither call repeats consecutively, so a consecutive-repeat trigger never\n * fires.\n * @param steps - observed steps, oldest first.\n * @param window - how many trailing steps to inspect.\n * @returns whether the tail oscillates.\n */\nexport function detectOscillation(steps: readonly ObservedStep[], window: number): boolean {\n const tail = steps.slice(Math.max(0, steps.length - window));\n if (tail.length < 4) return false;\n const signatures = new Set(tail.map((step) => step.signature));\n if (signatures.size !== 2) return false;\n for (let index = 2; index < tail.length; index += 1) {\n if (tail[index]!.signature !== tail[index - 2]!.signature) return false;\n }\n return true;\n}\n\n/**\n * Decide, locally and deterministically, whether a judgment is worth spending.\n *\n * This is the cost gate of the whole surface: the expensive path is a System 1\n * call, and it only opens when the *cheap* path already sees a pattern. A single\n * distinctive call is never judged, however large its output.\n *\n * @param steps - observed steps, oldest first.\n * @param options - thresholds, window, and the current call identity.\n * @returns the suspicion, with `suspicious: false` when nothing justifies a call.\n */\nexport function suspicionOf(\n steps: readonly ObservedStep[],\n options: { repeatThreshold: number; failureThreshold: number; window: number; signature: string }\n): StagnationSuspicion {\n const window = steps.slice(Math.max(0, steps.length - options.window));\n const repeats = countTrailingRepeats(window, options.signature);\n if (repeats >= options.repeatThreshold) {\n return { suspicious: true, pattern: 'repetition', note: `identical call repeated ${repeats}x`, repeats };\n }\n const failures = countTrailingFailures(window);\n if (failures >= options.failureThreshold) {\n return { suspicious: true, pattern: 'failing_retry', note: `${failures} consecutive failing steps`, repeats: failures };\n }\n if (detectOscillation(window, options.window)) {\n return { suspicious: true, pattern: 'oscillation', note: `two calls alternating over ${window.length} steps`, repeats: window.length };\n }\n return { suspicious: false, note: 'no local pattern', repeats: 0 };\n}\n\n/** The verdict that stands in when no judgment could be spent. */\nexport const EMPTY_VERDICT: StagnationCheckResponse = { isStuck: false, confidence: 0, latencyMs: 0 };\n\n/** What one judgment cost, charged exactly once per judgment. */\nexport interface JudgmentCharge {\n judgments: number;\n memoHits: number;\n localLatencyMs: number;\n remoteLatencyMs: number;\n judgeTokens: number;\n}\n\n/** One token and latency account of a mode or a capability. */\nexport interface InterventionCostBucket {\n /** Decisions planned. */\n plans: number;\n /** Decisions whose plan was executed. */\n applied: number;\n /** System 1 judgments paid for. */\n judgments: number;\n /** Judgments served from the per-turn verdict memo instead of a new call. */\n memoHits: number;\n /** Milliseconds spent in local, deterministic work. */\n localLatencyMs: number;\n /** Milliseconds spent waiting for System 1. */\n remoteLatencyMs: number;\n /** Tokens the judgments reasoned about. */\n judgeTokens: number;\n /** Tokens of the payloads decisions were made about. */\n originalTokens: number;\n /** Tokens the candidates would carry. */\n candidateTokens: number;\n /** Tokens the candidates would have saved. */\n potentialSavedTokens: number;\n /** Tokens actually removed from the model-visible surface. */\n actualSavedTokens: number;\n /** Tokens actually added to the model-visible surface. */\n injectedTokens: number;\n}\n\n/** A fresh, zeroed cost bucket. */\nexport function emptyBucket(): InterventionCostBucket {\n return {\n plans: 0,\n applied: 0,\n judgments: 0,\n memoHits: 0,\n localLatencyMs: 0,\n remoteLatencyMs: 0,\n judgeTokens: 0,\n originalTokens: 0,\n candidateTokens: 0,\n potentialSavedTokens: 0,\n actualSavedTokens: 0,\n injectedTokens: 0\n };\n}\n\n/** One charge against a mode's and a capability's account. */\nexport interface CostCharge {\n judgments?: number;\n memoHits?: number;\n localLatencyMs?: number;\n remoteLatencyMs?: number;\n judgeTokens?: number;\n originalTokens?: number;\n candidateTokens?: number;\n potentialSavedTokens?: number;\n actualSavedTokens?: number;\n injectedTokens?: number;\n}\n\n/**\n * Add one charge to one bucket.\n *\n * Every counter has exactly one writer, so a reader can add the parts up without\n * meeting a number twice.\n * @param bucket - the bucket to bill.\n * @param plans - decisions planned by this charge.\n * @param applied - decisions applied by this charge.\n * @param charge - the token/latency/decision counts.\n */\nexport function applyCharge(\n bucket: InterventionCostBucket,\n plans: number,\n applied: number,\n charge: CostCharge\n): void {\n bucket.plans += plans;\n bucket.applied += applied;\n bucket.judgments += charge.judgments ?? 0;\n bucket.memoHits += charge.memoHits ?? 0;\n bucket.localLatencyMs += charge.localLatencyMs ?? 0;\n bucket.remoteLatencyMs += charge.remoteLatencyMs ?? 0;\n bucket.judgeTokens += charge.judgeTokens ?? 0;\n bucket.originalTokens += charge.originalTokens ?? 0;\n bucket.candidateTokens += charge.candidateTokens ?? 0;\n bucket.potentialSavedTokens += charge.potentialSavedTokens ?? 0;\n bucket.actualSavedTokens += charge.actualSavedTokens ?? 0;\n bucket.injectedTokens += charge.injectedTokens ?? 0;\n}\n\n/** The state one judgment memo and the two budgets live in. */\nexport interface VerdictMemoState extends JudgmentState {\n verdictTurn: number;\n /** Identity of the window the cached verdict was about. */\n verdictKey: string;\n verdict?: StagnationCheckResponse;\n}\n\n/** The outcome of one judgment request. */\nexport interface JudgmentOutcome {\n useful: boolean;\n paid: boolean;\n reused: boolean;\n judgeTokens: number;\n localLatencyMs: number;\n remoteLatencyMs: number;\n skip?: string;\n response: StagnationCheckResponse;\n}\n\n/**\n * The memo key of one judgment: the question plus the trailing window it is\n * asked about.\n * @param goal - the wait/context question, when one was asked.\n * @param steps - the window.\n * @param repeatThreshold - how many trailing signatures identify the window.\n * @returns a stable key.\n */\nexport function judgmentKey(goal: string | undefined, steps: readonly ObservedStep[], repeatThreshold: number): string {\n return `${goal ?? ''}\\u0000${steps\n .slice(-Math.max(1, repeatThreshold))\n .map((step) => step.signature)\n .join('|')}`;\n}\n\n/**\n * The one purchase a judgment makes, from whichever channel the caller used.\n * @param buy - the current channel: one call, one step.\n * @param backend - the deprecated channel: the service itself.\n * @returns the purchase to run.\n * @throws Error when a caller supplied neither, which is a programming error.\n */\nfunction purchaseOf(\n buy: ((step: JudgmentStep) => Promise<StagnationCheckResponse>) | undefined,\n backend: StagnationBackendPort | undefined\n): (step: JudgmentStep) => Promise<StagnationCheckResponse> {\n if (buy !== undefined) return buy;\n if (backend === undefined) {\n throw new Error('runJudgment needs a purchase: pass buy(step)');\n }\n return (step) => backend.check(step.goal, step.history);\n}\n\n/** The zero-cost verdict of a judgment that could not be spent. */\nfunction noJudgment(skip: string): JudgmentOutcome {\n return {\n useful: false,\n paid: false,\n reused: false,\n judgeTokens: 0,\n localLatencyMs: 0,\n remoteLatencyMs: 0,\n skip,\n response: EMPTY_VERDICT\n };\n}\n\n/**\n * Ask for one stagnation verdict, reusing this turn's answer when the window is\n * the same one.\n *\n * The question is the trailing window plus the context it is asked in, so the\n * answer is cached against both: the same episode is never judged twice, while\n * a *different* episode or a different wait context in the same turn is a new\n * question — and therefore subject to the turn's budget.\n *\n * The purchase is this function's, not the host's: `buy` is called only after\n * the memo missed, after both budgets admitted the question, and after\n * {@link spendJudgment} booked the slot. A host that was handed the transport\n * instead would have to reproduce that order, and the one place a wrong answer is\n * a model-visible regression is the place the type would stop helping.\n *\n * @param args - state, policy, the host's `buy`, clock, window, question, and\n * abort signal.\n * @returns the outcome, including why a judgment was refused.\n */\nexport async function runJudgment(args: {\n state: VerdictMemoState;\n policy: PolicySnapshot;\n /** One purchase: ask the service about one step, and report what it cost. */\n buy?: (step: JudgmentStep) => Promise<StagnationCheckResponse>;\n /**\n * The pre-g-046 channel: a service handed over whole, instead of a purchase.\n *\n * Kept **only** for the frozen parity snapshot\n * (`packages/dsh-harness-reflex/src/baseline/interventions.ts`), which is the\n * oracle of the refactor and may not be touched. Every live caller passes\n * {@link buy}; the snapshot's `#judge` still passes its composition's service,\n * and the parity run therefore keeps this channel exercised.\n *\n * @deprecated Pass `buy`. Nothing added from now on should use this.\n */\n backend?: StagnationBackendPort;\n clock: ClockPort;\n steps: readonly ObservedStep[];\n goal?: string;\n signal?: AbortSignal;\n}): Promise<JudgmentOutcome> {\n const { state, policy, clock, steps, goal, signal } = args;\n const buy = purchaseOf(args.buy, args.backend);\n const key = judgmentKey(goal, steps, policy.repeatThreshold);\n const cached = state.verdictTurn === state.turn && state.verdictKey === key ? state.verdict : undefined;\n if (cached) {\n return {\n useful: usefulVerdict(cached, policy),\n paid: false,\n reused: true,\n judgeTokens: 0,\n localLatencyMs: 0,\n remoteLatencyMs: 0,\n response: cached\n };\n }\n if (state.judgmentsCount >= policy.maxJudgmentsPerTurn) return noJudgment('judgment-turn-cap');\n if (state.judgmentsSession >= policy.maxJudgmentsPerSession) return noJudgment('judgment-session-cap');\n if (signal?.aborted) return noJudgment('aborted');\n spendJudgment(state, policy);\n\n const history: ActionStep[] = steps.map((step) => ({\n tool: step.tool,\n input: step.input,\n ...(step.output ? { output: step.output } : {}),\n ...(step.error ? { error: step.error } : {}),\n timestamp: step.at\n }));\n const judgeTokens = history.reduce(\n (sum, step) => sum + estimateTokens(`${step.tool}${step.input}${step.output ?? ''}${step.error ?? ''}`),\n 0\n );\n const started = clock.now();\n const response = await buy({ goal, history });\n const remoteLatencyMs = Number.isFinite(response.latencyMs) ? response.latencyMs : 0;\n state.verdict = response;\n state.verdictTurn = state.turn;\n state.verdictKey = key;\n return {\n useful: usefulVerdict(response, policy),\n paid: true,\n reused: false,\n judgeTokens,\n localLatencyMs: Math.max(0, clock.now() - started - remoteLatencyMs),\n remoteLatencyMs,\n response\n };\n}\n\n/**\n * The charge of one judgment, so every judgment is billed exactly once.\n * @param verdict - the outcome of the judgment call.\n * @param started - clock reading at hook entry.\n * @param finished - clock reading now.\n * @returns the charge.\n */\nexport function judgmentCharge(\n verdict: Pick<JudgmentOutcome, 'paid' | 'reused' | 'judgeTokens' | 'localLatencyMs' | 'remoteLatencyMs'>,\n started: number,\n finished: number\n): JudgmentCharge {\n if (!verdict.paid) {\n return { judgments: 0, memoHits: verdict.reused ? 1 : 0, localLatencyMs: 0, remoteLatencyMs: 0, judgeTokens: 0 };\n }\n return {\n judgments: 1,\n memoHits: 0,\n localLatencyMs: Math.max(verdict.localLatencyMs, Math.max(0, finished - started - verdict.remoteLatencyMs)),\n remoteLatencyMs: verdict.remoteLatencyMs,\n judgeTokens: verdict.judgeTokens\n };\n}\n"]}
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shared orchestration of the closing check.
|
|
3
|
+
*
|
|
4
|
+
* The fourth and last lift: {@link ./orchestrate} owns when a result is reduced,
|
|
5
|
+
* {@link ./orchestrate-stagnation} owns when a call is refused and when a step is
|
|
6
|
+
* corrected, {@link ./orchestrate-correction} owns what happens to a result that
|
|
7
|
+
* failed — and this one owns what happens when a turn is about to *close* while
|
|
8
|
+
* its own words claim success the evidence does not support.
|
|
9
|
+
*
|
|
10
|
+
* ```
|
|
11
|
+
* agent/turn-stopping
|
|
12
|
+
* → off, or the host is not serving this capability → nothing at all
|
|
13
|
+
* → the turn said nothing, or no evidence is a failure → not suspicious, nothing at all
|
|
14
|
+
* → no candidate sentence → nothing at all
|
|
15
|
+
* → already latched for this turn → duplicate-intervention
|
|
16
|
+
* → the turn's action allowance is spent → intervention-cap
|
|
17
|
+
* → the caller's signal is aborted → nothing at all
|
|
18
|
+
* → assemble the evidence; truncation is NOTED and the decision continues
|
|
19
|
+
* → buy the classification (turn/session budgets inside)
|
|
20
|
+
* → the classifier could not answer → closing-claim-unavailable (fail open, locally)
|
|
21
|
+
* → nothing really claims completion → closing-no-claim (and the charge is kept)
|
|
22
|
+
* → buy the verification (same judgment, second request)
|
|
23
|
+
* → nothing contradicted → closing-undecided / closing-unconfirmed / closing-evidence-consistent
|
|
24
|
+
* → latch the turn, book the action, conclude
|
|
25
|
+
* → [the host steers the objection into the turn, in active mode only]
|
|
26
|
+
* → a failure anywhere after that → planning-error (fail open)
|
|
27
|
+
* ```
|
|
28
|
+
*
|
|
29
|
+
* ## What is shared and what is not
|
|
30
|
+
*
|
|
31
|
+
* Shared here: the order above, every skip reason, the budget rules, the two
|
|
32
|
+
* per-turn latches, the shape of the audit detail, and the decision that active
|
|
33
|
+
* mode asks its host to steer.
|
|
34
|
+
*
|
|
35
|
+
* *Not* shared here: the act of steering (that is `HostClosingPort#steer`), the
|
|
36
|
+
* wording the model reads (`#describe`), the storage of the evidence counters
|
|
37
|
+
* (`#noteEvidence`), and the accumulation of the turn's own words — a host that
|
|
38
|
+
* reads them from a stream and a host that reads them from a transcript both hand
|
|
39
|
+
* over the same string.
|
|
40
|
+
*
|
|
41
|
+
* ## The two judgments are one decision
|
|
42
|
+
*
|
|
43
|
+
* The closing check buys **two** requests from one capability: a classification
|
|
44
|
+
* of the turn's candidate sentences, and a verification of the claims that
|
|
45
|
+
* classification accepted. They are one logical judgment — the classification
|
|
46
|
+
* decides *whether* anything is worth verifying — so both are charged against the
|
|
47
|
+
* single slot the turn budget allowed, and both are billed as one
|
|
48
|
+
* {@link ClosingJudgment}. That fold is why this port states its two *purchases*
|
|
49
|
+
* ({@link HostClosingPort#classify} and {@link HostClosingPort#verify}) and never
|
|
50
|
+
* the transport behind them: a caller holding the service would have to
|
|
51
|
+
* re-implement the purchase, the memo, the latency split and the billing, and the
|
|
52
|
+
* one-charge rule is only stateable where the charge is built. It stays here.
|
|
53
|
+
*
|
|
54
|
+
* ## The skip that does not return
|
|
55
|
+
*
|
|
56
|
+
* Every skip in the other three modules ends the decision. `evidence-truncated`
|
|
57
|
+
* does not: the evidence was assembled with some of it dropped, the amount is
|
|
58
|
+
* reported, and the judgment proceeds on what survived. This module therefore
|
|
59
|
+
* distinguishes a *note* (`#note`, which records) from a *refusal* (`#refuse`,
|
|
60
|
+
* which records and returns). Collapsing the two would either stop the closing
|
|
61
|
+
* check whenever evidence is large, or lose the fact that it was truncated.
|
|
62
|
+
*
|
|
63
|
+
* ## A verdict that could not decide is not a contradiction
|
|
64
|
+
*
|
|
65
|
+
* `escalate` means the backend could not answer — an unavailable service degrades
|
|
66
|
+
* exactly this way. Steering a turn on an undecided verdict would turn a backend
|
|
67
|
+
* failure into a model-visible objection, so only `contradicted` results steer;
|
|
68
|
+
* `escalate` gets its own reason (`closing-undecided`) precisely so a run can tell
|
|
69
|
+
* "the evidence was fine" from "nobody looked".
|
|
70
|
+
*
|
|
71
|
+
* @module core/orchestrate-closing
|
|
72
|
+
*/
|
|
73
|
+
import { type EvidenceEntry } from './evidence.js';
|
|
74
|
+
import type { HostBillingPort, HostDecisionPort, JudgmentCost, JudgmentPosition } from './orchestrate-host.js';
|
|
75
|
+
/** The capability every decision in this module belongs to. */
|
|
76
|
+
export declare const CLOSING_CAPABILITY: "closing";
|
|
77
|
+
/** The audit action an objection is recorded under. */
|
|
78
|
+
export declare const CLOSING_ACTION: "steer-closing";
|
|
79
|
+
/**
|
|
80
|
+
* The two latches this decision keeps, both keyed by turn rather than by identity.
|
|
81
|
+
*
|
|
82
|
+
* The other capabilities latch by *signature* — one repeated call is one episode.
|
|
83
|
+
* A closing check has no such identity: the episode is the turn itself, so the
|
|
84
|
+
* key is `closing:turn:<n>` and it is the host's storage that has to keep it.
|
|
85
|
+
*/
|
|
86
|
+
export declare const CLOSING_LATCH: {
|
|
87
|
+
/** The turn was already objected to (or observed) — never twice per turn. */
|
|
88
|
+
readonly applied: (turn: number) => string;
|
|
89
|
+
/** The memo namespace of the verification request, so a replay is free. */
|
|
90
|
+
readonly verdictKey: (agent: string, turn: number) => string;
|
|
91
|
+
};
|
|
92
|
+
/** One planned objection, as the host records it. */
|
|
93
|
+
export interface ClosingPlanRecord {
|
|
94
|
+
readonly capability: typeof CLOSING_CAPABILITY;
|
|
95
|
+
readonly action: typeof CLOSING_ACTION;
|
|
96
|
+
readonly reason: string;
|
|
97
|
+
feedback: string;
|
|
98
|
+
readonly detail: Record<string, unknown>;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* The judgment one closing check rode on.
|
|
102
|
+
*
|
|
103
|
+
* Both requests are folded into one charge on purpose: the turn budget bought one
|
|
104
|
+
* slot, and a reader of the account must not see two slots spent for one decision.
|
|
105
|
+
* `localLatencyMs` is the wait the two requests cost in this process; the two
|
|
106
|
+
* remote times are summed because the model was asked two questions.
|
|
107
|
+
*/
|
|
108
|
+
export interface ClosingJudgment extends JudgmentCost {
|
|
109
|
+
}
|
|
110
|
+
/** What one closing check turned out to be. */
|
|
111
|
+
export type ClosingAction = 'objected' | 'pass-through';
|
|
112
|
+
/** What one orchestrated closing check produced. */
|
|
113
|
+
export interface ClosingOutcome {
|
|
114
|
+
/** What the capability was in force: a decision is only made when this is not `off`. */
|
|
115
|
+
readonly action: ClosingAction;
|
|
116
|
+
/** The reason the check did nothing, when it did nothing. */
|
|
117
|
+
readonly skip?: string;
|
|
118
|
+
/** Every skip reason this one check reported, in order (normally 0 or 1). */
|
|
119
|
+
readonly skips: readonly string[];
|
|
120
|
+
/** The objection, once the decision is to make one. */
|
|
121
|
+
readonly plan?: ClosingPlanRecord;
|
|
122
|
+
/** Whether the objection was really steered (active mode only). */
|
|
123
|
+
readonly applied: boolean;
|
|
124
|
+
/** The message to hand the model, when the host steers in active mode. */
|
|
125
|
+
readonly message?: string;
|
|
126
|
+
}
|
|
127
|
+
/** What the classification half answered. */
|
|
128
|
+
export interface ClaimClassificationLike {
|
|
129
|
+
readonly results: readonly {
|
|
130
|
+
readonly statement: string;
|
|
131
|
+
readonly isClaim: boolean;
|
|
132
|
+
readonly confidence: number;
|
|
133
|
+
}[];
|
|
134
|
+
readonly latencyMs: number;
|
|
135
|
+
}
|
|
136
|
+
/** What the verification half answered. */
|
|
137
|
+
export interface ClosingVerdictLike {
|
|
138
|
+
readonly passed: boolean;
|
|
139
|
+
readonly results: readonly {
|
|
140
|
+
readonly statement: string;
|
|
141
|
+
readonly outcome: string;
|
|
142
|
+
readonly confidence: number;
|
|
143
|
+
}[];
|
|
144
|
+
readonly latencyMs: number;
|
|
145
|
+
}
|
|
146
|
+
/** What the objection is built from, for the host's wording. */
|
|
147
|
+
export interface ClosingFeedbackFacts {
|
|
148
|
+
/** The contradicted statements, already clipped for quoting. */
|
|
149
|
+
readonly contradicted: readonly string[];
|
|
150
|
+
/** The turn that is closing. */
|
|
151
|
+
readonly turn: number;
|
|
152
|
+
}
|
|
153
|
+
/** Everything the shared layer cannot know by itself. */
|
|
154
|
+
export interface HostClosingPort extends HostDecisionPort, HostBillingPort<ClosingJudgment, ClosingPlanRecord> {
|
|
155
|
+
/** The effective mode of the `closing` capability. */
|
|
156
|
+
mode(): 'off' | 'observe' | 'active';
|
|
157
|
+
/**
|
|
158
|
+
* The turn's own words, as the stream carried them.
|
|
159
|
+
*
|
|
160
|
+
* The host accumulates them (`agent/assistant-stream` in DSH); the shared layer
|
|
161
|
+
* only asks for the string. An empty string means the turn said nothing, which
|
|
162
|
+
* is one of the four deterministic reasons nothing is bought.
|
|
163
|
+
*/
|
|
164
|
+
claims(): string;
|
|
165
|
+
/**
|
|
166
|
+
* Whether at least one retained evidence entry looks like a failure.
|
|
167
|
+
*
|
|
168
|
+
* A host computes this from its own reading of its results; the shared layer
|
|
169
|
+
* needs only the boolean, because *which* result failed is what the judgment
|
|
170
|
+
* reads, not what the trigger reads.
|
|
171
|
+
*/
|
|
172
|
+
evidenceSuspect(): boolean;
|
|
173
|
+
/** The evidence entries retained for this turn. */
|
|
174
|
+
evidence(): readonly EvidenceEntry[];
|
|
175
|
+
/** The evidence-assembly budget in force. */
|
|
176
|
+
evidenceBudget(): number;
|
|
177
|
+
/** Whether the caller's signal is already aborted (a cancelling turn). */
|
|
178
|
+
aborted(): boolean;
|
|
179
|
+
/** Whether this turn was already objected to (or observed) — the per-turn latch. */
|
|
180
|
+
alreadyObjected(): boolean;
|
|
181
|
+
/** Latch this turn as objected to. */
|
|
182
|
+
latchObjected(): void;
|
|
183
|
+
/** The identity the verification memo is namespaced by. */
|
|
184
|
+
agentId(): string;
|
|
185
|
+
/** The classification half of the one judgment. */
|
|
186
|
+
classify(request: {
|
|
187
|
+
readonly statements: readonly string[];
|
|
188
|
+
readonly context: string;
|
|
189
|
+
}): Promise<ClaimClassificationLike>;
|
|
190
|
+
/** The verification half of the same judgment. */
|
|
191
|
+
verify(claims: readonly {
|
|
192
|
+
readonly statement: string;
|
|
193
|
+
}[], evidence: string, options: {
|
|
194
|
+
readonly latchCacheKey: string;
|
|
195
|
+
}): Promise<ClosingVerdictLike>;
|
|
196
|
+
/** The confidence floor a classified sentence must clear to be a claim. */
|
|
197
|
+
claimMinConfidence(): number;
|
|
198
|
+
/** Word the objection the model reads. */
|
|
199
|
+
describe(facts: ClosingFeedbackFacts): string;
|
|
200
|
+
/** Hand the objection to the model. Only called in active mode. */
|
|
201
|
+
steer(message: string): void;
|
|
202
|
+
/** Record the evidence counters, which are engine-level rather than per-agent. */
|
|
203
|
+
noteEvidence(stats: {
|
|
204
|
+
readonly retainedChars: number;
|
|
205
|
+
readonly truncatedChars: number;
|
|
206
|
+
}): void;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* Decide whether the turn that is closing contradicts its own evidence, and tell
|
|
210
|
+
* the host what to do about it.
|
|
211
|
+
*
|
|
212
|
+
* The position is an *input of this decision*, not a port accessor and not a
|
|
213
|
+
* counter. The turn here is the boundary being closed, which can be a turn no
|
|
214
|
+
* step has recorded yet — a turn that said something and admitted no step — so it
|
|
215
|
+
* cannot be read off the running counters. `step` is the step the engine last
|
|
216
|
+
* recorded, which is the same number the audit detail has always quoted.
|
|
217
|
+
*
|
|
218
|
+
* @param invocation - where in the run this check is being made.
|
|
219
|
+
* @param port - everything the shared layer cannot know by itself.
|
|
220
|
+
* @returns what the check decided, and the message to steer when it applied.
|
|
221
|
+
*/
|
|
222
|
+
export declare function orchestrateClosing(invocation: {
|
|
223
|
+
readonly position: JudgmentPosition;
|
|
224
|
+
}, port: HostClosingPort): Promise<ClosingOutcome>;
|
|
225
|
+
/**
|
|
226
|
+
* The objection's wording, in the default form.
|
|
227
|
+
*
|
|
228
|
+
* Exported because a host that shows the text to the same audience may keep it
|
|
229
|
+
* verbatim; a host that words it differently supplies its own through the port.
|
|
230
|
+
* The statement clipping is the shared part: a contradicted claim is quoted at
|
|
231
|
+
* 160 characters with its whitespace collapsed, so a multi-line claim can never
|
|
232
|
+
* make the objection unbounded.
|
|
233
|
+
* @param facts - what the objection is built from.
|
|
234
|
+
* @param limit - the total character budget.
|
|
235
|
+
* @returns the text handed to the model.
|
|
236
|
+
*/
|
|
237
|
+
export declare function describeClosing(facts: ClosingFeedbackFacts, limit: number): string;
|