dsh-boost 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.en.md +141 -51
  2. package/README.md +115 -47
  3. package/dist/admission/usage.js +41 -7
  4. package/dist/admission/usage.js.map +1 -1
  5. package/dist/gate/decide.js +33 -2
  6. package/dist/gate/decide.js.map +1 -1
  7. package/dist/hooks/llm-stream.js +232 -58
  8. package/dist/hooks/llm-stream.js.map +1 -1
  9. package/dist/hooks/post-execute.js +206 -39
  10. package/dist/hooks/post-execute.js.map +1 -1
  11. package/dist/hooks/session-state.js +18 -8
  12. package/dist/hooks/session-state.js.map +1 -1
  13. package/dist/index.js +601 -72
  14. package/dist/index.js.map +1 -1
  15. package/dist/scope/doc.js.map +1 -1
  16. package/dist/scope/store.js +24 -9
  17. package/dist/scope/store.js.map +1 -1
  18. package/dist/tools/boost.js +82 -2
  19. package/dist/tools/boost.js.map +1 -1
  20. package/package.json +9 -5
  21. package/dist/admission/fixed-cost.d.ts +0 -23
  22. package/dist/admission/ledger.d.ts +0 -113
  23. package/dist/admission/retrieval.d.ts +0 -65
  24. package/dist/admission/usage.d.ts +0 -75
  25. package/dist/config.d.ts +0 -43
  26. package/dist/gate/binding.d.ts +0 -113
  27. package/dist/gate/decide.d.ts +0 -82
  28. package/dist/gate/guard.d.ts +0 -69
  29. package/dist/gate/invalidate.d.ts +0 -112
  30. package/dist/gate/plan.d.ts +0 -86
  31. package/dist/hooks/clock.d.ts +0 -68
  32. package/dist/hooks/execute.d.ts +0 -79
  33. package/dist/hooks/llm-stream.d.ts +0 -283
  34. package/dist/hooks/pending.d.ts +0 -89
  35. package/dist/hooks/post-execute.d.ts +0 -257
  36. package/dist/hooks/session-state.d.ts +0 -158
  37. package/dist/hooks/synthesize.d.ts +0 -74
  38. package/dist/host/loader.d.ts +0 -23
  39. package/dist/host/platform.d.ts +0 -18
  40. package/dist/host/root.d.ts +0 -25
  41. package/dist/projection/apply.d.ts +0 -174
  42. package/dist/projection/canonicalise.d.ts +0 -43
  43. package/dist/projection/counters.d.ts +0 -65
  44. package/dist/projection/truncate.d.ts +0 -47
  45. package/dist/prompt/protocol.d.ts +0 -45
  46. package/dist/receipts/store.d.ts +0 -198
  47. package/dist/scope/doc.d.ts +0 -117
  48. package/dist/scope/resolve.d.ts +0 -91
  49. package/dist/scope/store.d.ts +0 -135
  50. package/dist/selector/jev.d.ts +0 -93
  51. package/dist/tools/boost.d.ts +0 -380
  52. package/dist/tools/family.d.ts +0 -26
