dsh-boost 0.1.1 → 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.
Files changed (48) hide show
  1. package/README.en.md +97 -33
  2. package/README.md +85 -32
  3. package/dist/gate/decide.js +33 -2
  4. package/dist/gate/decide.js.map +1 -1
  5. package/dist/hooks/llm-stream.js +129 -54
  6. package/dist/hooks/llm-stream.js.map +1 -1
  7. package/dist/hooks/post-execute.js +104 -21
  8. package/dist/hooks/post-execute.js.map +1 -1
  9. package/dist/hooks/session-state.js +18 -8
  10. package/dist/hooks/session-state.js.map +1 -1
  11. package/dist/index.js +371 -67
  12. package/dist/index.js.map +1 -1
  13. package/dist/scope/doc.js.map +1 -1
  14. package/dist/scope/store.js +24 -9
  15. package/dist/scope/store.js.map +1 -1
  16. package/package.json +8 -4
  17. package/dist/admission/fixed-cost.d.ts +0 -23
  18. package/dist/admission/ledger.d.ts +0 -113
  19. package/dist/admission/retrieval.d.ts +0 -65
  20. package/dist/admission/usage.d.ts +0 -75
  21. package/dist/config.d.ts +0 -43
  22. package/dist/gate/binding.d.ts +0 -113
  23. package/dist/gate/decide.d.ts +0 -82
  24. package/dist/gate/guard.d.ts +0 -69
  25. package/dist/gate/invalidate.d.ts +0 -112
  26. package/dist/gate/plan.d.ts +0 -86
  27. package/dist/hooks/clock.d.ts +0 -68
  28. package/dist/hooks/execute.d.ts +0 -79
  29. package/dist/hooks/llm-stream.d.ts +0 -283
  30. package/dist/hooks/pending.d.ts +0 -89
  31. package/dist/hooks/post-execute.d.ts +0 -257
  32. package/dist/hooks/session-state.d.ts +0 -158
  33. package/dist/hooks/synthesize.d.ts +0 -74
  34. package/dist/host/loader.d.ts +0 -23
  35. package/dist/host/platform.d.ts +0 -18
  36. package/dist/host/root.d.ts +0 -25
  37. package/dist/projection/apply.d.ts +0 -174
  38. package/dist/projection/canonicalise.d.ts +0 -43
  39. package/dist/projection/counters.d.ts +0 -65
  40. package/dist/projection/truncate.d.ts +0 -47
  41. package/dist/prompt/protocol.d.ts +0 -45
  42. package/dist/receipts/store.d.ts +0 -198
  43. package/dist/scope/doc.d.ts +0 -117
  44. package/dist/scope/resolve.d.ts +0 -91
  45. package/dist/scope/store.d.ts +0 -135
  46. package/dist/selector/jev.d.ts +0 -93
  47. package/dist/tools/boost.d.ts +0 -380
  48. package/dist/tools/family.d.ts +0 -26
@@ -86,7 +86,7 @@ import { DEFAULT_SCOPE, isVisible } from '../scope/doc.js';
86
86
  import { SELECTOR_SYSTEM_PROMPT, choose, selectorPromptText } from '../selector/jev.js';
87
87
  import { familyOf } from '../tools/family.js';
88
88
  import { rejectIfTampered } from './execute.js';
89
- import { receiptsStopped, sessionBudget, sessionClock, sessionUsage, settleDiscarded, streamHook, } from './llm-stream.js';
89
+ import { budgetWired, receiptsStopped, sessionBudget, sessionClock, sessionUsage, settleDiscarded, streamHook, } from './llm-stream.js';
90
90
  import { callIdFor } from './pending.js';
91
91
  import { ReceiptSessionState, appendReceipt, callPreview, clearAnchors, clearPlan, clearPending, clockTurnOf, peekPending, previewOf, } from './session-state.js';
92
92
  /**
@@ -667,25 +667,37 @@ function admittedFor(deps, sessionId, plan, overheadTokens) {
667
667
  *
668
668
  * A selector call is real spend, so this check runs before the selector is
669
669
  * priced or called; the consuming `takeBudget` stays at the commit point.
670
- * A missing or foreign budget means "not exhausted", matching `takeBudget`'s
671
- * no-cap contract. Shadow mode never calls this: it spends no step.
670
+ * `undefined` from `sessionBudget` has two different meanings (row 21): no
671
+ * budget is wired at all (no cap), or one is wired but was not lent to this
672
+ * session (exhausted, fail closed). Shadow mode never calls this: it spends no
673
+ * step.
672
674
  */
