dsh-boost 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.en.md +476 -0
  4. package/README.md +408 -2
  5. package/cordis.patch.yml +40 -0
  6. package/dist/admission/fixed-cost.d.ts +23 -0
  7. package/dist/admission/fixed-cost.js +61 -0
  8. package/dist/admission/fixed-cost.js.map +1 -0
  9. package/dist/admission/ledger.d.ts +113 -0
  10. package/dist/admission/ledger.js +176 -0
  11. package/dist/admission/ledger.js.map +1 -0
  12. package/dist/admission/retrieval.d.ts +65 -0
  13. package/dist/admission/retrieval.js +162 -0
  14. package/dist/admission/retrieval.js.map +1 -0
  15. package/dist/admission/usage.d.ts +75 -0
  16. package/dist/admission/usage.js +124 -0
  17. package/dist/admission/usage.js.map +1 -0
  18. package/dist/config.d.ts +43 -0
  19. package/dist/config.js +103 -0
  20. package/dist/config.js.map +1 -0
  21. package/dist/gate/binding.d.ts +113 -0
  22. package/dist/gate/binding.js +297 -0
  23. package/dist/gate/binding.js.map +1 -0
  24. package/dist/gate/decide.d.ts +82 -0
  25. package/dist/gate/decide.js +163 -0
  26. package/dist/gate/decide.js.map +1 -0
  27. package/dist/gate/guard.d.ts +69 -0
  28. package/dist/gate/guard.js +195 -0
  29. package/dist/gate/guard.js.map +1 -0
  30. package/dist/gate/invalidate.d.ts +112 -0
  31. package/dist/gate/invalidate.js +111 -0
  32. package/dist/gate/invalidate.js.map +1 -0
  33. package/dist/gate/plan.d.ts +86 -0
  34. package/dist/gate/plan.js +222 -0
  35. package/dist/gate/plan.js.map +1 -0
  36. package/dist/hooks/clock.d.ts +68 -0
  37. package/dist/hooks/clock.js +82 -0
  38. package/dist/hooks/clock.js.map +1 -0
  39. package/dist/hooks/execute.d.ts +79 -0
  40. package/dist/hooks/execute.js +128 -0
  41. package/dist/hooks/execute.js.map +1 -0
  42. package/dist/hooks/llm-stream.d.ts +276 -0
  43. package/dist/hooks/llm-stream.js +1008 -0
  44. package/dist/hooks/llm-stream.js.map +1 -0
  45. package/dist/hooks/pending.d.ts +89 -0
  46. package/dist/hooks/pending.js +115 -0
  47. package/dist/hooks/pending.js.map +1 -0
  48. package/dist/hooks/post-execute.d.ts +247 -0
  49. package/dist/hooks/post-execute.js +1776 -0
  50. package/dist/hooks/post-execute.js.map +1 -0
  51. package/dist/hooks/session-state.d.ts +158 -0
  52. package/dist/hooks/session-state.js +168 -0
  53. package/dist/hooks/session-state.js.map +1 -0
  54. package/dist/hooks/synthesize.d.ts +74 -0
  55. package/dist/hooks/synthesize.js +100 -0
  56. package/dist/hooks/synthesize.js.map +1 -0
  57. package/dist/host/loader.d.ts +23 -0
  58. package/dist/host/loader.js +31 -0
  59. package/dist/host/loader.js.map +1 -0
  60. package/dist/host/platform.d.ts +18 -0
  61. package/dist/host/platform.js +19 -0
  62. package/dist/host/platform.js.map +1 -0
  63. package/dist/host/root.d.ts +18 -0
  64. package/dist/host/root.js +43 -0
  65. package/dist/host/root.js.map +1 -0
  66. package/dist/index.d.ts +13 -0
  67. package/dist/index.js +866 -0
  68. package/dist/index.js.map +1 -0
  69. package/dist/projection/apply.d.ts +174 -0
  70. package/dist/projection/apply.js +137 -0
  71. package/dist/projection/apply.js.map +1 -0
  72. package/dist/projection/canonicalise.d.ts +43 -0
  73. package/dist/projection/canonicalise.js +43 -0
  74. package/dist/projection/canonicalise.js.map +1 -0
  75. package/dist/projection/counters.d.ts +65 -0
  76. package/dist/projection/counters.js +88 -0
  77. package/dist/projection/counters.js.map +1 -0
  78. package/dist/projection/truncate.d.ts +47 -0
  79. package/dist/projection/truncate.js +57 -0
  80. package/dist/projection/truncate.js.map +1 -0
  81. package/dist/prompt/protocol.d.ts +45 -0
  82. package/dist/prompt/protocol.js +56 -0
  83. package/dist/prompt/protocol.js.map +1 -0
  84. package/dist/receipts/store.d.ts +198 -0
  85. package/dist/receipts/store.js +734 -0
  86. package/dist/receipts/store.js.map +1 -0
  87. package/dist/scope/doc.d.ts +117 -0
  88. package/dist/scope/doc.js +158 -0
  89. package/dist/scope/doc.js.map +1 -0
  90. package/dist/scope/resolve.d.ts +91 -0
  91. package/dist/scope/resolve.js +146 -0
  92. package/dist/scope/resolve.js.map +1 -0
  93. package/dist/scope/store.d.ts +135 -0
  94. package/dist/scope/store.js +573 -0
  95. package/dist/scope/store.js.map +1 -0
  96. package/dist/selector/jev.d.ts +93 -0
  97. package/dist/selector/jev.js +171 -0
  98. package/dist/selector/jev.js.map +1 -0
  99. package/dist/tools/boost.d.ts +367 -0
  100. package/dist/tools/boost.js +768 -0
  101. package/dist/tools/boost.js.map +1 -0
  102. package/dist/tools/family.d.ts +26 -0
  103. package/dist/tools/family.js +26 -0
  104. package/dist/tools/family.js.map +1 -0
  105. package/dist/types.d.ts +113 -0
  106. package/dist/types.js +21 -0
  107. package/dist/types.js.map +1 -0
  108. package/locale/en.json +6 -0
  109. package/locale/zh.json +6 -0
  110. package/package.json +75 -4
@@ -0,0 +1,247 @@
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;