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/CHANGELOG.md +20 -0
- package/README.md +103 -23
- package/USER_GUIDE.md +121 -43
- package/dist/adapters/agy.js +1 -1
- package/dist/adapters/agy.js.map +1 -1
- package/dist/adapters/codex.d.ts +133 -4
- package/dist/adapters/codex.js +325 -2
- package/dist/adapters/codex.js.map +1 -1
- package/dist/backend/defaults.d.ts +31 -0
- package/dist/backend/defaults.js +32 -0
- package/dist/backend/defaults.js.map +1 -0
- package/dist/backend/jev.js +6 -5
- package/dist/backend/jev.js.map +1 -1
- package/dist/backend/mock.d.ts +12 -1
- package/dist/backend/mock.js +34 -0
- package/dist/backend/mock.js.map +1 -1
- package/dist/backend/simple-jev.js +5 -4
- package/dist/backend/simple-jev.js.map +1 -1
- package/dist/backend/types.d.ts +34 -0
- package/dist/backend/types.js.map +1 -1
- package/dist/cli/index.js +5 -3
- package/dist/cli/index.js.map +1 -1
- package/dist/core/closing.d.ts +90 -0
- package/dist/core/closing.js +111 -0
- package/dist/core/closing.js.map +1 -0
- package/dist/core/evidence.d.ts +119 -0
- package/dist/core/evidence.js +209 -0
- package/dist/core/evidence.js.map +1 -0
- package/dist/core/judge.d.ts +221 -0
- package/dist/core/judge.js +251 -0
- package/dist/core/judge.js.map +1 -0
- package/dist/core/orchestrate-closing.d.ts +237 -0
- package/dist/core/orchestrate-closing.js +250 -0
- package/dist/core/orchestrate-closing.js.map +1 -0
- package/dist/core/orchestrate-correction.d.ts +209 -0
- package/dist/core/orchestrate-correction.js +141 -0
- package/dist/core/orchestrate-correction.js.map +1 -0
- package/dist/core/orchestrate-host.d.ts +225 -0
- package/dist/core/orchestrate-host.js +80 -0
- package/dist/core/orchestrate-host.js.map +1 -0
- package/dist/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/core/orchestrate-stagnation.js +270 -0
- package/dist/core/orchestrate-stagnation.js.map +1 -0
- package/dist/core/orchestrate.d.ts +357 -0
- package/dist/core/orchestrate.js +418 -0
- package/dist/core/orchestrate.js.map +1 -0
- package/dist/core/policy.d.ts +122 -0
- package/dist/core/policy.js +102 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/prune-plan.d.ts +141 -0
- package/dist/core/prune-plan.js +390 -0
- package/dist/core/prune-plan.js.map +1 -0
- package/dist/core/score.d.ts +2 -2
- package/dist/core/score.js.map +1 -1
- package/dist/core/text.d.ts +36 -0
- package/dist/core/text.js +66 -0
- package/dist/core/text.js.map +1 -0
- package/dist/hook/cli.d.ts +9 -0
- package/dist/hook/cli.js +52 -0
- package/dist/hook/cli.js.map +1 -0
- package/dist/hook/contract.d.ts +125 -0
- package/dist/hook/contract.js +159 -0
- package/dist/hook/contract.js.map +1 -0
- package/dist/hook/decision.d.ts +97 -0
- package/dist/hook/decision.js +955 -0
- package/dist/hook/decision.js.map +1 -0
- package/dist/hook/memory-store.d.ts +81 -0
- package/dist/hook/memory-store.js +157 -0
- package/dist/hook/memory-store.js.map +1 -0
- package/dist/hook/payload.d.ts +55 -0
- package/dist/hook/payload.js +129 -0
- package/dist/hook/payload.js.map +1 -0
- package/dist/hook/run.d.ts +48 -0
- package/dist/hook/run.js +218 -0
- package/dist/hook/run.js.map +1 -0
- package/dist/hook/store-port.d.ts +72 -0
- package/dist/hook/store-port.js +2 -0
- package/dist/hook/store-port.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/ports/audit.d.ts +18 -0
- package/dist/ports/audit.js +11 -0
- package/dist/ports/audit.js.map +1 -0
- package/dist/ports/clock.d.ts +14 -0
- package/dist/ports/clock.js +11 -0
- package/dist/ports/clock.js.map +1 -0
- package/dist/ports/decision.d.ts +75 -0
- package/dist/ports/decision.js +2 -0
- package/dist/ports/decision.js.map +1 -0
- package/dist/ports/index.d.ts +14 -0
- package/dist/ports/index.js +2 -0
- package/dist/ports/index.js.map +1 -0
- package/dist/ports/log.d.ts +22 -0
- package/dist/ports/log.js +12 -0
- package/dist/ports/log.js.map +1 -0
- package/dist/ports/state.d.ts +46 -0
- package/dist/ports/state.js +13 -0
- package/dist/ports/state.js.map +1 -0
- package/dist/state/clock.d.ts +40 -0
- package/dist/state/clock.js +43 -0
- package/dist/state/clock.js.map +1 -0
- package/dist/state/file-store.d.ts +340 -0
- package/dist/state/file-store.js +849 -0
- package/dist/state/file-store.js.map +1 -0
- package/dist/state/paths.d.ts +41 -0
- package/dist/state/paths.js +73 -0
- package/dist/state/paths.js.map +1 -0
- package/docs/USER_GUIDE.en.md +79 -36
- package/docs/claude-code.md +281 -0
- package/docs/design/v0.2.0-harness-plugins.md +381 -0
- package/docs/design/v0.3.0-orchestration-unification.md +580 -0
- package/docs/dsh-plugin.md +54 -54
- package/docs/release-checklist-v0.1.0.md +32 -21
- package/docs/release-handbook-porting-notes.md +11 -11
- package/docs/release-handbook.md +55 -30
- package/docs/release-notes-v0.1.0.md +27 -14
- package/docs/release-notes-v0.3.0.md +152 -0
- package/docs/research/claude-code-harness.md +607 -0
- package/docs/research/pi-harness.md +621 -0
- package/package.json +16 -7
|
@@ -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;
|
|
@@ -0,0 +1,250 @@
|
|
|
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 { claimCandidates } from './closing.js';
|
|
74
|
+
import { assembleEvidence } from './evidence.js';
|
|
75
|
+
import { actionWithinBudget, bookAction, spendJudgment } from './policy.js';
|
|
76
|
+
import { clip, estimateTokens } from './text.js';
|
|
77
|
+
/** The capability every decision in this module belongs to. */
|
|
78
|
+
export const CLOSING_CAPABILITY = 'closing';
|
|
79
|
+
/** The audit action an objection is recorded under. */
|
|
80
|
+
export const CLOSING_ACTION = 'steer-closing';
|
|
81
|
+
/**
|
|
82
|
+
* The two latches this decision keeps, both keyed by turn rather than by identity.
|
|
83
|
+
*
|
|
84
|
+
* The other capabilities latch by *signature* — one repeated call is one episode.
|
|
85
|
+
* A closing check has no such identity: the episode is the turn itself, so the
|
|
86
|
+
* key is `closing:turn:<n>` and it is the host's storage that has to keep it.
|
|
87
|
+
*/
|
|
88
|
+
export const CLOSING_LATCH = {
|
|
89
|
+
/** The turn was already objected to (or observed) — never twice per turn. */
|
|
90
|
+
applied: (turn) => `closing:turn:${turn}`,
|
|
91
|
+
/** The memo namespace of the verification request, so a replay is free. */
|
|
92
|
+
verdictKey: (agent, turn) => `reflex-closing:${agent}:${turn}`
|
|
93
|
+
};
|
|
94
|
+
/** Opinion of one contradicted statement, clipped for the wording and the record. */
|
|
95
|
+
const STATEMENT_CHARS = 160;
|
|
96
|
+
/** How much of the assembled evidence the classifier is shown as context. */
|
|
97
|
+
const CLASSIFY_CONTEXT_CHARS = 600;
|
|
98
|
+
/**
|
|
99
|
+
* Decide whether the turn that is closing contradicts its own evidence, and tell
|
|
100
|
+
* the host what to do about it.
|
|
101
|
+
*
|
|
102
|
+
* The position is an *input of this decision*, not a port accessor and not a
|
|
103
|
+
* counter. The turn here is the boundary being closed, which can be a turn no
|
|
104
|
+
* step has recorded yet — a turn that said something and admitted no step — so it
|
|
105
|
+
* cannot be read off the running counters. `step` is the step the engine last
|
|
106
|
+
* recorded, which is the same number the audit detail has always quoted.
|
|
107
|
+
*
|
|
108
|
+
* @param invocation - where in the run this check is being made.
|
|
109
|
+
* @param port - everything the shared layer cannot know by itself.
|
|
110
|
+
* @returns what the check decided, and the message to steer when it applied.
|
|
111
|
+
*/
|
|
112
|
+
export async function orchestrateClosing(invocation, port) {
|
|
113
|
+
const mode = port.mode();
|
|
114
|
+
const policy = port.policy();
|
|
115
|
+
// The three "nothing at all" exits are deliberately silent: a turn with nothing
|
|
116
|
+
// to say, or nothing to say it about, is not a refused decision and would fill
|
|
117
|
+
// the skip histogram with entries that describe every turn ever run.
|
|
118
|
+
if (mode === 'off' || !port.serves())
|
|
119
|
+
return silent();
|
|
120
|
+
if (!port.evidenceSuspect())
|
|
121
|
+
return silent();
|
|
122
|
+
const claimsText = port.claims();
|
|
123
|
+
if (claimsText.length === 0)
|
|
124
|
+
return silent();
|
|
125
|
+
const candidates = claimCandidates(claimsText);
|
|
126
|
+
if (candidates.length === 0)
|
|
127
|
+
return silent();
|
|
128
|
+
const state = port.budget();
|
|
129
|
+
// One place in the run, quoted by the latch key, the memo namespace, the audit
|
|
130
|
+
// detail and the wording alike.
|
|
131
|
+
const { turn, step } = invocation.position;
|
|
132
|
+
const skips = [];
|
|
133
|
+
const refuse = (reason, charge) => {
|
|
134
|
+
if (charge !== undefined)
|
|
135
|
+
port.chargeJudgment(charge);
|
|
136
|
+
port.skip(reason, charge);
|
|
137
|
+
skips.push(reason);
|
|
138
|
+
return { action: 'pass-through', skip: reason, skips: [...skips], applied: false };
|
|
139
|
+
};
|
|
140
|
+
// A note records a reason without ending the decision: `evidence-truncated` is
|
|
141
|
+
// the one branch that reports something and keeps going.
|
|
142
|
+
const note = (reason) => {
|
|
143
|
+
port.skip(reason);
|
|
144
|
+
skips.push(reason);
|
|
145
|
+
};
|
|
146
|
+
if (port.alreadyObjected())
|
|
147
|
+
return refuse('duplicate-intervention');
|
|
148
|
+
if (!actionWithinBudget(state, policy))
|
|
149
|
+
return refuse('intervention-cap');
|
|
150
|
+
if (port.aborted())
|
|
151
|
+
return silent();
|
|
152
|
+
const assembled = assembleEvidence(port.evidence(), port.evidenceBudget());
|
|
153
|
+
port.noteEvidence({ retainedChars: assembled.retainedChars, truncatedChars: assembled.truncatedChars });
|
|
154
|
+
if (assembled.truncatedChars > 0)
|
|
155
|
+
note('evidence-truncated');
|
|
156
|
+
const classificationSkip = spendJudgment(state, policy);
|
|
157
|
+
if (classificationSkip !== undefined)
|
|
158
|
+
return refuse(classificationSkip);
|
|
159
|
+
const started = port.clock().now();
|
|
160
|
+
let classification;
|
|
161
|
+
try {
|
|
162
|
+
classification = await port.classify({
|
|
163
|
+
statements: candidates,
|
|
164
|
+
context: assembled.text.slice(0, CLASSIFY_CONTEXT_CHARS)
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
catch {
|
|
168
|
+
// FAIL-OPEN, locally: an unavailable classifier must not become a model-visible
|
|
169
|
+
// objection, and it must never fall back to a word list. The spent slot is not
|
|
170
|
+
// refunded — the judgment really was bought — but nothing is billed, because
|
|
171
|
+
// no answer was received.
|
|
172
|
+
return refuse('closing-claim-unavailable');
|
|
173
|
+
}
|
|
174
|
+
const floor = port.claimMinConfidence();
|
|
175
|
+
const claims = classification.results
|
|
176
|
+
.filter((item) => item.isClaim && item.confidence >= floor)
|
|
177
|
+
.map((item) => ({ statement: item.statement }));
|
|
178
|
+
const classifyTokens = candidates.reduce((sum, statement) => sum + estimateTokens(statement), 0);
|
|
179
|
+
const classificationCharge = {
|
|
180
|
+
judgments: 1,
|
|
181
|
+
memoHits: 0,
|
|
182
|
+
localLatencyMs: Math.max(0, port.clock().now() - started - classification.latencyMs),
|
|
183
|
+
remoteLatencyMs: classification.latencyMs,
|
|
184
|
+
judgeTokens: classifyTokens
|
|
185
|
+
};
|
|
186
|
+
if (claims.length === 0) {
|
|
187
|
+
// Paying for the classification and then finding nothing to verify is a
|
|
188
|
+
// complete answer, not a failure: the charge is recorded with the skip.
|
|
189
|
+
return refuse('closing-no-claim', classificationCharge);
|
|
190
|
+
}
|
|
191
|
+
const verdict = await port.verify(claims, assembled.text, {
|
|
192
|
+
latchCacheKey: CLOSING_LATCH.verdictKey(port.agentId(), turn)
|
|
193
|
+
});
|
|
194
|
+
const judgeTokens = classifyTokens + claims.reduce((sum, item) => sum + estimateTokens(item.statement), estimateTokens(assembled.text));
|
|
195
|
+
const judgment = {
|
|
196
|
+
judgments: 1,
|
|
197
|
+
memoHits: 0,
|
|
198
|
+
localLatencyMs: Math.max(0, port.clock().now() - started - verdict.latencyMs - classification.latencyMs),
|
|
199
|
+
remoteLatencyMs: classification.latencyMs + verdict.latencyMs,
|
|
200
|
+
judgeTokens
|
|
201
|
+
};
|
|
202
|
+
const contradicted = verdict.results
|
|
203
|
+
.filter((item) => item.outcome === 'contradicted')
|
|
204
|
+
.map((item) => clip(item.statement, STATEMENT_CHARS));
|
|
205
|
+
const undecided = verdict.results.filter((item) => item.outcome === 'escalate').length;
|
|
206
|
+
if (contradicted.length === 0) {
|
|
207
|
+
return refuse(undecided > 0 ? 'closing-undecided' : verdict.passed ? 'closing-evidence-consistent' : 'closing-unconfirmed', judgment);
|
|
208
|
+
}
|
|
209
|
+
const plan = {
|
|
210
|
+
capability: CLOSING_CAPABILITY,
|
|
211
|
+
action: CLOSING_ACTION,
|
|
212
|
+
reason: `closing evidence contradicts ${contradicted.length} completion claim(s)`,
|
|
213
|
+
feedback: port.describe({ contradicted, turn }),
|
|
214
|
+
detail: { confidence: verdict.results[0]?.confidence, turn, step }
|
|
215
|
+
};
|
|
216
|
+
const applies = mode === 'active';
|
|
217
|
+
// Latched in both modes, for the same reason as the other capabilities: the
|
|
218
|
+
// episode is consumed once, and only the *steering* is gated on the mode. An
|
|
219
|
+
// observe run that did not latch would buy the same judgment again at the next
|
|
220
|
+
// boundary and describe a run nobody could reproduce.
|
|
221
|
+
port.latchObjected();
|
|
222
|
+
bookAction(state);
|
|
223
|
+
port.conclude(plan, applies, judgment);
|
|
224
|
+
if (!applies)
|
|
225
|
+
return { action: 'objected', skips: [...skips], plan, applied: false };
|
|
226
|
+
port.steer(plan.feedback);
|
|
227
|
+
return { action: 'objected', skips: [...skips], plan, applied: true, message: plan.feedback };
|
|
228
|
+
}
|
|
229
|
+
/** The outcome of a check that decided nothing and has nothing to report. */
|
|
230
|
+
function silent() {
|
|
231
|
+
return { action: 'pass-through', skips: [], applied: false };
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* The objection's wording, in the default form.
|
|
235
|
+
*
|
|
236
|
+
* Exported because a host that shows the text to the same audience may keep it
|
|
237
|
+
* verbatim; a host that words it differently supplies its own through the port.
|
|
238
|
+
* The statement clipping is the shared part: a contradicted claim is quoted at
|
|
239
|
+
* 160 characters with its whitespace collapsed, so a multi-line claim can never
|
|
240
|
+
* make the objection unbounded.
|
|
241
|
+
* @param facts - what the objection is built from.
|
|
242
|
+
* @param limit - the total character budget.
|
|
243
|
+
* @returns the text handed to the model.
|
|
244
|
+
*/
|
|
245
|
+
export function describeClosing(facts, limit) {
|
|
246
|
+
return clip(`Reflex closing check: this turn is about to close while its own tool results carry failures that contradict what it claims ` +
|
|
247
|
+
`(${facts.contradicted.map((item) => `"${item}"`).join('; ')}). Before concluding, either fix the failing evidence or state the failure ` +
|
|
248
|
+
`plainly instead of the completion claim.`, limit);
|
|
249
|
+
}
|
|
250
|
+
//# sourceMappingURL=orchestrate-closing.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"orchestrate-closing.js","sourceRoot":"","sources":["../../src/core/orchestrate-closing.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared orchestration of the closing check.\n *\n * The fourth and last lift: {@link ./orchestrate} owns when a result is reduced,\n * {@link ./orchestrate-stagnation} owns when a call is refused and when a step is\n * corrected, {@link ./orchestrate-correction} owns what happens to a result that\n * failed — and this one owns what happens when a turn is about to *close* while\n * its own words claim success the evidence does not support.\n *\n * ```\n * agent/turn-stopping\n * → off, or the host is not serving this capability → nothing at all\n * → the turn said nothing, or no evidence is a failure → not suspicious, nothing at all\n * → no candidate sentence → nothing at all\n * → already latched for this turn → duplicate-intervention\n * → the turn's action allowance is spent → intervention-cap\n * → the caller's signal is aborted → nothing at all\n * → assemble the evidence; truncation is NOTED and the decision continues\n * → buy the classification (turn/session budgets inside)\n * → the classifier could not answer → closing-claim-unavailable (fail open, locally)\n * → nothing really claims completion → closing-no-claim (and the charge is kept)\n * → buy the verification (same judgment, second request)\n * → nothing contradicted → closing-undecided / closing-unconfirmed / closing-evidence-consistent\n * → latch the turn, book the action, conclude\n * → [the host steers the objection into the turn, in active mode only]\n * → a failure anywhere after that → planning-error (fail open)\n * ```\n *\n * ## What is shared and what is not\n *\n * Shared here: the order above, every skip reason, the budget rules, the two\n * per-turn latches, the shape of the audit detail, and the decision that active\n * mode asks its host to steer.\n *\n * *Not* shared here: the act of steering (that is `HostClosingPort#steer`), the\n * wording the model reads (`#describe`), the storage of the evidence counters\n * (`#noteEvidence`), and the accumulation of the turn's own words — a host that\n * reads them from a stream and a host that reads them from a transcript both hand\n * over the same string.\n *\n * ## The two judgments are one decision\n *\n * The closing check buys **two** requests from one capability: a classification\n * of the turn's candidate sentences, and a verification of the claims that\n * classification accepted. They are one logical judgment — the classification\n * decides *whether* anything is worth verifying — so both are charged against the\n * single slot the turn budget allowed, and both are billed as one\n * {@link ClosingJudgment}. That fold is why this port states its two *purchases*\n * ({@link HostClosingPort#classify} and {@link HostClosingPort#verify}) and never\n * the transport behind them: a caller holding the service would have to\n * re-implement the purchase, the memo, the latency split and the billing, and the\n * one-charge rule is only stateable where the charge is built. It stays here.\n *\n * ## The skip that does not return\n *\n * Every skip in the other three modules ends the decision. `evidence-truncated`\n * does not: the evidence was assembled with some of it dropped, the amount is\n * reported, and the judgment proceeds on what survived. This module therefore\n * distinguishes a *note* (`#note`, which records) from a *refusal* (`#refuse`,\n * which records and returns). Collapsing the two would either stop the closing\n * check whenever evidence is large, or lose the fact that it was truncated.\n *\n * ## A verdict that could not decide is not a contradiction\n *\n * `escalate` means the backend could not answer — an unavailable service degrades\n * exactly this way. Steering a turn on an undecided verdict would turn a backend\n * failure into a model-visible objection, so only `contradicted` results steer;\n * `escalate` gets its own reason (`closing-undecided`) precisely so a run can tell\n * \"the evidence was fine\" from \"nobody looked\".\n *\n * @module core/orchestrate-closing\n */\n\nimport { claimCandidates } from './closing.js';\nimport { assembleEvidence, type EvidenceEntry } from './evidence.js';\nimport type { HostBillingPort, HostDecisionPort, JudgmentCost, JudgmentPosition } from './orchestrate-host.js';\nimport { actionWithinBudget, bookAction, spendJudgment } from './policy.js';\nimport { clip, estimateTokens } from './text.js';\n\n/** The capability every decision in this module belongs to. */\nexport const CLOSING_CAPABILITY = 'closing' as const;\n\n/** The audit action an objection is recorded under. */\nexport const CLOSING_ACTION = 'steer-closing' as const;\n\n/**\n * The two latches this decision keeps, both keyed by turn rather than by identity.\n *\n * The other capabilities latch by *signature* — one repeated call is one episode.\n * A closing check has no such identity: the episode is the turn itself, so the\n * key is `closing:turn:<n>` and it is the host's storage that has to keep it.\n */\nexport const CLOSING_LATCH = {\n /** The turn was already objected to (or observed) — never twice per turn. */\n applied: (turn: number): string => `closing:turn:${turn}`,\n /** The memo namespace of the verification request, so a replay is free. */\n verdictKey: (agent: string, turn: number): string => `reflex-closing:${agent}:${turn}`\n} as const;\n\n/** One planned objection, as the host records it. */\nexport interface ClosingPlanRecord {\n readonly capability: typeof CLOSING_CAPABILITY;\n readonly action: typeof CLOSING_ACTION;\n readonly reason: string;\n feedback: string;\n readonly detail: Record<string, unknown>;\n}\n\n/**\n * The judgment one closing check rode on.\n *\n * Both requests are folded into one charge on purpose: the turn budget bought one\n * slot, and a reader of the account must not see two slots spent for one decision.\n * `localLatencyMs` is the wait the two requests cost in this process; the two\n * remote times are summed because the model was asked two questions.\n */\nexport interface ClosingJudgment extends JudgmentCost {}\n\n/** What one closing check turned out to be. */\nexport type ClosingAction = 'objected' | 'pass-through';\n\n/** What one orchestrated closing check produced. */\nexport interface ClosingOutcome {\n /** What the capability was in force: a decision is only made when this is not `off`. */\n readonly action: ClosingAction;\n /** The reason the check did nothing, when it did nothing. */\n readonly skip?: string;\n /** Every skip reason this one check reported, in order (normally 0 or 1). */\n readonly skips: readonly string[];\n /** The objection, once the decision is to make one. */\n readonly plan?: ClosingPlanRecord;\n /** Whether the objection was really steered (active mode only). */\n readonly applied: boolean;\n /** The message to hand the model, when the host steers in active mode. */\n readonly message?: string;\n}\n\n/** What the classification half answered. */\nexport interface ClaimClassificationLike {\n readonly results: readonly { readonly statement: string; readonly isClaim: boolean; readonly confidence: number }[];\n readonly latencyMs: number;\n}\n\n/** What the verification half answered. */\nexport interface ClosingVerdictLike {\n readonly passed: boolean;\n readonly results: readonly { readonly statement: string; readonly outcome: string; readonly confidence: number }[];\n readonly latencyMs: number;\n}\n\n/** What the objection is built from, for the host's wording. */\nexport interface ClosingFeedbackFacts {\n /** The contradicted statements, already clipped for quoting. */\n readonly contradicted: readonly string[];\n /** The turn that is closing. */\n readonly turn: number;\n}\n\n/** Everything the shared layer cannot know by itself. */\nexport interface HostClosingPort extends HostDecisionPort, HostBillingPort<ClosingJudgment, ClosingPlanRecord> {\n /** The effective mode of the `closing` capability. */\n mode(): 'off' | 'observe' | 'active';\n /**\n * The turn's own words, as the stream carried them.\n *\n * The host accumulates them (`agent/assistant-stream` in DSH); the shared layer\n * only asks for the string. An empty string means the turn said nothing, which\n * is one of the four deterministic reasons nothing is bought.\n */\n claims(): string;\n /**\n * Whether at least one retained evidence entry looks like a failure.\n *\n * A host computes this from its own reading of its results; the shared layer\n * needs only the boolean, because *which* result failed is what the judgment\n * reads, not what the trigger reads.\n */\n evidenceSuspect(): boolean;\n /** The evidence entries retained for this turn. */\n evidence(): readonly EvidenceEntry[];\n /** The evidence-assembly budget in force. */\n evidenceBudget(): number;\n /** Whether the caller's signal is already aborted (a cancelling turn). */\n aborted(): boolean;\n /** Whether this turn was already objected to (or observed) — the per-turn latch. */\n alreadyObjected(): boolean;\n /** Latch this turn as objected to. */\n latchObjected(): void;\n /** The identity the verification memo is namespaced by. */\n agentId(): string;\n /** The classification half of the one judgment. */\n classify(request: { readonly statements: readonly string[]; readonly context: string }): Promise<ClaimClassificationLike>;\n /** The verification half of the same judgment. */\n verify(\n claims: readonly { readonly statement: string }[],\n evidence: string,\n options: { readonly latchCacheKey: string }\n ): Promise<ClosingVerdictLike>;\n /** The confidence floor a classified sentence must clear to be a claim. */\n claimMinConfidence(): number;\n /** Word the objection the model reads. */\n describe(facts: ClosingFeedbackFacts): string;\n /** Hand the objection to the model. Only called in active mode. */\n steer(message: string): void;\n /** Record the evidence counters, which are engine-level rather than per-agent. */\n noteEvidence(stats: { readonly retainedChars: number; readonly truncatedChars: number }): void;\n}\n\n/** Opinion of one contradicted statement, clipped for the wording and the record. */\nconst STATEMENT_CHARS = 160;\n\n/** How much of the assembled evidence the classifier is shown as context. */\nconst CLASSIFY_CONTEXT_CHARS = 600;\n\n/**\n * Decide whether the turn that is closing contradicts its own evidence, and tell\n * the host what to do about it.\n *\n * The position is an *input of this decision*, not a port accessor and not a\n * counter. The turn here is the boundary being closed, which can be a turn no\n * step has recorded yet — a turn that said something and admitted no step — so it\n * cannot be read off the running counters. `step` is the step the engine last\n * recorded, which is the same number the audit detail has always quoted.\n *\n * @param invocation - where in the run this check is being made.\n * @param port - everything the shared layer cannot know by itself.\n * @returns what the check decided, and the message to steer when it applied.\n */\nexport async function orchestrateClosing(\n invocation: { readonly position: JudgmentPosition },\n port: HostClosingPort\n): Promise<ClosingOutcome> {\n const mode = port.mode();\n const policy = port.policy();\n // The three \"nothing at all\" exits are deliberately silent: a turn with nothing\n // to say, or nothing to say it about, is not a refused decision and would fill\n // the skip histogram with entries that describe every turn ever run.\n if (mode === 'off' || !port.serves()) return silent();\n if (!port.evidenceSuspect()) return silent();\n const claimsText = port.claims();\n if (claimsText.length === 0) return silent();\n const candidates = claimCandidates(claimsText);\n if (candidates.length === 0) return silent();\n\n const state = port.budget();\n // One place in the run, quoted by the latch key, the memo namespace, the audit\n // detail and the wording alike.\n const { turn, step } = invocation.position;\n const skips: string[] = [];\n const refuse = (reason: string, charge?: ClosingJudgment): ClosingOutcome => {\n if (charge !== undefined) port.chargeJudgment(charge);\n port.skip(reason, charge);\n skips.push(reason);\n return { action: 'pass-through', skip: reason, skips: [...skips], applied: false };\n };\n // A note records a reason without ending the decision: `evidence-truncated` is\n // the one branch that reports something and keeps going.\n const note = (reason: string): void => {\n port.skip(reason);\n skips.push(reason);\n };\n\n if (port.alreadyObjected()) return refuse('duplicate-intervention');\n if (!actionWithinBudget(state, policy)) return refuse('intervention-cap');\n if (port.aborted()) return silent();\n\n const assembled = assembleEvidence(port.evidence(), port.evidenceBudget());\n port.noteEvidence({ retainedChars: assembled.retainedChars, truncatedChars: assembled.truncatedChars });\n if (assembled.truncatedChars > 0) note('evidence-truncated');\n\n const classificationSkip = spendJudgment(state, policy);\n if (classificationSkip !== undefined) return refuse(classificationSkip);\n\n const started = port.clock().now();\n let classification: ClaimClassificationLike;\n try {\n classification = await port.classify({\n statements: candidates,\n context: assembled.text.slice(0, CLASSIFY_CONTEXT_CHARS)\n });\n } catch {\n // FAIL-OPEN, locally: an unavailable classifier must not become a model-visible\n // objection, and it must never fall back to a word list. The spent slot is not\n // refunded — the judgment really was bought — but nothing is billed, because\n // no answer was received.\n return refuse('closing-claim-unavailable');\n }\n const floor = port.claimMinConfidence();\n const claims = classification.results\n .filter((item) => item.isClaim && item.confidence >= floor)\n .map((item) => ({ statement: item.statement }));\n const classifyTokens = candidates.reduce((sum, statement) => sum + estimateTokens(statement), 0);\n const classificationCharge: ClosingJudgment = {\n judgments: 1,\n memoHits: 0,\n localLatencyMs: Math.max(0, port.clock().now() - started - classification.latencyMs),\n remoteLatencyMs: classification.latencyMs,\n judgeTokens: classifyTokens\n };\n if (claims.length === 0) {\n // Paying for the classification and then finding nothing to verify is a\n // complete answer, not a failure: the charge is recorded with the skip.\n return refuse('closing-no-claim', classificationCharge);\n }\n\n const verdict = await port.verify(claims, assembled.text, {\n latchCacheKey: CLOSING_LATCH.verdictKey(port.agentId(), turn)\n });\n const judgeTokens =\n classifyTokens + claims.reduce((sum, item) => sum + estimateTokens(item.statement), estimateTokens(assembled.text));\n const judgment: ClosingJudgment = {\n judgments: 1,\n memoHits: 0,\n localLatencyMs: Math.max(0, port.clock().now() - started - verdict.latencyMs - classification.latencyMs),\n remoteLatencyMs: classification.latencyMs + verdict.latencyMs,\n judgeTokens\n };\n const contradicted = verdict.results\n .filter((item) => item.outcome === 'contradicted')\n .map((item) => clip(item.statement, STATEMENT_CHARS));\n const undecided = verdict.results.filter((item) => item.outcome === 'escalate').length;\n if (contradicted.length === 0) {\n return refuse(undecided > 0 ? 'closing-undecided' : verdict.passed ? 'closing-evidence-consistent' : 'closing-unconfirmed', judgment);\n }\n\n const plan: ClosingPlanRecord = {\n capability: CLOSING_CAPABILITY,\n action: CLOSING_ACTION,\n reason: `closing evidence contradicts ${contradicted.length} completion claim(s)`,\n feedback: port.describe({ contradicted, turn }),\n detail: { confidence: verdict.results[0]?.confidence, turn, step }\n };\n const applies = mode === 'active';\n // Latched in both modes, for the same reason as the other capabilities: the\n // episode is consumed once, and only the *steering* is gated on the mode. An\n // observe run that did not latch would buy the same judgment again at the next\n // boundary and describe a run nobody could reproduce.\n port.latchObjected();\n bookAction(state);\n port.conclude(plan, applies, judgment);\n if (!applies) return { action: 'objected', skips: [...skips], plan, applied: false };\n port.steer(plan.feedback);\n return { action: 'objected', skips: [...skips], plan, applied: true, message: plan.feedback };\n}\n\n/** The outcome of a check that decided nothing and has nothing to report. */\nfunction silent(): ClosingOutcome {\n return { action: 'pass-through', skips: [], applied: false };\n}\n\n/**\n * The objection's wording, in the default form.\n *\n * Exported because a host that shows the text to the same audience may keep it\n * verbatim; a host that words it differently supplies its own through the port.\n * The statement clipping is the shared part: a contradicted claim is quoted at\n * 160 characters with its whitespace collapsed, so a multi-line claim can never\n * make the objection unbounded.\n * @param facts - what the objection is built from.\n * @param limit - the total character budget.\n * @returns the text handed to the model.\n */\nexport function describeClosing(facts: ClosingFeedbackFacts, limit: number): string {\n return clip(\n `Reflex closing check: this turn is about to close while its own tool results carry failures that contradict what it claims ` +\n `(${facts.contradicted.map((item) => `\"${item}\"`).join('; ')}). Before concluding, either fix the failing evidence or state the failure ` +\n `plainly instead of the completion claim.`,\n limit\n );\n}\n\n"]}
|