@@ -1,380 +0,0 @@
1
- /**
2
- * The `boost` control tool: the user's only way to see or change what the
3
- * plugin is doing.
4
- *
5
- * The plugin itself is invisible — it rewrites what the model sees and never
6
- * speaks — so this tool's output is part of the product, not a debugging aid.
7
- * `status` reports what the plugin has actually recorded: the scope document's
8
- * exposure surface, both switches (`shadow` and `projection`; "recording but
9
- * not replacing" is not "replacing"), per-code receipt counts over **every**
10
- * shard, the substitution and projection ledgers, and the stable degraded
11
- * codes observed. `scope-get` reads `scope.json`; `scope-set` and `shadow`
12
- * write it; both writes are compare-and-swap through `ScopeStore.write`, so a
13
- * stale caller gets `ERR_SCOPE_REVISION_CONFLICT` rather than silently
14
- * overwriting a concurrent change.
15
- *
16
- * ## Contracts this module keeps
17
- *
18
- * - Every failure is a stable code in a returned value; nothing throws out of
19
- * `runBoost`. The store's own codes are passed through unchanged.
20
- * - `scope-set` never lets a caller set `version` or `revision`: `revision` is
21
- * the store's, `version` is fixed at 2, and a body carrying either reserved
22
- * field is rejected **before** the mutation runs. The store persists whatever
23
- * `mutate` returns, so this rejection is what stops a v1-shaped document.
24
- * - Both ledger sides come from the receipts. This module never estimates a
25
- * retrieval cost: an unpriced retrieval makes the net `'unknown'` rather
26
- * than free, and `projection_unpriced_retrievals` says how many there were.
27
- * A retrieval's own projection is excluded from gross because its visible
28
- * window is already charged as retrieval content. The projection saving is
29
- * read from `saved_projection_tokens` (the design §5.3 name T23b/T26 write),
30
- * falling back to `saved`; a producer must write one of them, while a
31
- * meterless projection has neither and makes gross/net `'unknown'`. The
32
- * substitution saving is read only from the settled line, because the
33
- * synth-time line predates any measurement.
34
- * - `status.degraded` is a list of **stable codes only** (`ERR_HOST_*` /
35
- * `ERR_SCOPE_*`; the one wiring code is `ERR_BOOST_PARTIAL_MOUNT`). The scope
36
- * store's internal `scope-degraded` label and the
37
- * receipt stream's `projection-skipped:*` are inputs, not output: a receipt
38
- * code is mapped to `ERR_HOST_NO_SPILL` (no spill backend),
39
- * `ERR_HOST_SPILL_FAILING` (backend present, every write rejected) or
40
- * `ERR_HOST_NO_SPILL_NOTICE` (backend present, notice module cannot render
41
- * the footer), and a degraded scope read passes its `ERR_SCOPE_*` code
42
- * through. The two estimator absences are separate codes:
43
- * `ERR_HOST_NO_TOKENMETER` is the host service probe (`apply` records whether
44
- * the synchronous token meter exists), while `ERR_HOST_NO_ESTIMATOR` is the
45
- * pure fixed-cost package being unreachable. One can exist without the other,
46
- * and merging them sent the operator to the wrong host.
47
- * `ERR_HOST_PLATFORM_UNSUPPORTED` is `isPosixOnly()` being false.
48
- * `ERR_BOOST_PARTIAL_MOUNT` is an `apply` wiring failure: at least one of the
49
- * four host mounts (prompt section, post-execute, llm/stream, execute) is
50
- * missing, so the plugin is loaded but not fully wired.
51
- * - The fixed overhead is measured **once at startup**
52
- * (`measureBoostFixedOverhead`: protocol section + tool schema) and awaited
53
- * by `status`; it is never on a request path (design §6.1).
54
- * - `runBoost` is pure orchestration over the two stores plus the host facts
55
- * `apply` hands it: no `ctx`, no host calls beyond the one measurement. The
56
- * tool definition is therefore testable without a host, and the host probe
57
- * lives in `src/index.ts`.
58
- *
59
- * The command table is deliberately a plain record, one handler per
60
- * subcommand, so an unknown `cmd` is a lookup miss rather than a fallthrough.
61
- *
62
- * @module dsh-boost/tools/boost
63
- */
64
- import type { JsonSchemaNode } from '@deepseek-ai/dsh-tools';
65
- import type { FixedOverheadMeasurement } from '../admission/fixed-cost.js';
66
- import type { ProjectionMode } from '../projection/apply.js';
67
- import type { ScopeDoc } from '../scope/doc.js';
68
- import type { ScopeStore } from '../scope/store.js';
69
- import type { ReceiptStore } from '../receipts/store.js';
70
- /**
71
- * Host capabilities `apply` probes once and hands `status`.
72
- *
73
- * Every field is optional because `runBoost` is also usable without a host
74
- * (unit tests, and the control tool built before `apply` wires the probe). An
75
- * absent fact means "not probed", never "supported": the status code list then
76
- * simply omits the corresponding code rather than guessing.
77
- */
78
- export interface BoostHostFacts {
79
- /** Whether `ctx.get('tokenMeter')` exposed the synchronous message estimator. */
80
- hasTokenMeter?: boolean;
81
- /** Whether `ctx.get('spillStore')` exposed the projection backend. */
82
- hasSpill?: boolean;
83
- /**
84
- * Whether `ctx.get('workspaceRegistry')` ever became available.
85
- *
86
- * A missing registry makes every session invisible, which presents to the
87
- * operator as "nothing ever happens" with no error anywhere. It is a host
88
- * fact rather than an assembly detail because that failure mode has to be
89
- * diagnosable from inside the product.
90
- */
91
- hasWorkspaceRegistry?: boolean;
92
- }
93
- /** The two stores `runBoost` orchestrates, plus the host facts it reports. */
94
- export interface BoostDeps {
95
- scope: ScopeStore;
96
- receipts: ReceiptStore;
97
- /** Host capabilities measured by `apply`; absent when no host was probed. */
98
- host?: BoostHostFacts;
99
- /**
100
- * The one fixed-overhead measurement, started at plugin load.
101
- *
102
- * A function rather than a promise so `status` can await it lazily; the
103
- * default reuses the module-level memoised measurement.
104
- */
105
- fixedOverhead?: () => Promise<FixedOverheadMeasurement | 'unknown'>;
106
- /**
107
- * Which estimator priced this assembly's figures.
108
- *
109
- * `host` means the synchronous host meter; `unknown` means no token meter,
110
- * so no number is fabricated (design §9). There is deliberately no
111
- * `chars/4` arm: a characters-over-four guess is not a measurement, and a
112
- * receipt that says `unknown` is more useful than one that is wrong.
113
- */
114
- estimateKind?: 'host' | 'unknown';
115
- /**
116
- * The current replay horizon; defaults to the design's 20.
117
- *
118
- * Receipts carry their own `horizon_steps`, so this is only the fallback for
119
- * receipts written before that field existed (counted in
120
- * `projection_horizon_reestimated`) — not a factor applied to the whole
121
- * ledger.
122
- */
123
- horizonSteps?: number;
124
- /** Locators evicted by the per-session cap; status-time read. */
125
- locatorEvictions?: () => number;
126
- /**
127
- * Receipt shards whole-store scans had to skip since the last scan that read
128
- * every shard; status-time read.
129
- *
130
- * This is the **only** source of `ERR_RECEIPTS_UNREADABLE`: the store skips
131
- * an unreadable shard per shard and reports the count, so `status` has one
132
- * mechanism rather than a status-side scan flag that no production store can
133
- * raise. Absent means the store has no such counter (or none was skipped);
134
- * the count clears when a scan reads every shard.
135
- */
136
- receiptReadErrors?: () => number;
137
- /**
138
- * Whether the status scan stopped at the store's 256-shard cap; status-time
139
- * read.
140
- *
141
- * True means every total in the answer covers only the first 256 sorted
142
- * shards: the figures are a lower bound, not the whole ledger. Absent means
143
- * the store has no such flag (or the last scan fitted), which is the
144
- * pre-existing "totals are complete" reading.
145
- */
146
- receiptsTruncated?: () => boolean;
147
- /** Calls skipped because no family matched; status-time read. */
148
- unknownFamilies?: () => number;
149
- /** Retained unmapped tool names; status-time read. */
150
- unknownTools?: () => Record<string, number>;
151
- /**
152
- * Prompt assemblies whose protocol section was suppressed; status-time read.
153
- *
154
- * The prompt path is the one mount that acts on every request, so design
155
- * §5.5:378 makes it a count rather than a receipt. It is exposed because the
156
- * shipped default scope is *correctly* inert: with no counter, "nothing
157
- * configured" and "assembly failed" look identical from `status`.
158
- */
159
- protocolSuppressed?: () => number;
160
- /** Requests whose final prompt lost the protocol to a complete section; status-time read. */
161
- completeSectionSuppressions?: () => number;
162
- /**
163
- * Integration points `apply` could not mount; status-time read.
164
- *
165
- * A missing projection or flush hook leaves every ledger healthy-looking
166
- * while the plugin never acts, so the mounts are a fact `status` must
167
- * report. Absent means no mount failed (or the caller does not track them).
168
- */
169
- partialMounts?: () => readonly string[];
170
- /**
171
- * Cancellation for this invocation only.
172
- *
173
- * `runBoost` is also callable directly (tests, future hosts), so this is
174
- * optional; `boostTool.execute` fills it from the host's `exec.signal` and a
175
- * cancelled call leaves `scope.json` untouched.
176
- */
177
- signal?: AbortSignal;
178
- }
179
- /** The four subcommands. */
180
- type BoostCmd = 'status' | 'scope-get' | 'scope-set' | 'shadow';
181
- /** What `status` reports. Both switches are top-level on purpose: they differ. */
182
- export interface BoostStatus {
183
- scope: {
184
- mode: ScopeDoc['mode'];
185
- workspaceIds: string[];
186
- revision: number;
187
- };
188
- shadow: boolean;
189
- projection: ProjectionMode;
190
- saved: {
191
- /**
192
- * Σ numeric `saved_input_tokens` over settled substitutions only. The
193
- * synth-time `substitute` line predates any measurement (design §5.3 says
194
- * the field is measured), so its value is `'unknown'` or absent and never
195
- * contributes; `counts` keeps the event count.
196
- */
197
- substitution: number;
198
- /**
199
- * Σ `saved_projection_tokens` over non-retrieval projections, **replayed**
200
- * by each receipt's own `horizon_steps`.
201
- *
202
- * Replay-aware so this legacy object no longer mixes a one-time gross with
203
- * a replay net (review R2). The one-time figure is the top-level
204
- * `projection_gross_tokens`. A receipt that predates `horizon_steps` is
205
- * replayed at the current horizon; `projection_horizon_reestimated` counts
206
- * those, so a re-estimated figure is never mistaken for a measured one.
207
- */
208
- projectionGross: number | 'unknown';
209
- /**
210
- * Σ saved × (1 + that receipt's horizon) − Σ content × (1 + its horizon)
211
- * − Σ call blocks − legacy replay-aware costs.
212
- *
213
- * `'unknown'` when any retrieval in the ledger is unpriced: an unmeasured
214
- * cost must never silently become zero (review R3).
215
- */
216
- projectionNet: number | 'unknown';
217
- /** Number of `kind:'projection'` receipts marked `retrieved: true`. */
218
- retrievals: number;
219
- };
220
- /** Receipt count per `code`, over every shard (including the empty session id). */
221
- counts: Record<string, number>;
222
- /** Stable degradation codes actually observed. */
223
- degraded: string[];
224
- /**
225
- * Whether the host ever exposed a workspace registry.
226
- *
227
- * Reported separately from {@link degraded} because it is the single fact
228
- * that explains "the plugin is installed and nothing ever happens": with no
229
- * registry, no session resolves to a workspace and every path is inert.
230
- * Absent when no host was probed.
231
- */
232
- hasWorkspaceRegistry?: boolean;
233
- /**
234
- * The measured per-request fixed cost: protocol section + tool schema.
235
- *
236
- * `'unknown'` when the host estimator is unreachable: the measurement is
237
- * never fabricated (design §9). Status-time only; see
238
- * `src/admission/fixed-cost.ts`.
239
- */
240
- fixedOverheadTokens: number | 'unknown';
241
- /** The two components behind {@link fixedOverheadTokens}. */
242
- fixedOverhead: FixedOverheadMeasurement | 'unknown';
243
- /**
244
- * Whether the ledger figures are provider-metered or estimates.
245
- *
246
- * `unknown` means no token meter: projection still clips, but its receipts
247
- * carry `'unknown'` rather than invented numbers, and substitution is
248
- * refused (design §9).
249
- */
250
- estimate_kind: 'host' | 'unknown';
251
- /** The current `(1 + horizon)` replay factor; the fallback for old receipts. */
252
- projection_horizon_steps: number;
253
- /**
254
- * Projection receipts replayed at {@link projection_horizon_steps} because
255
- * they predate the per-receipt `horizon_steps` field.
256
- *
257
- * `0` means every replay figure in this report is the horizon its own
258
- * decision was made under. A non-zero value marks that part of the net is
259
- * re-estimated, not measured: an operator reading the shadow-week go/no-go
260
- * must be able to tell the two apart.
261
- */
262
- projection_horizon_reestimated: number;
263
- /**
264
- * Σ one-time `saved_projection_tokens` over applied projections whose call
265
- * was **not** itself a retrieval.
266
- *
267
- * A retrieval's own projection is excluded: crediting it here while also
268
- * charging its visible window as retrieval cost would count the same tokens
269
- * from both sides (review I3).
270
- */
271
- projection_gross_tokens: number | 'unknown';
272
- /** {@link projection_gross_tokens} replayed at each receipt's own horizon. */
273
- projection_gross_replay_tokens: number | 'unknown';
274
- /** Σ one-time retrieval totals (call + content); `0` for unpriced receipts. */
275
- projection_retrieval_tokens: number;
276
- /** Σ one-time retrieval content, the side that replays with the gross. */
277
- projection_retrieval_content_tokens: number;
278
- /** Σ one-time retrieval call blocks; replay does not apply to these. */
279
- projection_retrieval_call_tokens: number;
280
- /** Projections with no measured saving; the gross/net become `'unknown'`. */
281
- projection_unpriced_projections: number;
282
- /** Retrievals with no usable token fields; their cost makes the net unknown. */
283
- projection_unpriced_retrievals: number;
284
- /** Pre-schema retrievals priced through the old `retrievalCost` field. */
285
- projection_legacy_retrievals: number;
286
- /**
287
- * The design's receipt-field spelling of `saved.retrievals`.
288
- *
289
- * Kept at the top level because the shadow-week operator reads the two
290
- * ledgers by the names §5.3 gives them; `saved` keeps the original camelCase
291
- * shape so existing consumers keep working. Both are derived from one
292
- * aggregation, so they cannot drift.
293
- */
294
- projection_retrievals: number;
295
- /**
296
- * Σ saved × (1 + receipt horizon) − Σ retrieval content × (1 + its horizon)
297
- * − Σ retrieval call blocks.
298
- *
299
- * The retrieval's own projection is not in the gross, the content it made
300
- * visible replays at the horizon in effect when the retrieval happened, and
301
- * its call block is charged once. `'unknown'` when a retrieval is unpriced or
302
- * a meterless projection was clipped: a lower bound cannot be computed from a
303
- * missing measurement.
304
- */
305
- projection_net_tokens: number | 'unknown';
306
- /** Locators dropped by the per-session cap; a lossy ledger is visible. */
307
- projection_locator_evictions: number;
308
- /** Calls skipped because no projection family matched. */
309
- projection_unknown_families: number;
310
- /** Retained unmapped tool names (at most 32), for mapper-gap diagnosis. */
311
- projection_unknown_tools: Record<string, number>;
312
- /**
313
- * Prompt assemblies whose protocol section was suppressed.
314
- *
315
- * Counted, never receipted, because assembly runs on every request (design
316
- * §5.5:378). A live, monotonically increasing number is the only evidence
317
- * that the inert-looking default is "no workspace configured" rather than a
318
- * section that failed to inject.
319
- */
320
- protocol_suppressed: number;
321
- /**
322
- * Whether the receipt store stopped accepting writes (fail-closed).
323
- *
324
- * Once true, substitution is refused outright (design §5.2-3) and every
325
- * figure above is a stale snapshot. Reported because the alternative is an
326
- * operator reading frozen numbers with no warning that they froze.
327
- */
328
- receipts_stopped: boolean;
329
- }
330
- /**
331
- * Run one `boost` invocation. Pure orchestration over the two stores.
332
- *
333
- * Failures are values: an unknown command, an invalid body or a store code all
334
- * come back as `{ ok: false, code }`. The `try` covers the argument read as
335
- * well as the handler, so a null call or an argument object with a throwing
336
- * getter answers a stable code instead of throwing. The catch exists only so
337
- * an unexpected store failure cannot turn the user's only control surface into
338
- * a thrown tool error; it is not an expected path.
339
- */
340
- export declare function runBoost(input: BoostDeps & {
341
- args: {
342
- cmd: BoostCmd;
343
- body?: unknown;
344
- baseRevision?: number;
345
- };
346
- }): Promise<{
347
- ok: true;
348
- data: unknown;
349
- } | {
350
- ok: false;
351
- code: string;
352
- }>;
353
- /**
354
- * The startup probe `apply` fires once and `status` awaits.
355
- *
356
- * Memoised per process: a status call must report the same number the startup
357
- * measured, and must not re-import or re-price the schema.
358
- */
359
- export declare function measureBoostFixedOverhead(): Promise<FixedOverheadMeasurement | 'unknown'>;
360
- /**
361
- * Build the host tool definition.
362
- *
363
- * `output: { schema, render }` is mandatory in the host's `ToolDefinition`;
364
- * a definition missing it is rejected at registration. `execute` reuses
365
- * `runBoost`, so the tool and the pure orchestration cannot drift.
366
- */
367
- export declare function boostTool(deps: BoostDeps): {
368
- name: 'boost';
369
- description: string;
370
- parameters: Record<string, unknown>;
371
- output: {
372
- schema: JsonSchemaNode;
373
- render: (args: unknown, value: unknown) => {
374
- type: 'text';
375
- text: string;
376
- }[];
377
- };
378
- execute: (args: unknown, exec: unknown) => Promise<unknown>;
379
- };
380
- export {};
@@ -1,26 +0,0 @@
1
- /**
2
- * Host tool name → projection family.
3
- *
4
- * The projection windows are keyed by family (`read`/`grep`/`glob`/`bash`/
5
- * `ssh`), but the host names MCP-backed tools with a decoration:
6
- * `mcp__ssh__execute-command`. A miss here is silent — `projectDecision`
7
- * simply returns the receipt unchanged — so this mapping is the only thing
8
- * that keeps projection enabled for the ssh family.
9
- *
10
- * The rule is deliberately narrow. A bare family name maps to itself; an MCP
11
- * name maps only when the **server** segment is itself a family. `web_fetch`,
12
- * `edit`, `mcp__filesystem__read_file` and every future tool have no window
13
- * (design §5.3), and the last one must not be mistaken for `read` just because
14
- * its method is named `read_file`.
15
- *
16
- * @module dsh-boost/tools/family
17
- */
18
- import type { ToolFamily } from '../types.js';
19
- /**
20
- * The projection family for a host tool name, or `undefined` when it has none.
21
- *
22
- * `undefined` is the design's "pass through unchanged" case, not an error.
23
- * The name is validated defensively because `exec.name` crosses the host
24
- * boundary and is typed loosely at the hook.
25
- */
26
- export declare function familyOf(name: string): ToolFamily | undefined;