dsh-boost 0.1.0 → 0.1.2
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.en.md +184 -70
- package/README.md +148 -59
- package/dist/gate/decide.js +33 -2
- package/dist/gate/decide.js.map +1 -1
- package/dist/hooks/llm-stream.js +242 -89
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +282 -25
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/hooks/session-state.js +18 -8
- package/dist/hooks/session-state.js.map +1 -1
- package/dist/host/root.js +22 -1
- package/dist/host/root.js.map +1 -1
- package/dist/index.js +494 -72
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +24 -9
- package/dist/scope/store.js.map +1 -1
- package/dist/tools/boost.js +37 -4
- package/dist/tools/boost.js.map +1 -1
- package/dist/types.d.ts +18 -1
- package/dist/types.js.map +1 -1
- package/package.json +10 -6
- package/dist/admission/fixed-cost.d.ts +0 -23
- package/dist/admission/ledger.d.ts +0 -113
- package/dist/admission/retrieval.d.ts +0 -65
- package/dist/admission/usage.d.ts +0 -75
- package/dist/config.d.ts +0 -43
- package/dist/gate/binding.d.ts +0 -113
- package/dist/gate/decide.d.ts +0 -82
- package/dist/gate/guard.d.ts +0 -69
- package/dist/gate/invalidate.d.ts +0 -112
- package/dist/gate/plan.d.ts +0 -86
- package/dist/hooks/clock.d.ts +0 -68
- package/dist/hooks/execute.d.ts +0 -79
- package/dist/hooks/llm-stream.d.ts +0 -276
- package/dist/hooks/pending.d.ts +0 -89
- package/dist/hooks/post-execute.d.ts +0 -247
- package/dist/hooks/session-state.d.ts +0 -158
- package/dist/hooks/synthesize.d.ts +0 -74
- package/dist/host/loader.d.ts +0 -23
- package/dist/host/platform.d.ts +0 -18
- package/dist/host/root.d.ts +0 -18
- package/dist/projection/apply.d.ts +0 -174
- package/dist/projection/canonicalise.d.ts +0 -43
- package/dist/projection/counters.d.ts +0 -65
- package/dist/projection/truncate.d.ts +0 -47
- package/dist/prompt/protocol.d.ts +0 -45
- package/dist/receipts/store.d.ts +0 -198
- package/dist/scope/doc.d.ts +0 -117
- package/dist/scope/resolve.d.ts +0 -91
- package/dist/scope/store.d.ts +0 -135
- package/dist/selector/jev.d.ts +0 -93
- package/dist/tools/boost.d.ts +0 -367
- package/dist/tools/family.d.ts +0 -26
|
@@ -1,247 +0,0 @@
|
|
|
1
|
-
import type { StepBudget } from '../admission/ledger.js';
|
|
2
|
-
import type { RetrievalLedger } from '../admission/retrieval.js';
|
|
3
|
-
import type { UsageLedger } from '../admission/usage.js';
|
|
4
|
-
import type { AnchorStore } from '../gate/invalidate.js';
|
|
5
|
-
import type { Guard, Plan } from '../gate/plan.js';
|
|
6
|
-
import type { ProjectionCounters } from '../projection/counters.js';
|
|
7
|
-
import type { FormatFooter, SpillBackend } from '../projection/apply.js';
|
|
8
|
-
import type { ReceiptStore } from '../receipts/store.js';
|
|
9
|
-
import type { ScopeStore } from '../scope/store.js';
|
|
10
|
-
import type { LlmLike } from '../selector/jev.js';
|
|
11
|
-
import type { BoostConfig, PluginContext } from '../types.js';
|
|
12
|
-
import type { TurnClock } from './clock.js';
|
|
13
|
-
import { streamHook } from './llm-stream.js';
|
|
14
|
-
import type { SessionRuntime } from './llm-stream.js';
|
|
15
|
-
import type { PendingEntry, PendingQueue } from './pending.js';
|
|
16
|
-
import { ReceiptSessionState } from './session-state.js';
|
|
17
|
-
/**
|
|
18
|
-
* The `llm/stream` body lives in its own module (Task 23c-1). It is re-exported
|
|
19
|
-
* here because `registerHooks` is the assembly surface the rest of the plugin
|
|
20
|
-
* and the integration tests import; the mount below uses the same function.
|
|
21
|
-
*/
|
|
22
|
-
export { streamHook };
|
|
23
|
-
/**
|
|
24
|
-
* The substitution whitelist: exactly the read-only trio (design §5.2-5).
|
|
25
|
-
*
|
|
26
|
-
* One constant drives both `decide` (non-shadow) and the `whitelisted` field
|
|
27
|
-
* written to the shadow/substitute receipts, so the policy the gate enforced
|
|
28
|
-
* and the policy the audit trail reports cannot drift. `bash`, `web_fetch` and
|
|
29
|
-
* every write tool stay out: they have no deterministic read-only judgement.
|
|
30
|
-
*/
|
|
31
|
-
export declare const SUBSTITUTION_WHITELIST: ReadonlySet<string>;
|
|
32
|
-
/** The route an `ask-selector` request inherits from the boundary request. */
|
|
33
|
-
export interface SelectorRoute {
|
|
34
|
-
provider: string;
|
|
35
|
-
model: string;
|
|
36
|
-
reasoningEffort?: string;
|
|
37
|
-
}
|
|
38
|
-
/** The dependencies the mounts read; Task 23c constructs the whole set once. */
|
|
39
|
-
export interface HookDeps {
|
|
40
|
-
config: BoostConfig;
|
|
41
|
-
scope: ScopeStore;
|
|
42
|
-
receipts: ReceiptStore;
|
|
43
|
-
/**
|
|
44
|
-
* Per-session receipt anchors (design §5.2-7).
|
|
45
|
-
*
|
|
46
|
-
* Written by the decision path on a real commit and read here to detect an
|
|
47
|
-
* external rewrite; a hit clears them. Required by the contract: without a
|
|
48
|
-
* store the invalidation check is silently dead.
|
|
49
|
-
*/
|
|
50
|
-
anchors: AnchorStore;
|
|
51
|
-
/**
|
|
52
|
-
* Session id to workspace id.
|
|
53
|
-
*
|
|
54
|
-
* Required: substitution is refused for a session that does not resolve to a
|
|
55
|
-
* workspace, or whose live scope document does not list that workspace. The
|
|
56
|
-
* judgement cache alone can be stale, and the replacement path must never
|
|
57
|
-
* run without a current visibility answer (design §5.5). Returning
|
|
58
|
-
* `undefined` is fail-closed, never an error.
|
|
59
|
-
*/
|
|
60
|
-
resolveSession: (sessionId: string) => string | undefined;
|
|
61
|
-
/** At most one pending substitution per session; absent means the path is inert. */
|
|
62
|
-
queue?: PendingQueue;
|
|
63
|
-
/**
|
|
64
|
-
* Per-turn substitution budget; absent means no cap is applied. Used only
|
|
65
|
-
* when `sessions` is absent, so a shared instance is never preferred over
|
|
66
|
-
* the per-session runtime.
|
|
67
|
-
*/
|
|
68
|
-
budget?: StepBudget;
|
|
69
|
-
/** Usage pairing; the shared fallback when `sessions` is absent (T21/T23c). */
|
|
70
|
-
usage?: UsageLedger;
|
|
71
|
-
/**
|
|
72
|
-
* The host turn/step clock; `step()` is the only source of a call id's step.
|
|
73
|
-
* The shared fallback when `sessions` is absent.
|
|
74
|
-
*/
|
|
75
|
-
clock?: TurnClock;
|
|
76
|
-
/**
|
|
77
|
-
* Per-session clock, budget and usage (Task 23c).
|
|
78
|
-
*
|
|
79
|
-
* A shared `clock` lets another session's turn/step stamp this session's
|
|
80
|
-
* `callId`; a shared `StepBudget` starves a session; a shared `UsageLedger`
|
|
81
|
-
* pairs one session's substitution with another session's request. When
|
|
82
|
-
* supplied, this runtime is authoritative and the three single instances
|
|
83
|
-
* above are only the fallback for a plugin wired without it. 23c-2 constructs
|
|
84
|
-
* one `SessionRuntime`, drives `onModelRequest` from the host's
|
|
85
|
-
* `agent/request` payload, and passes it here.
|
|
86
|
-
*/
|
|
87
|
-
sessions?: SessionRuntime;
|
|
88
|
-
/**
|
|
89
|
-
* The host LLM service, used only for the `ask-selector` call.
|
|
90
|
-
*
|
|
91
|
-
* Optional so a minimal assembly (or a unit test of the decision path)
|
|
92
|
-
* degrades to a record-only abstention rather than crashing. The selector
|
|
93
|
-
* request carries `purpose: 'boost-selector'`, which the frozen stream hook
|
|
94
|
-
* lets through untouched (Task 23c-2).
|
|
95
|
-
*/
|
|
96
|
-
llm?: LlmLike;
|
|
97
|
-
/**
|
|
98
|
-
* The effective provider/model of the session's latest model request.
|
|
99
|
-
*
|
|
100
|
-
* The selector request must inherit the boundary request's route; this hook
|
|
101
|
-
* has no `GenerateOptions` of its own, so 23c-2 captures it from the
|
|
102
|
-
* `agent/request` waterfall and exposes it here. Missing means the selector
|
|
103
|
-
* cannot run and `ask-selector` records an abstention.
|
|
104
|
-
*/
|
|
105
|
-
selectorRoute?: (sessionId: string) => SelectorRoute | undefined;
|
|
106
|
-
/** Parsed plans per session, written by 23c's stream hook. */
|
|
107
|
-
plans?: Map<string, Plan>;
|
|
108
|
-
/**
|
|
109
|
-
* The per-session receipt/dispatch store. Optional so 23c can own the
|
|
110
|
-
* instance and call `clear(sessionId)` on a session-end signal; when omitted,
|
|
111
|
-
* `registerHooks` creates one. Lifetime: the store keeps one host turn's
|
|
112
|
-
* receipts and in-flight dispatches per session, folds them on the first call
|
|
113
|
-
* of a new turn, and otherwise retains the last turn until `clear` (or process
|
|
114
|
-
* exit). The class documents the reasoning.
|
|
115
|
-
*/
|
|
116
|
-
sessionState?: ReceiptSessionState;
|
|
117
|
-
/** The host spill backend; absent skips apply-mode projection. */
|
|
118
|
-
spill?: SpillBackend;
|
|
119
|
-
/**
|
|
120
|
-
* Session → spill locators of the receipts this plugin projected.
|
|
121
|
-
*
|
|
122
|
-
* Its only producer is a real spill write (design §5.3): the applied outcome
|
|
123
|
-
* carries the locator, and a later `read`/`grep` naming it becomes a
|
|
124
|
-
* `projection-retrieval` receipt whose cost is subtracted from the projection
|
|
125
|
-
* net. Optional so a minimal assembly degrades to uncounted retrievals rather
|
|
126
|
-
* than crashing; `apply` constructs one and `clearSession` drops a session's
|
|
127
|
-
* set on disposal.
|
|
128
|
-
*/
|
|
129
|
-
retrievals?: RetrievalLedger;
|
|
130
|
-
/**
|
|
131
|
-
* Projection skip counters (Task 25 review).
|
|
132
|
-
*
|
|
133
|
-
* `projectDecision` increments the unknown-family counter when a tool name has
|
|
134
|
-
* no configured family, so status can distinguish "no window, by design"
|
|
135
|
-
* from "the mapper missed a decorated name".
|
|
136
|
-
*/
|
|
137
|
-
projectionCounters?: ProjectionCounters;
|
|
138
|
-
/**
|
|
139
|
-
* Token estimator; absent means no meter.
|
|
140
|
-
*
|
|
141
|
-
* Projection still clips, but records `estimate:'unknown'` and no token
|
|
142
|
-
* numbers; substitution is refused before it can spend money (design §9).
|
|
143
|
-
*/
|
|
144
|
-
estimateText?: (t: string) => number;
|
|
145
|
-
/**
|
|
146
|
-
* Which estimator produced a projection receipt's numbers.
|
|
147
|
-
*
|
|
148
|
-
* `host` means the synchronous host token meter priced it. `unknown` is the
|
|
149
|
-
* only meterless value: a projection without a meter still clips, but its
|
|
150
|
-
* receipt carries `estimate:'unknown'` and no numbers at all. There is
|
|
151
|
-
* deliberately no characters-over-four arm — a fixed-density guess is not a
|
|
152
|
-
* measurement, and admitting the type would let a future producer stamp a
|
|
153
|
-
* fabricated figure as if the host had measured it.
|
|
154
|
-
*/
|
|
155
|
-
estimateKind?: 'host' | 'unknown';
|
|
156
|
-
/**
|
|
157
|
-
* The host spill-notice predicate, injected instead of imported.
|
|
158
|
-
*
|
|
159
|
-
* Kept because the host spill policy is not declared as a dependency at all and a
|
|
160
|
-
* test needs to hand over a throwing predicate without the host package.
|
|
161
|
-
* Production omits it and the dynamically imported host function is used.
|
|
162
|
-
*/
|
|
163
|
-
hasSpillNotice?: (text: string) => boolean;
|
|
164
|
-
/**
|
|
165
|
-
* The host spill footer renderer, injected instead of imported.
|
|
166
|
-
*
|
|
167
|
-
* The same seam and the same reason as {@link hasSpillNotice}: the notice
|
|
168
|
-
* module is reached by `import()` only, and a test must be able to exercise
|
|
169
|
-
* the "module absent" path (which disables apply-mode projection) without
|
|
170
|
-
* uninstalling the host package. Returning `undefined` means the module has
|
|
171
|
-
* no renderer; production omits this and the dynamically imported host
|
|
172
|
-
* function is used.
|
|
173
|
-
*/
|
|
174
|
-
resolveFooter?: () => FormatFooter | undefined | Promise<FormatFooter | undefined>;
|
|
175
|
-
/**
|
|
176
|
-
* The session's runtime replay horizon (design §5.3), when the assembly can
|
|
177
|
-
* supply it.
|
|
178
|
-
*
|
|
179
|
-
* The horizon is `min(config horizon, mean of the session's last
|
|
180
|
-
* `historyTurns` turns)`. Its instance (`RuntimeStepHorizon`) is built in
|
|
181
|
-
* `src/index.ts` and read there by `status`; the decision path can only see
|
|
182
|
-
* it through this seam. A projection receipt pins whatever this returns, so
|
|
183
|
-
* a historical saving is never re-valued by a later cross-session minimum.
|
|
184
|
-
* Absent (the current production wiring) means the resolved config's
|
|
185
|
-
* `horizonSteps` is the horizon in effect.
|
|
186
|
-
*/
|
|
187
|
-
horizonFor?: (sessionId: string) => number;
|
|
188
|
-
/**
|
|
189
|
-
* The host logger, for the few conditions that have no other surface.
|
|
190
|
-
*
|
|
191
|
-
* `registerHooks` fills it from `ctx.logger` when absent, so production never
|
|
192
|
-
* passes it explicitly. A missing footer renderer is the one current caller:
|
|
193
|
-
* it logs once, and `status` reports the same condition as a stable code.
|
|
194
|
-
*/
|
|
195
|
-
logger?: {
|
|
196
|
-
warn(message: string): void;
|
|
197
|
-
};
|
|
198
|
-
}
|
|
199
|
-
/** What a substitute, substitute-settled or shadow receipt adds about its plan. */
|
|
200
|
-
export interface SubstitutionEvidence {
|
|
201
|
-
/** The plan's goal, capped to {@link MAX_RECEIPT_PLAN_CODE_POINTS}. */
|
|
202
|
-
plan: string;
|
|
203
|
-
/** The committed candidate's guards, up to {@link MAX_RECEIPT_GUARDS}. */
|
|
204
|
-
guards: unknown[];
|
|
205
|
-
/** The plan's guard count, present only when `guards` was capped. */
|
|
206
|
-
guards_total?: number;
|
|
207
|
-
}
|
|
208
|
-
/**
|
|
209
|
-
* A queued entry carrying the evidence the synth-time receipt needs.
|
|
210
|
-
*
|
|
211
|
-
* `PendingEntry` is the one object that travels from the commit (post-execute)
|
|
212
|
-
* to synthesis (llm-stream), so the evidence rides on it; the settle afterwards
|
|
213
|
-
* reads it back from the ledger pairing. The extra field is additive and never
|
|
214
|
-
* dispatched: `synthesizeTurn` reads `name`/`args` only.
|
|
215
|
-
*/
|
|
216
|
-
export type AuditedPendingEntry = PendingEntry & {
|
|
217
|
-
evidence?: SubstitutionEvidence;
|
|
218
|
-
};
|
|
219
|
-
/**
|
|
220
|
-
* The plan/goal and guard evidence for one committed candidate.
|
|
221
|
-
*
|
|
222
|
-
* Guards are carried as written while they fit. Only a guard whose own JSON
|
|
223
|
-
* exceeds {@link MAX_RECEIPT_GUARD_CODE_POINTS} (a multi-KB `text_contains`,
|
|
224
|
-
* say) is replaced by a `truncated_json` marker, so the array stays bounded
|
|
225
|
-
* without silently dropping the guard's form.
|
|
226
|
-
*/
|
|
227
|
-
export declare function substitutionEvidence(goal: unknown, guards: readonly Guard[]): SubstitutionEvidence;
|
|
228
|
-
/**
|
|
229
|
-
* Register the plugin's four host integration points.
|
|
230
|
-
*
|
|
231
|
-
* The prompt section is registered first on purpose: it is the only mount that
|
|
232
|
-
* rejects a duplicate name, so a second `apply` aborts here before any event
|
|
233
|
-
* hook is mounted twice (the host turns a duplicate section into an error, and
|
|
234
|
-
* `apply` treats that as "already mounted"). Registering it last would leave
|
|
235
|
-
* three live duplicate listeners behind.
|
|
236
|
-
*
|
|
237
|
-
* One `ReceiptSessionState` belongs to the whole registration: the execute
|
|
238
|
-
* mount writes the in-flight call mapping and the post-execute mount consumes
|
|
239
|
-
* it, so the two waterfalls must share it.
|
|
240
|
-
*
|
|
241
|
-
* `scope`, `receipts`, `anchors` and `resolveSession` are required by
|
|
242
|
-
* `HookDeps`, but they are still checked at the point of use: a host wiring the
|
|
243
|
-
* plugin without one of the optional pieces still gets the four mount points,
|
|
244
|
-
* and every degraded path is fail-closed instead of throwing during
|
|
245
|
-
* registration.
|
|
246
|
-
*/
|
|
247
|
-
export declare function registerHooks(ctx: PluginContext, deps: HookDeps): void;
|
|
@@ -1,158 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Per-session bookkeeping for the post-execute decision path.
|
|
3
|
-
*
|
|
4
|
-
* The receipt/dispatch maps below are the class's own state. The module also
|
|
5
|
-
* owns the small plumbing both hook modules share — queue/anchor/plan access,
|
|
6
|
-
* receipt appends, the clock-turn read and receipt previews — so the two
|
|
7
|
-
* former copies cannot drift (in particular, their `clockTurnOf` fallbacks
|
|
8
|
-
* disagreed on `0` vs `undefined`).
|
|
9
|
-
*
|
|
10
|
-
* Both maps are keyed by session id and scoped to one host turn
|
|
11
|
-
* (design §5.2-7: the anchor cache expires at turn end):
|
|
12
|
-
*
|
|
13
|
-
* - **Receipts.** `decide` evaluates guards and `$public` templates against the
|
|
14
|
-
* receipt that just arrived (filed under `'root'`) *and* the receipts of the
|
|
15
|
-
* calls this plugin substituted earlier in the turn (filed under the plan
|
|
16
|
-
* candidate id). Without the second half a later step's
|
|
17
|
-
* `{ "$public": { "after": "A" … } }` can never bind, so the plan could only
|
|
18
|
-
* ever commit its first step.
|
|
19
|
-
* - **In-flight dispatches.** `tools/execute` clears the pending entry once the
|
|
20
|
-
* arriving call's id matches it (on accept or reject); a call with a different
|
|
21
|
-
* id passes through untouched. `tools/post-execute` still needs to know which
|
|
22
|
-
* candidate the arriving call belonged to. The execute hook records `callId -> candidateId` here
|
|
23
|
-
* before clearing, and the post-execute hook consumes it once.
|
|
24
|
-
*
|
|
25
|
-
* A new host turn drops both maps. Turn detection is lazy: the hooks see no
|
|
26
|
-
* turn-end event, so the first call of a new turn is what folds the old turn
|
|
27
|
-
* away. Nothing here throws on its own, but every method is still called from
|
|
28
|
-
* inside the hooks' `try` blocks, because the callers own the no-throw
|
|
29
|
-
* contract with the host.
|
|
30
|
-
*
|
|
31
|
-
* **Lifetime.** One entry per session, scoped to the host turn. A session's
|
|
32
|
-
* entry is replaced on the first call of its next turn, so the steady-state
|
|
33
|
-
* retention is one turn's receipts (at most 27: `'root'` plus the plan's
|
|
34
|
-
* `A`–`Z`) and any in-flight dispatches. `session/disposed` is wired in
|
|
35
|
-
* `src/index.ts`, which calls `clearSession(deps, sessionId)`; that drops this
|
|
36
|
-
* state along with the queue, anchors, plan and per-session runtime, so a
|
|
37
|
-
* disposed session leaves nothing behind.
|
|
38
|
-
*
|
|
39
|
-
* The class's internals stay private (`HookDeps` exposes only the optional
|
|
40
|
-
* instance), and only the plumbing helpers are exported. It lives apart from
|
|
41
|
-
* `post-execute.ts` because that file already carries the four mount bodies and
|
|
42
|
-
* the eleven obligations; mixing a mutable session map into it would make the
|
|
43
|
-
* hook harder to audit.
|
|
44
|
-
*
|
|
45
|
-
* @module dsh-boost/hooks/session-state
|
|
46
|
-
*/
|
|
47
|
-
import type { ReceiptAnchors } from '../gate/invalidate.js';
|
|
48
|
-
import type { ReceiptStore } from '../receipts/store.js';
|
|
49
|
-
import type { CanonicalReceipt } from '../projection/canonicalise.js';
|
|
50
|
-
import type { TurnClock } from './clock.js';
|
|
51
|
-
import type { PendingEntry, PendingQueue } from './pending.js';
|
|
52
|
-
/** One session's receipts and in-flight dispatches for the current turn. */
|
|
53
|
-
interface SessionEntry {
|
|
54
|
-
/** The host turn the entry belongs to; a different turn resets it. */
|
|
55
|
-
turn: number;
|
|
56
|
-
/** Receipts keyed by `'root'` or a plan candidate id. */
|
|
57
|
-
receipts: Map<string, CanonicalReceipt>;
|
|
58
|
-
/** `callId -> candidateId` for substitutions the execute hook accepted. */
|
|
59
|
-
dispatches: Map<string, string>;
|
|
60
|
-
}
|
|
61
|
-
/**
|
|
62
|
-
* Receipt and dispatch memory for every session the plugin has seen.
|
|
63
|
-
*
|
|
64
|
-
* `begin` is the only reader that can fold a turn away; callers use it once per
|
|
65
|
-
* hook invocation and then use the rest of the API. There is no eviction within
|
|
66
|
-
* a turn: a session's candidate receipts are exactly the steps of the current
|
|
67
|
-
* plan, and plan parsing caps a plan at 26 steps (`A`–`Z`).
|
|
68
|
-
*/
|
|
69
|
-
export declare class ReceiptSessionState {
|
|
70
|
-
private readonly bySession;
|
|
71
|
-
/**
|
|
72
|
-
* Return the state for `sessionId` at `turn`, discarding a previous turn's
|
|
73
|
-
* receipts and dispatches.
|
|
74
|
-
*
|
|
75
|
-
* `rolledOver` tells the caller that the previous turn's anchors (which live
|
|
76
|
-
* in `AnchorStore`, not here) are stale too and must be dropped. A brand-new
|
|
77
|
-
* session has nothing to roll over, so it reports `false`.
|
|
78
|
-
*/
|
|
79
|
-
begin(sessionId: string, turn: number): {
|
|
80
|
-
entry: SessionEntry;
|
|
81
|
-
rolledOver: boolean;
|
|
82
|
-
};
|
|
83
|
-
/** File the receipt that just arrived under `'root'`, keeping candidate receipts. */
|
|
84
|
-
recordRoot(sessionId: string, turn: number, receipt: CanonicalReceipt): void;
|
|
85
|
-
/** File an executed candidate's receipt under its plan candidate id. */
|
|
86
|
-
recordCandidate(sessionId: string, turn: number, candidateId: string, receipt: CanonicalReceipt): void;
|
|
87
|
-
/** The receipt map `decide` reads; contains `'root'` after `recordRoot`. */
|
|
88
|
-
receiptsFor(sessionId: string, turn: number): ReadonlyMap<string, CanonicalReceipt>;
|
|
89
|
-
/** Remember which candidate a dispatched call id belongs to. */
|
|
90
|
-
recordDispatch(sessionId: string, turn: number, callId: string, candidateId: string): void;
|
|
91
|
-
/** Consume the candidate id for `callId`, or `undefined` when the call is not one of ours. */
|
|
92
|
-
takeDispatch(sessionId: string, turn: number, callId: string): string | undefined;
|
|
93
|
-
/**
|
|
94
|
-
* Drop everything for one session: both maps and the stored turn.
|
|
95
|
-
*
|
|
96
|
-
* `src/index.ts` calls this from its `session/disposed` listener through
|
|
97
|
-
* `clearSession`; the hooks themselves only replace an entry lazily when the
|
|
98
|
-
* next turn's first call arrives.
|
|
99
|
-
*/
|
|
100
|
-
clear(sessionId: string): void;
|
|
101
|
-
}
|
|
102
|
-
/** The store's append input, shared by both hook modules. */
|
|
103
|
-
export type ReceiptInput = Parameters<ReceiptStore['append']>[0];
|
|
104
|
-
/** The dependencies these helpers read; `HookDeps` is structurally assignable. */
|
|
105
|
-
export interface SessionPlumbing {
|
|
106
|
-
/** Shared fallback clock when no per-session runtime is wired. */
|
|
107
|
-
clock?: TurnClock;
|
|
108
|
-
/** Per-session runtime; its clock is authoritative when present. */
|
|
109
|
-
sessions?: {
|
|
110
|
-
clockFor(sessionId: string): TurnClock;
|
|
111
|
-
};
|
|
112
|
-
/** At most one pending substitution per session. */
|
|
113
|
-
queue?: PendingQueue;
|
|
114
|
-
/** Per-session receipt anchors. */
|
|
115
|
-
anchors?: {
|
|
116
|
-
get(sessionId: string): ReceiptAnchors | undefined;
|
|
117
|
-
clear(sessionId: string): void;
|
|
118
|
-
};
|
|
119
|
-
/** Append-only receipt store. */
|
|
120
|
-
receipts?: ReceiptStore;
|
|
121
|
-
/** Parsed plans, keyed by session. */
|
|
122
|
-
plans?: {
|
|
123
|
-
delete(sessionId: string): boolean;
|
|
124
|
-
};
|
|
125
|
-
}
|
|
126
|
-
/**
|
|
127
|
-
* The session's host turn, or `undefined` when no clock can answer a real turn.
|
|
128
|
-
*
|
|
129
|
-
* The per-session runtime wins over the shared fallback, exactly as in
|
|
130
|
-
* `sessionClock`. A clock that throws, a missing clock and a non-finite or
|
|
131
|
-
* non-positive turn all mean "no host turn": `TurnClock` reports 0 before the
|
|
132
|
-
* first `agent/request`, and real host turns start at 1. Callers that need a
|
|
133
|
-
* number for a receipt field write `?? 0`; callers that decide turn validity
|
|
134
|
-
* keep the `undefined` distinction.
|
|
135
|
-
*/
|
|
136
|
-
export declare function clockTurnOf(deps: SessionPlumbing, sessionId: string): number | undefined;
|
|
137
|
-
/** The pending entry for a session, never removing it and never throwing. */
|
|
138
|
-
export declare function peekPending(deps: SessionPlumbing, sessionId: string): PendingEntry | undefined;
|
|
139
|
-
/** Drop the session's pending entry; a foreign queue must not break the call. */
|
|
140
|
-
export declare function clearPending(deps: SessionPlumbing, sessionId: string): void;
|
|
141
|
-
/** Drop the session's anchors; a foreign store must not break the call. */
|
|
142
|
-
export declare function clearAnchors(deps: SessionPlumbing, sessionId: string): void;
|
|
143
|
-
/** Drop the session's parsed plan; a foreign map must not break the call. */
|
|
144
|
-
export declare function clearPlan(deps: SessionPlumbing, sessionId: string): void;
|
|
145
|
-
/** Append one receipt; a receipt is evidence, never a precondition. */
|
|
146
|
-
export declare function appendReceipt(deps: SessionPlumbing, receipt: ReceiptInput): Promise<void>;
|
|
147
|
-
/** The first 256 code points of a canonical receipt, or of a synthesized call. */
|
|
148
|
-
export declare function previewOf(text: string | undefined): string;
|
|
149
|
-
/**
|
|
150
|
-
* The evidence line for a receipt that predates its tool result.
|
|
151
|
-
*
|
|
152
|
-
* A substitute or a refused dispatch has no canonical tool result yet, so its
|
|
153
|
-
* preview names the call that is being made (or was refused): the operator's
|
|
154
|
-
* question is "why did this call run?", and the name plus bound args is the
|
|
155
|
-
* answer available at that point.
|
|
156
|
-
*/
|
|
157
|
-
export declare function callPreview(name: string, args: unknown): string;
|
|
158
|
-
export {};
|
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The synthesized model turn: a fake assistant reply that asks for the tool
|
|
3
|
-
* call the plugin already decided on.
|
|
4
|
-
*
|
|
5
|
-
* The host's agent loop consumes chunks and then dispatches the tool call it
|
|
6
|
-
* saw. The chunk sequence is therefore a protocol, not a presentation choice:
|
|
7
|
-
*
|
|
8
|
-
* 1. a `reasoning` block, then
|
|
9
|
-
* 2. a `tool-call` block, then
|
|
10
|
-
* 3. a terminal `finish` with reason `tool-calls`.
|
|
11
|
-
*
|
|
12
|
-
* The reasoning block is emitted first so the assistant turn carries the
|
|
13
|
-
* sibling a reasoning-preserving adapter needs. DeepSeek's thinking mode
|
|
14
|
-
* requires the assistant `tool_use` message to carry a sibling `thinking` block
|
|
15
|
-
* (`content[].thinking … must be passed back`, appendix §7), and a synthesized
|
|
16
|
-
* turn with only a `tool-call` block cannot satisfy that on such a route.
|
|
17
|
-
*
|
|
18
|
-
* It does **not** reach the wire on this host build's current
|
|
19
|
-
* `openai-completions` route. A settled assistant message with no `replayState`
|
|
20
|
-
* is routed to `foreignAssistant` and stamped `api:'dsh-foreign'`
|
|
21
|
-
* (`dsh-llm-pi-ai/lib/index.js:180,250-252`), and pi-ai's `transformMessages`
|
|
22
|
-
* drops every thinking block of a non-same-model message
|
|
23
|
-
* (`transform-messages.js:87-96`). Emitting the block is still the right shape
|
|
24
|
-
* and costs nothing — a route that preserves reasoning needs it — but whether a
|
|
25
|
-
* route that enforces the sibling rule is satisfied end to end is a Task 24
|
|
26
|
-
* question, not a claim this module makes.
|
|
27
|
-
*
|
|
28
|
-
* The host's `ReasoningBlock` has exactly `type` and `text` — there is no
|
|
29
|
-
* signature field to fill in — so the block is emitted unsigned.
|
|
30
|
-
*
|
|
31
|
-
* No `usage` chunk is emitted: nothing was measured, and a fabricated usage
|
|
32
|
-
* would corrupt the token ledger. The chunk shape follows
|
|
33
|
-
* `StreamChunk`/`ContentBlock` in `@deepseek-ai/dsh-llm/types` field by field;
|
|
34
|
-
* in particular `tool-call.arguments` is the raw JSON string and must be
|
|
35
|
-
* byte-identical to the `argumentsDelta` that streamed it.
|
|
36
|
-
*
|
|
37
|
-
* The generator is pure over `e`: it reads no clock, no queue, and no I/O, so
|
|
38
|
-
* the same entry always produces the same chunks.
|
|
39
|
-
*
|
|
40
|
-
* @module dsh-boost/hooks/synthesize
|
|
41
|
-
*/
|
|
42
|
-
import type { StreamChunk } from '@deepseek-ai/dsh-llm';
|
|
43
|
-
import type { PendingEntry } from './pending.js';
|
|
44
|
-
/**
|
|
45
|
-
* Stream the turn that asks for `e`'s tool call.
|
|
46
|
-
*
|
|
47
|
-
* Yields, in order and with these indexes:
|
|
48
|
-
*
|
|
49
|
-
* ```text
|
|
50
|
-
* block-start {index:0, blockType:'reasoning'}
|
|
51
|
-
* reasoning-delta {index:0, text}
|
|
52
|
-
* block-end {index:0, block:{type:'reasoning', text}}
|
|
53
|
-
* block-start {index:1, blockType:'tool-call'}
|
|
54
|
-
* tool-call-delta {index:1, id, name, argumentsDelta}
|
|
55
|
-
* block-end {index:1, block:{type:'tool-call', id, name, arguments}}
|
|
56
|
-
* finish {reason:{kind:'tool-calls'}}
|
|
57
|
-
* ```
|
|
58
|
-
*
|
|
59
|
-
* **Invalid call id.** A `PendingEntry` with a blank `callId` (empty or
|
|
60
|
-
* whitespace-only) violates this module's contract and cannot be repaired here:
|
|
61
|
-
* inventing one would make the execute-side tamper check compare a different id
|
|
62
|
-
* and reject every dispatch silently. The generator throws `RangeError` before
|
|
63
|
-
* its first yield, so no partial turn reaches the host.
|
|
64
|
-
*
|
|
65
|
-
* **Unserialisable arguments.** `args` is plan-validated JSON in production,
|
|
66
|
-
* but this function is exported and must be total. When `JSON.stringify`
|
|
67
|
-
* throws (a `BigInt`, a cycle) or returns `undefined`, the turn emits the
|
|
68
|
-
* reasoning block and then a terminal `finish` with `kind:'error'` — it never
|
|
69
|
-
* emits a `tool-call` block, because substituting an empty or partial argument
|
|
70
|
-
* object would dispatch a call nobody decided. The error is a protocol chunk,
|
|
71
|
-
* not a thrown exception: appendix §1.1 defines errors as `finish.reason`, and
|
|
72
|
-
* a partially-consumed stream must not blow up the host loop.
|
|
73
|
-
*/
|
|
74
|
-
export declare function synthesizeTurn(e: PendingEntry): AsyncIterable<StreamChunk>;
|
package/dist/host/loader.d.ts
DELETED
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The optional-peer import seam.
|
|
3
|
-
*
|
|
4
|
-
* A static `import` of an optional host package is `ERR_MODULE_NOT_FOUND` at
|
|
5
|
-
* module-evaluation time, which kills the whole plugin before any degradation
|
|
6
|
-
* path can run (design §5.4/§9). Every optional peer — the spill policy and the
|
|
7
|
-
* token meter — must therefore load through this function, which turns a
|
|
8
|
-
* missing package (or one that throws while evaluating) into `undefined`.
|
|
9
|
-
*
|
|
10
|
-
* The function is deliberately total: a broken peer is the same as an absent
|
|
11
|
-
* one for the plugin's purposes, and a host that installed it badly must still
|
|
12
|
-
* get the plugin's degraded mode rather than a failed load.
|
|
13
|
-
*
|
|
14
|
-
* @module dsh-boost/host/loader
|
|
15
|
-
*/
|
|
16
|
-
/**
|
|
17
|
-
* Import `specifier`, or return `undefined` when it cannot be loaded.
|
|
18
|
-
*
|
|
19
|
-
* `T` is the module namespace the caller expects; it is not validated here —
|
|
20
|
-
* callers check the individual export they use, because a package can exist
|
|
21
|
-
* while an export is missing in another version.
|
|
22
|
-
*/
|
|
23
|
-
export declare function loadOptional<T>(specifier: string): Promise<T | undefined>;
|
package/dist/host/platform.d.ts
DELETED
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Platform capability: is the host a POSIX system?
|
|
3
|
-
*
|
|
4
|
-
* Substitution depends on POSIX process semantics (the dispatched call is
|
|
5
|
-
* synthesised and replayed through the host's tool pipeline), so on Windows it
|
|
6
|
-
* is refused. Projection does not depend on the platform and stays on. The
|
|
7
|
-
* refusal is not silent: `dsh-boost`'s `boost status` reports
|
|
8
|
-
* `ERR_HOST_PLATFORM_UNSUPPORTED` (design §9).
|
|
9
|
-
*
|
|
10
|
-
* The predicate reads `process.platform` at call time rather than caching it at
|
|
11
|
-
* module load, which is what makes the platform a seam a test can control
|
|
12
|
-
* (`Object.defineProperty(process, 'platform', …)`): a load-time constant would
|
|
13
|
-
* freeze the value before the test could change it.
|
|
14
|
-
*
|
|
15
|
-
* @module dsh-boost/host/platform
|
|
16
|
-
*/
|
|
17
|
-
/** Whether substitution may run on this host. Only `win32` is excluded. */
|
|
18
|
-
export declare const isPosixOnly: () => boolean;
|
package/dist/host/root.d.ts
DELETED
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* `<DSH_HOME>/boost`, falling back to `<homedir>/.dsh/boost`.
|
|
3
|
-
*
|
|
4
|
-
* A `config.dshHome` override wins over the environment, matching the other
|
|
5
|
-
* host plugins (`dsh-mcp-btwy` resolves `config.dshHome` before `$DSH_HOME`):
|
|
6
|
-
* an operator who patches the plugin row should not have to change the
|
|
7
|
-
* process environment for all plugins. A non-string or blank override is
|
|
8
|
-
* ignored and the environment rule applies.
|
|
9
|
-
*
|
|
10
|
-
* A blank value is treated as unset: `join('', 'boost')` would otherwise put
|
|
11
|
-
* state in the process's working directory, which is not a home directory.
|
|
12
|
-
*
|
|
13
|
-
* A relative home is resolved against the current cwd **once**, here.
|
|
14
|
-
* Passing it through would leave the stores resolving it again on every read,
|
|
15
|
-
* so a later `chdir` would silently move the state root mid-session (review
|
|
16
|
-
* minor).
|
|
17
|
-
*/
|
|
18
|
-
export declare function resolveBoostRoot(config?: unknown): string;
|