673
675
  function budgetExhausted(deps, sessionId) {
674
676
  try {
675
677
  const budget = sessionBudget(deps, sessionId);
676
- if (budget == null || typeof budget.exhausted !== 'function')
678
+ if (budget == null)
679
+ return budgetWired(deps);
680
+ if (typeof budget.exhausted !== 'function')
677
681
  return false;
678
682
  return budget.exhausted() === true;
679
683
  }
680
684
  catch {
681
- return false;
685
+ return budgetWired(deps);
682
686
  }
683
687
  }
684
- /** Claim one budget step; no budget wired means no cap is applied. */
688
+ /**
689
+ * Claim one budget step.
690
+ *
691
+ * No budget wired means no cap is applied. A wired budget that this session may
692
+ * not borrow is a refusal, not "no cap": `take` fails and the caller records
693
+ * `steps-exhausted` without enqueueing (row 21).
694
+ */
685
695
  function takeBudget(deps, sessionId) {
686
696
  try {
687
697
  const budget = sessionBudget(deps, sessionId);
688
- if (budget == null || typeof budget.take !== 'function')
698
+ if (budget == null)
699
+ return !budgetWired(deps);
700
+ if (typeof budget.take !== 'function')
689
701
  return true;
690
702
  return budget.take();
691
703
  }
@@ -722,10 +734,14 @@ function pendingCandidateOf(deps, sessionId) {
722
734
  * accepted dispatch is mirrored here together with the evidence that would
723
735
  * otherwise be parked for the next settlement.
724
736
  *
725
- * One record per session: a later accepted dispatch replaces it, a session
726
- * whose usage mark is already gone drops it, and a rollover consumes it. The
727
- * `HookDeps` key keeps two assemblies in one process from reading each other's
728
- * sessions. The record is small and per-session; it is never persisted.
737
+ * One record per session: a later accepted dispatch (or a later synthesis)
738
+ * replaces it, a session whose usage mark is already gone drops it, and a
739
+ * rollover consumes it. The `HookDeps` key keeps two assemblies in one process
740
+ * from reading each other's sessions. The record is small and per-session; it
741
+ * is never persisted. It is also written at synthesis time through
742
+ * {@link HookDeps.noteSynthesis}: a dispatch denied by `tools/pre-execute`
743
+ * never reaches `tools/execute`, and that skipped model round must still be
744
+ * reportable at a rollover (row 27).
729
745
  */
730
746
  const ACCEPTED_DISPATCH = new WeakMap();
731
747
  /** Mirror an accepted dispatch for a possible rollover settlement. */
@@ -746,7 +762,8 @@ function noteAcceptedDispatch(deps, sessionId, turn, candidateId, evidence) {
746
762
  *
747
763
  * The turn check is a staleness guard: the record that a pending mark belongs
748
764
  * to was written in the turn now rolling over. A record written in the new
749
- * turn cannot belong to it.
765
+ * turn cannot belong to it. The record's own turn is returned so the settled
766
+ * receipt pairs with the dispatch, not with the rollover (row 26).
750
767
  */
751
768
  function takeAcceptedDispatch(deps, sessionId, candidateId, turn) {
752
769
  const bySession = ACCEPTED_DISPATCH.get(deps);
@@ -755,7 +772,9 @@ function takeAcceptedDispatch(deps, sessionId, candidateId, turn) {
755
772
  if (record === undefined || record.candidateId !== candidateId || record.turn === turn) {
756
773
  return undefined;
757
774
  }
758
- return record.evidence === undefined ? {} : { evidence: record.evidence };
775
+ return record.evidence === undefined
776
+ ? { turn: record.turn }
777
+ : { turn: record.turn, evidence: record.evidence };
759
778
  }
760
779
  /** Drop the mirrored dispatch; no pending mark is waiting to settle it. */
761
780
  export function clearAcceptedDispatch(deps, sessionId) {
@@ -768,11 +787,13 @@ export function clearAcceptedDispatch(deps, sessionId) {
768
787
  * parallel tool result can roll the turn before that request; the mark must not
769
788
  * survive into the new turn, where it would pair with a request that is not the
770
789
  * substitution's next one. If `tools/execute` never accepted the synthesized
771
- * dispatch, the substitution did not run and the mark is a discard. If it did,
772
- * the model round really was skipped: the settlement line is written with
773
- * whatever sample the ledger holds (`'unknown'` when no after-mark request has
774
- * run yet) and with the evidence captured at dispatch, so the substitution is
775
- * reported instead of disappearing.
790
+ * dispatch, the substitution did not run and the mark is a discard. If it did
791
+ * — or if the synthesis itself was mirrored before a `tools/pre-execute`
792
+ * denial (row 27) — the model round really was skipped: the settlement line is
793
+ * written with whatever sample the ledger holds (`'unknown'` when no after-mark
794
+ * request has run yet), with the evidence captured at dispatch, and with the
795
+ * dispatch turn the mirror recorded rather than the rollover turn (row 26), so
796
+ * the substitution is reported instead of disappearing.
776
797
  */
777
798
  async function settleRollover(deps, sessionId, turn) {
778
799
  const candidateId = pendingCandidateOf(deps, sessionId);
@@ -808,7 +829,10 @@ async function settleRollover(deps, sessionId, turn) {
808
829
  version: 1,
809
830
  ts: new Date().toISOString(),
810
831
  sessionId,
811
- turn,
832
+ // Row 26: the substitution happened in the dispatch turn the mirror
833
+ // recorded. Stamping the rollover turn paired a turn-1 substitution with a
834
+ // turn-2 settled line, which reads as a saving from the wrong round.
835
+ turn: dispatched.turn,
812
836
  stepId: 'root',
813
837
  kind: 'substitute-settled',
814
838
  code: 'substitute-settled',
@@ -1061,12 +1085,43 @@ async function chooseCandidate(deps, ctx, candidates, receiptText) {
1061
1085
  return undefined;
1062
1086
  }
1063
1087
  }
1088
+ // ---------------------------------------------------------------------------
1089
+ // Row 7: the step's admitted tool set
1090
+ // ---------------------------------------------------------------------------
1091
+ /**
1092
+ * Read this step's admission predicate, or `undefined` when it cannot be
1093
+ * verified.
1094
+ *
1095
+ * `view(scope)` takes the exact requesting agent; the host admits no other
1096
+ * scope. A missing `toolSet`, a missing `view` and a throwing `view` are all
1097
+ * "no evidence" and take the documented `no-toolset` path: the substitution
1098
+ * proceeds and records that it ran without admission evidence. Refusing on
1099
+ * absence would silently disable the feature on paths we cannot enumerate,
1100
+ * while a real model step always carries one (row 7).
1101
+ */
1102
+ function admissionViewOf(exec) {
1103
+ const toolSet = exec?.toolSet;
1104
+ if (toolSet == null || typeof toolSet.view !== 'function')
1105
+ return undefined;
1106
+ try {
1107
+ const view = toolSet.view(exec?.agent);
1108
+ if (view == null || typeof view.has !== 'function')
1109
+ return undefined;
1110
+ return (tool) => view.has(tool) === true;
1111
+ }
1112
+ catch {
1113
+ return undefined;
1114
+ }
1115
+ }
1064
1116
  /**
1065
1117
  * The substitution decision and its side effects.
1066
1118
  *
1067
1119
  * The fixed order is the plan's: existence of a plan and a receipt first, then
1068
- * `worthSubstituting`, then `budget.take()`. Nothing below spends budget on a
1069
- * decision that will not be dispatched.
1120
+ * `worthSubstituting`, then `budget.take()`. The step's admission filter
1121
+ * (row 7) runs inside `decide`, before the selector is priced and before the
1122
+ * budget is taken; when its evidence is unavailable the commit still happens
1123
+ * and a `substitute-skipped:no-toolset` line records that it did.
1124
+ * Nothing below spends budget on a decision that will not be dispatched.
1070
1125
  *
1071
1126
  * `ask-selector` is fulfilled here since Task 23c-2: the decision carries only
1072
1127
  * already-bound candidates, so the selector's choice is committed from
@@ -1123,6 +1178,12 @@ async function decideSubstitution(deps, ctx) {
1123
1178
  }));
1124
1179
  return;
1125
1180
  }
1181
+ // Row 7: this step's `ResolvedToolSet` is the host's admission set, so
1182
+ // `decide` drops a candidate whose tool it does not admit before the selector
1183
+ // or the budget is touched. Shadow mode is record-only and measures potential
1184
+ // across the whole whitelist, so it passes no admission filter.
1185
+ const admission = ctx.doc.shadow ? undefined : admissionViewOf(ctx.exec);
1186
+ const noToolset = !ctx.doc.shadow && admission === undefined;
1126
1187
  let decision;
1127
1188
  try {
1128
1189
  decision = decide({
@@ -1131,6 +1192,7 @@ async function decideSubstitution(deps, ctx) {
1131
1192
  receipts: ctx.state.receiptsFor(ctx.sessionId, ctx.turn),
1132
1193
  whitelist: SUBSTITUTION_WHITELIST,
1133
1194
  shadow: ctx.doc.shadow,
1195
+ ...(admission === undefined ? {} : { admitted: admission }),
1134
1196
  });
1135
1197
  }
1136
1198
  catch {
@@ -1286,6 +1348,15 @@ async function decideSubstitution(deps, ctx) {
1286
1348
  }));
1287
1349
  return;
1288
1350
  }
1351
+ // Row 7: the commit is real but the admission evidence was not available.
1352
+ // Recording it here (not at the missing-evidence point above) means the note
1353
+ // names the candidate that actually committed and only exists when one did.
1354
+ if (noToolset) {
1355
+ await appendReceipt(deps, ledgerEntry(ctx, 'skip', 'substitute-skipped:no-toolset', {
1356
+ stepId: 'root',
1357
+ candidateId,
1358
+ }));
1359
+ }
1289
1360
  markSubstituted(deps, ctx.sessionId, candidateId);
1290
1361
  // Anchors name the templates the executed call was bound from: the decision's
1291
1362
  // args are already expanded, so only the plan copy still carries the
@@ -1814,6 +1885,11 @@ async function appendDispatchRejected(deps, exec, entry, sessionId) {
1814
1885
  * then fails open.
1815
1886
  */
1816
1887
  async function inspectDispatch(deps, exec) {
1888
+ // Row 30: a PTC inner call carries `parent` and belongs to the enclosing
1889
+ // `run_code` step. Its host-assigned call id is not the root decision's, so
1890
+ // even a collision must not be read as our dispatch.
1891
+ if (exec.parent !== undefined)
1892
+ return { kind: 'next' };
1817
1893
  const sessionId = sessionIdOf(exec);
1818
1894
  if (sessionId === undefined)
1819
1895
  return { kind: 'next' };
@@ -1864,6 +1940,10 @@ async function inspectDispatch(deps, exec) {
1864
1940
  * not block every tool call in the process.
1865
1941
  */
1866
1942
  async function executeHook(deps, state, exec, next) {
1943
+ // Row 30: a PTC inner dispatch is the enclosing `run_code` step's business,
1944
+ // not this hook's; `next()` runs untouched so the inner tool still executes.
1945
+ if (exec?.parent !== undefined)
1946
+ return next();
1867
1947
  let outcome;
1868
1948
  try {
1869
1949
  outcome = await inspectDispatch(deps, exec);
@@ -1942,6 +2022,9 @@ export function registerHooks(ctx, deps) {
1942
2022
  // keeps the degradation warnings reachable without widening every caller's
1943
2023
  // deps literal. A deps object that already names one keeps it.
1944
2024
  deps.logger ??= ctx.logger;
2025
+ // Row 27: `llm/stream` records the synthesis through this seam, because the
2026
+ // mirror lives here and a denied dispatch never reaches `tools/execute`.
2027
+ deps.noteSynthesis ??= (sessionId, turn, candidateId, evidence) => noteAcceptedDispatch(deps, sessionId, turn, candidateId, evidence);
1945
2028
  registerProtocolSection(ctx, deps.scope);
1946
2029
  registerPostExecute(ctx, deps, state);
1947
2030
  registerLlmStream(ctx, deps);