dsh-jev-tools-continued 0.0.0-stage → 0.2.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 (122) hide show
  1. package/CHANGELOG.en.md +449 -0
  2. package/CHANGELOG.i18n.yaml +13 -0
  3. package/CHANGELOG.md +357 -0
  4. package/LICENSE +21 -0
  5. package/README.en.md +210 -0
  6. package/README.i18n.yaml +13 -0
  7. package/README.md +209 -2
  8. package/client/client.js +755 -0
  9. package/cordis.patch.yml +30 -0
  10. package/docs/banner.png +0 -0
  11. package/docs/dev-workflow.md +414 -0
  12. package/docs/s0-trigger-rate.md +168 -0
  13. package/icon.svg +16 -0
  14. package/lib/backends/jev.d.ts +69 -0
  15. package/lib/backends/jev.d.ts.map +1 -0
  16. package/lib/backends/jev.js +151 -0
  17. package/lib/backends/jev.js.map +1 -0
  18. package/lib/backends/types.d.ts +104 -0
  19. package/lib/backends/types.d.ts.map +1 -0
  20. package/lib/backends/types.js +12 -0
  21. package/lib/backends/types.js.map +1 -0
  22. package/lib/budget.d.ts +60 -0
  23. package/lib/budget.d.ts.map +1 -0
  24. package/lib/budget.js +70 -0
  25. package/lib/budget.js.map +1 -0
  26. package/lib/calibrate.d.ts +162 -0
  27. package/lib/calibrate.d.ts.map +1 -0
  28. package/lib/calibrate.js +269 -0
  29. package/lib/calibrate.js.map +1 -0
  30. package/lib/config.d.ts +261 -0
  31. package/lib/config.d.ts.map +1 -0
  32. package/lib/config.js +194 -0
  33. package/lib/config.js.map +1 -0
  34. package/lib/context-cache.d.ts +59 -0
  35. package/lib/context-cache.d.ts.map +1 -0
  36. package/lib/context-cache.js +116 -0
  37. package/lib/context-cache.js.map +1 -0
  38. package/lib/credentials.d.ts +32 -0
  39. package/lib/credentials.d.ts.map +1 -0
  40. package/lib/credentials.js +44 -0
  41. package/lib/credentials.js.map +1 -0
  42. package/lib/degrade.d.ts +36 -0
  43. package/lib/degrade.d.ts.map +1 -0
  44. package/lib/degrade.js +41 -0
  45. package/lib/degrade.js.map +1 -0
  46. package/lib/features/prune.d.ts +116 -0
  47. package/lib/features/prune.d.ts.map +1 -0
  48. package/lib/features/prune.js +574 -0
  49. package/lib/features/prune.js.map +1 -0
  50. package/lib/features/screen.d.ts +112 -0
  51. package/lib/features/screen.d.ts.map +1 -0
  52. package/lib/features/screen.js +130 -0
  53. package/lib/features/screen.js.map +1 -0
  54. package/lib/features/skill-suggest.d.ts +68 -0
  55. package/lib/features/skill-suggest.d.ts.map +1 -0
  56. package/lib/features/skill-suggest.js +283 -0
  57. package/lib/features/skill-suggest.js.map +1 -0
  58. package/lib/host.d.ts +280 -0
  59. package/lib/host.d.ts.map +1 -0
  60. package/lib/host.js +15 -0
  61. package/lib/host.js.map +1 -0
  62. package/lib/http.d.ts +71 -0
  63. package/lib/http.d.ts.map +1 -0
  64. package/lib/http.js +162 -0
  65. package/lib/http.js.map +1 -0
  66. package/lib/i18n.d.ts +372 -0
  67. package/lib/i18n.d.ts.map +1 -0
  68. package/lib/i18n.js +254 -0
  69. package/lib/i18n.js.map +1 -0
  70. package/lib/index.d.ts +44 -0
  71. package/lib/index.d.ts.map +1 -0
  72. package/lib/index.js +268 -0
  73. package/lib/index.js.map +1 -0
  74. package/lib/keys.d.ts +90 -0
  75. package/lib/keys.d.ts.map +1 -0
  76. package/lib/keys.js +131 -0
  77. package/lib/keys.js.map +1 -0
  78. package/lib/ledger-domain.d.ts +169 -0
  79. package/lib/ledger-domain.d.ts.map +1 -0
  80. package/lib/ledger-domain.js +338 -0
  81. package/lib/ledger-domain.js.map +1 -0
  82. package/lib/ledger.d.ts +243 -0
  83. package/lib/ledger.d.ts.map +1 -0
  84. package/lib/ledger.js +239 -0
  85. package/lib/ledger.js.map +1 -0
  86. package/lib/memo.d.ts +32 -0
  87. package/lib/memo.d.ts.map +1 -0
  88. package/lib/memo.js +62 -0
  89. package/lib/memo.js.map +1 -0
  90. package/lib/notify.d.ts +78 -0
  91. package/lib/notify.d.ts.map +1 -0
  92. package/lib/notify.js +122 -0
  93. package/lib/notify.js.map +1 -0
  94. package/lib/proxy.d.ts +40 -0
  95. package/lib/proxy.d.ts.map +1 -0
  96. package/lib/proxy.js +136 -0
  97. package/lib/proxy.js.map +1 -0
  98. package/lib/request.d.ts +99 -0
  99. package/lib/request.d.ts.map +1 -0
  100. package/lib/request.js +168 -0
  101. package/lib/request.js.map +1 -0
  102. package/lib/source.d.ts +46 -0
  103. package/lib/source.d.ts.map +1 -0
  104. package/lib/source.js +35 -0
  105. package/lib/source.js.map +1 -0
  106. package/lib/status.d.ts +42 -0
  107. package/lib/status.d.ts.map +1 -0
  108. package/lib/status.js +214 -0
  109. package/lib/status.js.map +1 -0
  110. package/lib/tokens.d.ts +26 -0
  111. package/lib/tokens.d.ts.map +1 -0
  112. package/lib/tokens.js +57 -0
  113. package/lib/tokens.js.map +1 -0
  114. package/lib/tools/jev-ask.d.ts +44 -0
  115. package/lib/tools/jev-ask.d.ts.map +1 -0
  116. package/lib/tools/jev-ask.js +208 -0
  117. package/lib/tools/jev-ask.js.map +1 -0
  118. package/lib/tools/jev-gate.d.ts +79 -0
  119. package/lib/tools/jev-gate.d.ts.map +1 -0
  120. package/lib/tools/jev-gate.js +412 -0
  121. package/lib/tools/jev-gate.js.map +1 -0
  122. package/package.json +169 -4
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Semantic pruning of oversized tool results, and injection screening for
3
+ * content about to enter the context.
4
+ *
5
+ * Two responsibilities share this listener because they share the same moment:
6
+ * a tool result that is about to be read by the model. Pruning decides how much
7
+ * of it to keep; screening asks whether it is addressing the agent. Keeping them
8
+ * here rather than in two listeners is what lets **one request answer both** —
9
+ * questions are judged in parallel and in isolation, so the second one is nearly
10
+ * free, and two listeners would each send the whole payload.
11
+ *
12
+ * Triggered from `tools/post-execute`, which is an awaited waterfall on every
13
+ * tool call — so what matters is not one call's latency but `trigger rate ×
14
+ * latency`. S0 measured that: uncapped, a single turn can present 27 oversized
15
+ * read-family results, about 8.1 s of added serial latency; capped at three it
16
+ * is 0.9 s. Every guard below exists to keep that number honest.
17
+ *
18
+ * Three properties are non-negotiable:
19
+ *
20
+ * - **Rank, never threshold.** The raw probabilities are known to be
21
+ * under-confident, which makes them a good ordering and a poor probability.
22
+ * Segments are therefore sorted and cut to a budget, not filtered at 0.5.
23
+ * - **Deterministic floors.** The head and tail are always kept, high-scoring
24
+ * segments are always kept, and the result never shrinks past a floor. A
25
+ * model that loses the beginning of a file cannot use the rest.
26
+ * - **Pure fail-open.** Anything unexpected returns the original payload.
27
+ * Pruning is an optimisation; it must never be the reason a task failed.
28
+ * Screening inherits this: it warns and never blocks.
29
+ *
30
+ * @module dsh-jev-tools/features/prune
31
+ */
32
+ import type { DegradeNotices } from '../notify.js';
33
+ import { type Lang } from '../i18n.js';
34
+ import type { DecisionBackend } from '../backends/types.js';
35
+ import type { JevSettings } from '../config.js';
36
+ import type { ContextCache } from '../context-cache.js';
37
+ import type { Budget } from '../budget.js';
38
+ import type { Memo } from '../memo.js';
39
+ import type { Ledger } from '../ledger.js';
40
+ import type { KeyPool } from '../keys.js';
41
+ import type { PostToolListener, ToolResultPrunerService } from '../host.js';
42
+ /** Dependencies the listener needs. */
43
+ export interface PruneDeps {
44
+ readonly settings: () => JevSettings;
45
+ /** The session's key, and the next one when it is spent. */
46
+ readonly keys: KeyPool;
47
+ /** Build a backend for one resolved key. */
48
+ readonly backendFor: (apiKey: string, model: string, agentId?: string) => DecisionBackend;
49
+ /** DSH's own deterministic pruner, for the baseline measurement. */
50
+ readonly pruner: () => ToolResultPrunerService | undefined;
51
+ readonly cache: ContextCache;
52
+ readonly budget: Budget;
53
+ readonly memo: Memo<readonly unknown[]>;
54
+ readonly ledger: Ledger;
55
+ /**
56
+ * Where a decline that a reader has to know about is reported.
57
+ *
58
+ * Fail-open means the two structural failures (`no-key`, `unauthorized`)
59
+ * leave no other trace, so this is what turns them from invisible into a
60
+ * single line in the session.
61
+ */
62
+ readonly notices: DegradeNotices;
63
+ readonly now: () => number;
64
+ readonly newMessageId: () => string;
65
+ }
66
+ /** One indivisible piece of the payload. */
67
+ interface Chunk {
68
+ readonly text: string;
69
+ readonly lines: number;
70
+ readonly tokens: number;
71
+ }
72
+ /**
73
+ * Split text into chunks that can each be judged on their own.
74
+ *
75
+ * Blank-line paragraphs are the natural unit; an oversized paragraph is split
76
+ * by lines so no single question dominates the request's token budget.
77
+ *
78
+ * @param text - the payload text.
79
+ * @returns the chunks, in original order.
80
+ */
81
+ export declare function chunkText(text: string): Chunk[];
82
+ /**
83
+ * Choose which chunks to keep.
84
+ *
85
+ * Ordering is by relevance, but the result is reassembled in the original
86
+ * order and the floors are applied before the budget so a large irrelevant
87
+ * opening can never crowd out a required one.
88
+ *
89
+ * @param chunks - the payload's chunks.
90
+ * @param relevance - one probability per chunk, same order.
91
+ * @param settings - the resolved prune settings.
92
+ * @returns the kept indices, ascending, plus the resulting token count.
93
+ */
94
+ export declare function selectChunks(chunks: readonly Chunk[], relevance: readonly number[], settings: JevSettings['prune']): {
95
+ keep: boolean[];
96
+ keptTokens: number;
97
+ };
98
+ /**
99
+ * Reassemble the payload, marking each place where chunks were dropped.
100
+ *
101
+ * @param chunks - the payload's chunks.
102
+ * @param keep - which chunks survived, same order.
103
+ * @param content - the original content, kept for future block-level use.
104
+ * @param lang - the language for the omission marker.
105
+ * @returns the reassembled text.
106
+ */
107
+ export declare function reassemble(chunks: readonly Chunk[], keep: readonly boolean[], content: readonly unknown[], lang: Lang): string;
108
+ /**
109
+ * Create the `tools/post-execute` listener.
110
+ *
111
+ * @param deps - the capability's dependencies.
112
+ * @returns the listener.
113
+ */
114
+ export declare function createPruneListener(deps: PruneDeps): PostToolListener;
115
+ export {};
116
+ //# sourceMappingURL=prune.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../src/features/prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAiB,KAAK,IAAI,EAAE,MAAM,YAAY,CAAA;AAIrD,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,sBAAsB,CAAA;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAsC,MAAM,cAAc,CAAA;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EACQ,gBAAgB,EAA2B,uBAAuB,EACrF,MAAM,YAAY,CAAA;AAsBnB,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,WAAW,CAAA;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,eAAe,CAAA;IACzF,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,uBAAuB,GAAG,SAAS,CAAA;IAC1D,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,CAAA;CACpC;AAED,4CAA4C;AAC5C,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAE,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,CA6BhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAC7B;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAgDzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,IAAI,EAAE,IAAI,GACT,MAAM,CAkBR;AAiED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAE,IAAI,EAAE,SAAS,GAAG,gBAAgB,CAsVtE"}