@dsh-cc/tool-search 0.9.4 → 0.9.5-rc.1
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.i18n.yaml +2 -2
- package/README.md +42 -1
- package/README.zh.md +42 -1
- package/lib/discovery-cache.d.ts +208 -0
- package/lib/discovery-cache.d.ts.map +1 -0
- package/lib/discovery-cache.js +296 -0
- package/lib/discovery-cache.js.map +1 -0
- package/lib/discovery-contract.d.ts +144 -0
- package/lib/discovery-contract.d.ts.map +1 -0
- package/lib/discovery-contract.js +144 -0
- package/lib/discovery-contract.js.map +1 -0
- package/lib/discovery-runtime.d.ts +137 -0
- package/lib/discovery-runtime.d.ts.map +1 -0
- package/lib/discovery-runtime.js +343 -0
- package/lib/discovery-runtime.js.map +1 -0
- package/lib/discovery-settings.d.ts +134 -0
- package/lib/discovery-settings.d.ts.map +1 -0
- package/lib/discovery-settings.js +269 -0
- package/lib/discovery-settings.js.map +1 -0
- package/lib/discovery.d.ts +267 -0
- package/lib/discovery.d.ts.map +1 -0
- package/lib/discovery.js +278 -0
- package/lib/discovery.js.map +1 -0
- package/lib/index.d.ts +15 -0
- package/lib/index.d.ts.map +1 -1
- package/lib/index.js +84 -88
- package/lib/index.js.map +1 -1
- package/lib/search-message.d.ts +32 -0
- package/lib/search-message.d.ts.map +1 -0
- package/lib/search-message.js +50 -0
- package/lib/search-message.js.map +1 -0
- package/lib/search-scoring.d.ts +31 -0
- package/lib/search-scoring.d.ts.map +1 -0
- package/lib/search-scoring.js +53 -0
- package/lib/search-scoring.js.map +1 -0
- package/package.json +12 -4
package/README.i18n.yaml
CHANGED
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
|
3
3
|
# after editing either side, bring the other along and re-record with:
|
|
4
4
|
# pnpm check:readme --write
|
|
5
|
-
README.md:
|
|
6
|
-
README.zh.md:
|
|
5
|
+
README.md: e9510188e4015910f426146cf65bffea6e923f30
|
|
6
|
+
README.zh.md: 4d0082c6d3668e1c8cfa1b31fb7191987bc038d4
|
package/README.md
CHANGED
|
@@ -33,6 +33,47 @@ The design rides the repo's effect conventions:
|
|
|
33
33
|
- **Deferred names never leak into the prompt.** Only activated (`alwaysLoad` or loaded) tools enter the schema; reserved-but-unloaded names are known for restriction/`toolOrder` purposes but never model-visible.
|
|
34
34
|
- **ToolSearch itself is lazy, with hysteresis.** While the searchable pool is empty, only the `ToolSearch` *name* is reserved (restrictable, not visible); the first non-`alwaysLoad` deferred registration brings the tool into the model-visible set, and it then stays registered for the rest of the session even if the pool empties again — a mid-session removal would shift the assembled tool order and break the cached prefix. An empty pool also makes the tool's "tools are hidden, search to load them" description actively misleading, which is why it is withheld.
|
|
35
35
|
|
|
36
|
+
## Semantic tool discovery (S1-05)
|
|
37
|
+
|
|
38
|
+
Lexical ranking cannot see a query that shares no literal token with a tool's metadata — a Chinese question against English metadata, or a paraphrase of the same request. The optional discovery layer puts an independent relevance judgment in front of the existing activation path: every admitted deferred candidate is scored against the query through the System One decision runtime (the optional `ctx.systemoneDecisions` service that the `decision-usage` plugin provides), and only candidates whose judged relevance **and** direct fit both clear their thresholds become activations. Tool names, schemas, and return messages still come from deterministic code; the model answers only "is this candidate relevant", with one question pair per candidate, so one candidate's metadata cannot contaminate another's judgment.
|
|
39
|
+
|
|
40
|
+
The layer is **off by default** and never rewrites the lexical path on its own:
|
|
41
|
+
|
|
42
|
+
| `mode` | Behavior |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `off` | Default. Zero runner calls; `search()` and `execute` behave exactly as before, including result ordering and the default five items. |
|
|
45
|
+
| `shadow` | Runs the judgment and records the suggested difference; the original lexical hits still execute. |
|
|
46
|
+
| `active` | Activates the judged names in deterministic order (relevance, direct fit, lexical score, name ascending), capped at `min(max_results, max-activations)`. |
|
|
47
|
+
|
|
48
|
+
Settings live in the `cc-tool-discovery` namespace; raw keys are kebab-case:
|
|
49
|
+
|
|
50
|
+
| Key | Type, range | Default |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `mode` | `off \| shadow \| active` | `off` |
|
|
53
|
+
| `timeout-ms` | integer, 100–5000; time ceiling for the whole discovery transaction | `1200` |
|
|
54
|
+
| `max-input-tokens` | integer, 512–16384; per runner request, including questions and headroom | `4096` |
|
|
55
|
+
| `max-candidates` | integer, 1–128; cap on the complete eligible pool | `64` |
|
|
56
|
+
| `batch-size` | integer, 1–16 | `8` |
|
|
57
|
+
| `max-query-chars` | integer, 64–8192 | `2048` |
|
|
58
|
+
| `max-metadata-chars` | integer, 128–8192; combined cap per description and search hint | `2048` |
|
|
59
|
+
| `min-relevance-index` | finite number, 0–4; experimental threshold | `3` |
|
|
60
|
+
| `min-direct-fit` | number, 0–1; experimental threshold | `0.75` |
|
|
61
|
+
| `max-activations` | integer, 1–20 | `3` |
|
|
62
|
+
| `cache-entries` | integer, 0–1024; zero disables the cache | `128` |
|
|
63
|
+
| `cache-ttl-ms` | integer, 0–300000 | `60000` |
|
|
64
|
+
|
|
65
|
+
These thresholds are first-round evaluation parameters, not measured quality guarantees. Any invalid value disables the judgment entirely: the runner is not called, the lexical path runs, and the failure is reported once through `ctx.logger.warn`. The same whole-path fallback applies when the route, the service, or a complete answer is missing, and when a hard bound is exceeded — an oversized query or metadata field, a pool over `max-candidates`, a batch that cannot be split into whole groups that fit the request window, a timeout, caller cancellation, or a catalog/permission change before activation. A partial judgment is never blended with lexical hits, and a valid judgment that finds nothing relevant activates nothing (it is not backfilled from lexical hits). Admission is checked on both ends: a candidate the scope denies never enters the pool, and `activate()` re-checks the permission gate before loading, so a recommendation can never widen a scope.
|
|
66
|
+
|
|
67
|
+
The offline evaluator replays the pure policy layer against a redacted fixture — the human target set plus a lexical control, split into Chinese, synonym, no-relevant-tool, and restricted-tool subsets — with no network access:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
node packages/core/tool-search/scripts/eval-discovery.mjs \
|
|
71
|
+
--corpus packages/core/tool-search/tests/fixtures/discovery-corpus.json --mode replay
|
|
72
|
+
node packages/core/tool-search/scripts/eval-discovery.mjs --mode selfcheck
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`--mode replay` prints Recall@3 per subset beside the lexical control, plus activation precision, admission leaks, and a reproducibility check, and emits only aggregate numbers and case ids — never query text. `--mode selfcheck` validates the corpus schema alone.
|
|
76
|
+
|
|
36
77
|
## Model Experience
|
|
37
78
|
|
|
38
79
|
Turn one, the model sees only `ToolSearch` plus whatever is already loaded (including `alwaysLoad` tools) — or, in a session with no deferred tools at all, no `ToolSearch` either. It searches for a capability by keywords, and the result names the now-available tools. On the next turn those tools are first-class: declare them, call them. Already-loaded tools drop out of the deferred set, so a second search for them is correctly empty.
|
|
@@ -41,5 +82,5 @@ An empty search result always says *why*, so the model never mistakes "nothing d
|
|
|
41
82
|
|
|
42
83
|
## Known Limitations and Deferred Work
|
|
43
84
|
|
|
44
|
-
- **Matching is lexical
|
|
85
|
+
- **Matching is lexical unless discovery is enabled.** Ranking uses weighted substring/token scoring; there is no embedding/vector search. The optional S1-05 layer adds a model relevance judgment for synonyms and Chinese queries, but it is off by default and falls back to the lexical path on any failure.
|
|
45
86
|
- **Global activation.** Loading happens on the host plane (global registration); a per-agent scope sees a loaded tool only if its restriction admits it. There is no per-conversation discovery history — loading is an in-memory effect, so a re-registered composition starts from the deferred pool again.
|
package/README.zh.md
CHANGED
|
@@ -32,6 +32,47 @@ ctx.toolSearch.registerDeferred({
|
|
|
32
32
|
- **延迟名字永不泄漏进提示词。** 只有已激活(`alwaysLoad` 或已加载)的工具才进 schema;被预留而未加载的名字仅用于限制/`toolOrder` 判定,不对外可见。
|
|
33
33
|
- **ToolSearch 自身懒注册、带迟滞。** 可搜索池为空时只预留 `ToolSearch` 这个名字(可限制、不可见);首个非 `alwaysLoad` 的延迟注册才把它带进模型可见集,此后即使池再次清空也保持注册——会话中途注销会移动组装后的工具顺序、击穿缓存前缀。空池时该工具"工具被隐藏、搜索后加载"的描述会主动误导模型,这正是它在空池时不展示的原因。
|
|
34
34
|
|
|
35
|
+
## 语义工具发现(S1-05)
|
|
36
|
+
|
|
37
|
+
词法排序看不见与工具元数据不共享任何字面词元的查询——中文问题对上英文元数据,或同一个请求换一种说法。可选的发现层在既有激活路径前加一次独立的相关性判断:每个已准入的延迟候选都通过 System One 决策运行时针对查询打分(该运行时即 `decision-usage` 插件提供的可选 `ctx.systemoneDecisions` 服务),只有相关性判断**与**直接匹配度都越过阈值的候选才会成为激活项。工具名、schema 与返回消息仍由确定性代码产生;模型只回答"这个候选是否相关",每个候选一对问题,因此一个候选的元数据不会污染另一个的判断。
|
|
38
|
+
|
|
39
|
+
该层**默认关闭**,且绝不会自行改写词法路径:
|
|
40
|
+
|
|
41
|
+
| `mode` | 行为 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `off` | 默认。零次 runner 调用;`search()` 与 `execute` 与之前完全一致,包括结果顺序与默认五条。 |
|
|
44
|
+
| `shadow` | 执行判断并记录建议差异;仍然执行原来的词法命中。 |
|
|
45
|
+
| `active` | 按确定性顺序(相关性、直接匹配度、词法分数、名字升序)激活判断出的名字,上限为 `min(max_results, max-activations)`。 |
|
|
46
|
+
|
|
47
|
+
设置位于 `cc-tool-discovery` 命名空间;原始键为 kebab-case:
|
|
48
|
+
|
|
49
|
+
| 键 | 类型与范围 | 默认值 |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| `mode` | `off \| shadow \| active` | `off` |
|
|
52
|
+
| `timeout-ms` | 整数,100–5000;整次发现事务的时间上限 | `1200` |
|
|
53
|
+
| `max-input-tokens` | 整数,512–16384;单次 runner 请求,含问题与余量 | `4096` |
|
|
54
|
+
| `max-candidates` | 整数,1–128;完整候选池上限 | `64` |
|
|
55
|
+
| `batch-size` | 整数,1–16 | `8` |
|
|
56
|
+
| `max-query-chars` | 整数,64–8192 | `2048` |
|
|
57
|
+
| `max-metadata-chars` | 整数,128–8192;描述与搜索提示各自的合并上限 | `2048` |
|
|
58
|
+
| `min-relevance-index` | 有限数,0–4;实验性阈值 | `3` |
|
|
59
|
+
| `min-direct-fit` | 数,0–1;实验性阈值 | `0.75` |
|
|
60
|
+
| `max-activations` | 整数,1–20 | `3` |
|
|
61
|
+
| `cache-entries` | 整数,0–1024;为零则关闭缓存 | `128` |
|
|
62
|
+
| `cache-ttl-ms` | 整数,0–300000 | `60000` |
|
|
63
|
+
|
|
64
|
+
这些阈值是第一轮评估参数,而非已测的质量保证。任何一个值非法都会彻底关闭判断:不调用 runner,运行词法路径,并通过 `ctx.logger.warn` 只报告一次。同样的整路回退也适用于路由、服务或完整答案缺失,以及越过任何硬性边界的情况——查询或元数据字段过长、候选池超过 `max-candidates`、批次无法拆成装得进请求窗口的整组、超时、调用方取消,或激活前目录/权限发生变化。部分判断绝不与词法命中混合;判断有效但没有找到相关工具时不激活任何东西(不会用词法命中回填)。准入在两端都检查:作用域拒绝的候选根本不进池,`activate()` 在加载前再查一次权限闸,因此推荐绝不会扩大作用域。
|
|
65
|
+
|
|
66
|
+
离线评估器针对一份脱敏 fixture 回放纯策略层——人工目标集加上词法对照,分为中文、同义词、无相关工具、受限工具四个子集——全程不访问网络:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
node packages/core/tool-search/scripts/eval-discovery.mjs \
|
|
70
|
+
--corpus packages/core/tool-search/tests/fixtures/discovery-corpus.json --mode replay
|
|
71
|
+
node packages/core/tool-search/scripts/eval-discovery.mjs --mode selfcheck
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`--mode replay` 按子集打印 Recall@3 并与词法对照并列,同时给出激活精确率、准入泄漏与可复现性检查,只输出聚合数字与用例 id——绝不输出查询文本。`--mode selfcheck` 只校验语料 schema。
|
|
75
|
+
|
|
35
76
|
## 模型体验
|
|
36
77
|
|
|
37
78
|
第一轮,模型只看到 `ToolSearch` 加已加载的(包括 `alwaysLoad` 的)工具——而在完全没有延迟工具的会话里,连 `ToolSearch` 也不出现。它按关键字搜索某个能力,结果里点名现在可用哪些工具。下一轮这些工具就成头等公民:声明它们,调用它们。已加载的工具会退出延迟集合,因此再次搜索它们会正确地得到空结果。
|
|
@@ -40,5 +81,5 @@ ctx.toolSearch.registerDeferred({
|
|
|
40
81
|
|
|
41
82
|
## 已知限制与暂缓事项
|
|
42
83
|
|
|
43
|
-
-
|
|
84
|
+
- **匹配是词法的,除非启用了发现层。** 排序用加权的子串/词元打分;没有嵌入/向量检索。可选的 S1-05 层为同义词与中文查询补上一次模型相关性判断,但它默认关闭,且任何失败都会回退到词法路径。
|
|
44
85
|
- **全局激活。** 加载发生在宿主平面(全局注册);某个 per-agent 作用域只有在它的限制放行时才能看到已加载的工具。没有按会话的记忆历史——加载是内存里的 effect,因此重新组装后又会从延迟池重新开始。
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The in-process judgment cache of S1-05 tool discovery: a bounded LRU with
|
|
3
|
+
* lazy TTL expiry, plus same-key request coalescing with independent caller
|
|
4
|
+
* cancellation.
|
|
5
|
+
*
|
|
6
|
+
* Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
|
|
7
|
+
* § "Lifecycle, cache, and failure handling" and § "Settings". The protocol
|
|
8
|
+
* this file implements is the one shared with S1-06/S1-11/S1-12 and verified in
|
|
9
|
+
* `specs/tla/decision-gate-coalescing`:
|
|
10
|
+
*
|
|
11
|
+
* - **cache-then-coalesce**: a completed judgment is stored BEFORE waiters are
|
|
12
|
+
* woken, and an in-flight run is joined rather than duplicated;
|
|
13
|
+
* - **only complete answers are cached**: a rejected run (timeout, transport
|
|
14
|
+
* error, missing route, partial batch) and an abandoned run (every waiter
|
|
15
|
+
* left) store nothing;
|
|
16
|
+
* - **per-caller independent cancellation**: each waiter's own `AbortSignal`
|
|
17
|
+
* ends only that waiter's wait — nothing is published on its behalf — while
|
|
18
|
+
* the shared request keeps running for the others;
|
|
19
|
+
* - **last waiter aborts the request**: the underlying factory's signal fires
|
|
20
|
+
* only when the refcount drops to zero;
|
|
21
|
+
* - **post-await revalidation** stays with the caller (design step 9): this
|
|
22
|
+
* layer only guarantees that a run whose catalog/admission/identity/threshold
|
|
23
|
+
* inputs changed is a DIFFERENT key, so a stale judgment is never reused.
|
|
24
|
+
*
|
|
25
|
+
* The model's invariants map onto this file as `AbortOnlyWhenAllCancelled` and
|
|
26
|
+
* `SettledHoldsSlot` (the refcounted {@link Flight}), `CacheCompleteOnly` (a
|
|
27
|
+
* failed or abandoned run stores nothing), and `NoConsumeAfterCancel` (a
|
|
28
|
+
* cancelled waiter resolves `cancelled` and publishes nothing).
|
|
29
|
+
*
|
|
30
|
+
* There is no persistence, no background sweep, and no timer: an expired entry
|
|
31
|
+
* is discovered at read time and treated as absent.
|
|
32
|
+
*
|
|
33
|
+
* @module @dsh-cc/tool-search/discovery-cache
|
|
34
|
+
*/
|
|
35
|
+
import type { DiscoveryRouteIdentity } from './discovery.ts';
|
|
36
|
+
/**
|
|
37
|
+
* Key-format version. Bumping it retires every previously stored entry without
|
|
38
|
+
* having to reason about collisions with an older field order.
|
|
39
|
+
*/
|
|
40
|
+
export declare const DISCOVERY_CACHE_KEY_VERSION = "tool-discovery-key-v1";
|
|
41
|
+
/**
|
|
42
|
+
* The keyless route identity returned by `identifyRoute` (design
|
|
43
|
+
* § "File responsibilities": the consumer re-reads it after every await and
|
|
44
|
+
* compares all seven fields). One canonical declaration lives in the policy
|
|
45
|
+
* layer; it is re-exported here so cache-key consumers need a single import.
|
|
46
|
+
*/
|
|
47
|
+
export type { DiscoveryRouteIdentity };
|
|
48
|
+
/**
|
|
49
|
+
* Every settings threshold that shapes a judgment, camelCase (design §
|
|
50
|
+
* "Settings"). These are part of the cache key because changing one changes
|
|
51
|
+
* which candidates fit the window and which answers survive the thresholds.
|
|
52
|
+
* The two CACHE knobs (`cacheEntries`, `cacheTtlMs`) are deliberately NOT here:
|
|
53
|
+
* they govern reuse, not what a judgment means.
|
|
54
|
+
*/
|
|
55
|
+
export interface DiscoveryThresholds {
|
|
56
|
+
/** Time ceiling for the whole discovery transaction. */
|
|
57
|
+
readonly timeoutMs: number;
|
|
58
|
+
/** Per runner request, including questions and headroom. */
|
|
59
|
+
readonly maxInputTokens: number;
|
|
60
|
+
/** Cap on the complete eligible pool. */
|
|
61
|
+
readonly maxCandidates: number;
|
|
62
|
+
/** Candidates per runner request before window splitting. */
|
|
63
|
+
readonly batchSize: number;
|
|
64
|
+
/** Longest query, in characters, that may be judged. */
|
|
65
|
+
readonly maxQueryChars: number;
|
|
66
|
+
/** Combined per-field cap on the metadata sent for a candidate. */
|
|
67
|
+
readonly maxMetadataChars: number;
|
|
68
|
+
/** Experimental relevance threshold. */
|
|
69
|
+
readonly minRelevanceIndex: number;
|
|
70
|
+
/** Experimental direct-fit threshold. */
|
|
71
|
+
readonly minDirectFit: number;
|
|
72
|
+
/** Upper bound on activated names. */
|
|
73
|
+
readonly maxActivations: number;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Everything the design's § "Lifecycle, cache, and failure handling" requires
|
|
77
|
+
* in the key, in one value. The host resolves `project`/`session`/`agent`, and
|
|
78
|
+
* `originSeq` is the persisted session watermark (`Number(agent.session.seq)`)
|
|
79
|
+
* — never `events.length` (design § "Inputs, questions, and output").
|
|
80
|
+
*/
|
|
81
|
+
export interface DiscoveryCacheKeyParts {
|
|
82
|
+
/** Project key resolved by the host. */
|
|
83
|
+
readonly project: string;
|
|
84
|
+
/** Session id. */
|
|
85
|
+
readonly session: string;
|
|
86
|
+
/** Agent id within the session. */
|
|
87
|
+
readonly agent: string;
|
|
88
|
+
/** Persisted sequence watermark at entry. */
|
|
89
|
+
readonly originSeq: number;
|
|
90
|
+
/** The raw query; trimmed by {@link buildDiscoveryCacheKey}. */
|
|
91
|
+
readonly query: string;
|
|
92
|
+
/** Hash of the full visible catalog. */
|
|
93
|
+
readonly catalogHash: string;
|
|
94
|
+
/** Hash of the scope's admission (permission) set. */
|
|
95
|
+
readonly admissionHash: string;
|
|
96
|
+
/** The full route identity and revision. */
|
|
97
|
+
readonly route: DiscoveryRouteIdentity;
|
|
98
|
+
/** Question-set version (`tool-discovery-v1`). */
|
|
99
|
+
readonly questionVersion: string;
|
|
100
|
+
/** Policy version (`tool-discovery-policy-v1`). */
|
|
101
|
+
readonly policyVersion: string;
|
|
102
|
+
/** Every threshold that shapes the judgment. */
|
|
103
|
+
readonly thresholds: DiscoveryThresholds;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Build the cache key for one discovery transaction.
|
|
107
|
+
*
|
|
108
|
+
* The fields are serialized in a fixed order as a JSON array, so a value can
|
|
109
|
+
* never bleed into the next slot (a length-prefixed/escaped join would have to
|
|
110
|
+
* re-derive that invariant). The query is trimmed first: `" x "` and `"x"`
|
|
111
|
+
* describe the same judgment and must share a key.
|
|
112
|
+
* @param parts - the transaction identity.
|
|
113
|
+
* @returns an opaque, deterministic key string.
|
|
114
|
+
*/
|
|
115
|
+
export declare function buildDiscoveryCacheKey(parts: DiscoveryCacheKeyParts): string;
|
|
116
|
+
/**
|
|
117
|
+
* How one caller's wait ended: a complete judgment, or that caller's own
|
|
118
|
+
* cancellation. A cancelled caller must activate nothing (design §
|
|
119
|
+
* "Lifecycle, cache, and failure handling": cancellation is never backfilled
|
|
120
|
+
* with lexical activation), so the two outcomes are distinguished here instead
|
|
121
|
+
* of relying on a rejected promise.
|
|
122
|
+
*/
|
|
123
|
+
export type DiscoveryRunOutcome<T> = {
|
|
124
|
+
readonly status: 'ok';
|
|
125
|
+
readonly value: T;
|
|
126
|
+
} | {
|
|
127
|
+
readonly status: 'cancelled';
|
|
128
|
+
};
|
|
129
|
+
/** Cache construction options. */
|
|
130
|
+
export interface DiscoveryCacheOptions<T> {
|
|
131
|
+
/** Maximum stored entries; `0` disables storage entirely (settings `cache-entries`). */
|
|
132
|
+
readonly maxEntries: number;
|
|
133
|
+
/** Entry lifetime in milliseconds; `<= 0` means no entry is ever reusable (settings `cache-ttl-ms`). */
|
|
134
|
+
readonly ttlMs: number;
|
|
135
|
+
/**
|
|
136
|
+
* Whether a completed judgment may be stored. Defaults to "only a fully
|
|
137
|
+
* validated `selected` judgment": the design forbids caching timeouts,
|
|
138
|
+
* cancellation, missing routes, partial batches and lexical fallbacks.
|
|
139
|
+
*/
|
|
140
|
+
readonly cacheable?: (value: T) => boolean;
|
|
141
|
+
/** Clock, injectable for tests; defaults to `Date.now`. */
|
|
142
|
+
readonly now?: () => number;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* In-process LRU cache with TTL and refcounted same-key coalescing.
|
|
146
|
+
*
|
|
147
|
+
* One instance per plugin fiber (design § "Lifecycle, cache, and failure
|
|
148
|
+
* handling": plugin unload aborts its requests and clears the cache — call
|
|
149
|
+
* {@link DiscoveryCache.clear} from the unload path). Storage is a `Map`, whose
|
|
150
|
+
* iteration order is the LRU order: a read re-inserts the entry at the MRU end,
|
|
151
|
+
* a write beyond `maxEntries` evicts from the front.
|
|
152
|
+
*/
|
|
153
|
+
export declare class DiscoveryCache<T> {
|
|
154
|
+
private readonly entries;
|
|
155
|
+
private readonly flights;
|
|
156
|
+
private readonly maxEntries;
|
|
157
|
+
private readonly ttlMs;
|
|
158
|
+
private readonly cacheable;
|
|
159
|
+
private readonly now;
|
|
160
|
+
constructor(options: DiscoveryCacheOptions<T>);
|
|
161
|
+
/** Stored entries currently held (expired ones are dropped as they are read). */
|
|
162
|
+
get size(): number;
|
|
163
|
+
/** Keys with an in-flight shared run. */
|
|
164
|
+
get pending(): number;
|
|
165
|
+
/**
|
|
166
|
+
* Resolve one discovery transaction, reusing a cached judgment or joining the
|
|
167
|
+
* in-flight run for the same key.
|
|
168
|
+
*
|
|
169
|
+
* - a warm entry is returned without invoking `factory`;
|
|
170
|
+
* - concurrent callers with the same key share ONE `factory` invocation;
|
|
171
|
+
* - `signal` cancels only THIS caller's wait (resolving `cancelled`, so the
|
|
172
|
+
* caller activates nothing); the shared request is aborted only when the
|
|
173
|
+
* last waiter's signal aborts;
|
|
174
|
+
* - a factory rejection (timeout, transport error, partial batch) is
|
|
175
|
+
* propagated to every remaining waiter and caches nothing.
|
|
176
|
+
* @param key - the key from {@link buildDiscoveryCacheKey}.
|
|
177
|
+
* @param factory - performs the judgment; receives the shared abort signal.
|
|
178
|
+
* @param signal - the calling transaction's own cancellation signal.
|
|
179
|
+
* @returns the judgment, or `cancelled` when this caller left.
|
|
180
|
+
*/
|
|
181
|
+
run(key: string, factory: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<DiscoveryRunOutcome<T>>;
|
|
182
|
+
/**
|
|
183
|
+
* Drop every stored entry and abort every in-flight run, resolving its
|
|
184
|
+
* waiters as cancelled. This is the plugin-unload / rollback hook (design
|
|
185
|
+
* § "Lifecycle, cache, and failure handling" and § "Release gates and
|
|
186
|
+
* rollback").
|
|
187
|
+
*/
|
|
188
|
+
clear(): void;
|
|
189
|
+
/** A warm, unexpired entry, promoted to the MRU end. */
|
|
190
|
+
private read;
|
|
191
|
+
/** Store one completed judgment, evicting the least recently used entry. */
|
|
192
|
+
private store;
|
|
193
|
+
/** The flight for a key, starting one when this caller is the first. */
|
|
194
|
+
private flightOf;
|
|
195
|
+
/** Invoke the factory once and settle the flight when it finishes. */
|
|
196
|
+
private start;
|
|
197
|
+
/** Store (when allowed), then wake every remaining waiter with the value. */
|
|
198
|
+
private complete;
|
|
199
|
+
/** Propagate a failed run to every remaining waiter; nothing is cached. */
|
|
200
|
+
private fail;
|
|
201
|
+
/** Forget the flight for a key, leaving a newer one in place if it replaced this. */
|
|
202
|
+
private detach;
|
|
203
|
+
/** Remove one waiter, aborting the shared request when it was the last. */
|
|
204
|
+
private leave;
|
|
205
|
+
/** Register one caller as a waiter of a flight. */
|
|
206
|
+
private awaitFlight;
|
|
207
|
+
}
|
|
208
|
+
//# sourceMappingURL=discovery-cache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery-cache.d.ts","sourceRoot":"","sources":["../src/discovery-cache.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The in-process judgment cache of S1-05 tool discovery: a bounded LRU with
|
|
3
|
+
* lazy TTL expiry, plus same-key request coalescing with independent caller
|
|
4
|
+
* cancellation.
|
|
5
|
+
*
|
|
6
|
+
* Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
|
|
7
|
+
* § "Lifecycle, cache, and failure handling" and § "Settings". The protocol
|
|
8
|
+
* this file implements is the one shared with S1-06/S1-11/S1-12 and verified in
|
|
9
|
+
* `specs/tla/decision-gate-coalescing`:
|
|
10
|
+
*
|
|
11
|
+
* - **cache-then-coalesce**: a completed judgment is stored BEFORE waiters are
|
|
12
|
+
* woken, and an in-flight run is joined rather than duplicated;
|
|
13
|
+
* - **only complete answers are cached**: a rejected run (timeout, transport
|
|
14
|
+
* error, missing route, partial batch) and an abandoned run (every waiter
|
|
15
|
+
* left) store nothing;
|
|
16
|
+
* - **per-caller independent cancellation**: each waiter's own `AbortSignal`
|
|
17
|
+
* ends only that waiter's wait — nothing is published on its behalf — while
|
|
18
|
+
* the shared request keeps running for the others;
|
|
19
|
+
* - **last waiter aborts the request**: the underlying factory's signal fires
|
|
20
|
+
* only when the refcount drops to zero;
|
|
21
|
+
* - **post-await revalidation** stays with the caller (design step 9): this
|
|
22
|
+
* layer only guarantees that a run whose catalog/admission/identity/threshold
|
|
23
|
+
* inputs changed is a DIFFERENT key, so a stale judgment is never reused.
|
|
24
|
+
*
|
|
25
|
+
* The model's invariants map onto this file as `AbortOnlyWhenAllCancelled` and
|
|
26
|
+
* `SettledHoldsSlot` (the refcounted {@link Flight}), `CacheCompleteOnly` (a
|
|
27
|
+
* failed or abandoned run stores nothing), and `NoConsumeAfterCancel` (a
|
|
28
|
+
* cancelled waiter resolves `cancelled` and publishes nothing).
|
|
29
|
+
*
|
|
30
|
+
* There is no persistence, no background sweep, and no timer: an expired entry
|
|
31
|
+
* is discovered at read time and treated as absent.
|
|
32
|
+
*
|
|
33
|
+
* @module @dsh-cc/tool-search/discovery-cache
|
|
34
|
+
*/
|
|
35
|
+
/**
|
|
36
|
+
* Key-format version. Bumping it retires every previously stored entry without
|
|
37
|
+
* having to reason about collisions with an older field order.
|
|
38
|
+
*/
|
|
39
|
+
export const DISCOVERY_CACHE_KEY_VERSION = 'tool-discovery-key-v1';
|
|
40
|
+
/**
|
|
41
|
+
* Build the cache key for one discovery transaction.
|
|
42
|
+
*
|
|
43
|
+
* The fields are serialized in a fixed order as a JSON array, so a value can
|
|
44
|
+
* never bleed into the next slot (a length-prefixed/escaped join would have to
|
|
45
|
+
* re-derive that invariant). The query is trimmed first: `" x "` and `"x"`
|
|
46
|
+
* describe the same judgment and must share a key.
|
|
47
|
+
* @param parts - the transaction identity.
|
|
48
|
+
* @returns an opaque, deterministic key string.
|
|
49
|
+
*/
|
|
50
|
+
export function buildDiscoveryCacheKey(parts) {
|
|
51
|
+
const { route, thresholds } = parts;
|
|
52
|
+
return JSON.stringify([
|
|
53
|
+
DISCOVERY_CACHE_KEY_VERSION,
|
|
54
|
+
parts.project,
|
|
55
|
+
parts.session,
|
|
56
|
+
parts.agent,
|
|
57
|
+
parts.originSeq,
|
|
58
|
+
parts.query.trim(),
|
|
59
|
+
parts.catalogHash,
|
|
60
|
+
parts.admissionHash,
|
|
61
|
+
route.provider,
|
|
62
|
+
route.model,
|
|
63
|
+
route.revision,
|
|
64
|
+
route.perRequestTokens,
|
|
65
|
+
route.perQuestionTokens,
|
|
66
|
+
route.maxQuestions,
|
|
67
|
+
route.maxOutputTokens,
|
|
68
|
+
parts.questionVersion,
|
|
69
|
+
parts.policyVersion,
|
|
70
|
+
thresholds.timeoutMs,
|
|
71
|
+
thresholds.maxInputTokens,
|
|
72
|
+
thresholds.maxCandidates,
|
|
73
|
+
thresholds.batchSize,
|
|
74
|
+
thresholds.maxQueryChars,
|
|
75
|
+
thresholds.maxMetadataChars,
|
|
76
|
+
thresholds.minRelevanceIndex,
|
|
77
|
+
thresholds.minDirectFit,
|
|
78
|
+
thresholds.maxActivations,
|
|
79
|
+
]);
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Default cacheability: a discriminated judgment is stored only when it is a
|
|
83
|
+
* validated `selected` answer (design § "Lifecycle, cache, and failure
|
|
84
|
+
* handling"). A non-discriminated value has no verdict to second-guess and is
|
|
85
|
+
* stored. Note this is a shape test, not the validation itself: the judgment
|
|
86
|
+
* layer must mint `kind: 'selected'` only after full validation.
|
|
87
|
+
*/
|
|
88
|
+
function defaultCacheable(value) {
|
|
89
|
+
if (value === null || typeof value !== 'object' || !('kind' in value))
|
|
90
|
+
return true;
|
|
91
|
+
return value.kind === 'selected';
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* In-process LRU cache with TTL and refcounted same-key coalescing.
|
|
95
|
+
*
|
|
96
|
+
* One instance per plugin fiber (design § "Lifecycle, cache, and failure
|
|
97
|
+
* handling": plugin unload aborts its requests and clears the cache — call
|
|
98
|
+
* {@link DiscoveryCache.clear} from the unload path). Storage is a `Map`, whose
|
|
99
|
+
* iteration order is the LRU order: a read re-inserts the entry at the MRU end,
|
|
100
|
+
* a write beyond `maxEntries` evicts from the front.
|
|
101
|
+
*/
|
|
102
|
+
export class DiscoveryCache {
|
|
103
|
+
entries = new Map();
|
|
104
|
+
flights = new Map();
|
|
105
|
+
maxEntries;
|
|
106
|
+
ttlMs;
|
|
107
|
+
cacheable;
|
|
108
|
+
now;
|
|
109
|
+
constructor(options) {
|
|
110
|
+
this.maxEntries = Math.max(0, Math.trunc(options.maxEntries));
|
|
111
|
+
this.ttlMs = options.ttlMs;
|
|
112
|
+
this.cacheable = options.cacheable ?? defaultCacheable;
|
|
113
|
+
this.now = options.now ?? Date.now;
|
|
114
|
+
}
|
|
115
|
+
/** Stored entries currently held (expired ones are dropped as they are read). */
|
|
116
|
+
get size() {
|
|
117
|
+
return this.entries.size;
|
|
118
|
+
}
|
|
119
|
+
/** Keys with an in-flight shared run. */
|
|
120
|
+
get pending() {
|
|
121
|
+
return this.flights.size;
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Resolve one discovery transaction, reusing a cached judgment or joining the
|
|
125
|
+
* in-flight run for the same key.
|
|
126
|
+
*
|
|
127
|
+
* - a warm entry is returned without invoking `factory`;
|
|
128
|
+
* - concurrent callers with the same key share ONE `factory` invocation;
|
|
129
|
+
* - `signal` cancels only THIS caller's wait (resolving `cancelled`, so the
|
|
130
|
+
* caller activates nothing); the shared request is aborted only when the
|
|
131
|
+
* last waiter's signal aborts;
|
|
132
|
+
* - a factory rejection (timeout, transport error, partial batch) is
|
|
133
|
+
* propagated to every remaining waiter and caches nothing.
|
|
134
|
+
* @param key - the key from {@link buildDiscoveryCacheKey}.
|
|
135
|
+
* @param factory - performs the judgment; receives the shared abort signal.
|
|
136
|
+
* @param signal - the calling transaction's own cancellation signal.
|
|
137
|
+
* @returns the judgment, or `cancelled` when this caller left.
|
|
138
|
+
*/
|
|
139
|
+
async run(key, factory, signal) {
|
|
140
|
+
const cached = this.read(key);
|
|
141
|
+
if (cached !== undefined)
|
|
142
|
+
return { status: 'ok', value: cached.value };
|
|
143
|
+
if (signal?.aborted === true)
|
|
144
|
+
return { status: 'cancelled' };
|
|
145
|
+
const flight = this.flightOf(key, factory);
|
|
146
|
+
return this.awaitFlight(key, flight, signal);
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Drop every stored entry and abort every in-flight run, resolving its
|
|
150
|
+
* waiters as cancelled. This is the plugin-unload / rollback hook (design
|
|
151
|
+
* § "Lifecycle, cache, and failure handling" and § "Release gates and
|
|
152
|
+
* rollback").
|
|
153
|
+
*/
|
|
154
|
+
clear() {
|
|
155
|
+
this.entries.clear();
|
|
156
|
+
for (const [key, flight] of [...this.flights]) {
|
|
157
|
+
this.flights.delete(key);
|
|
158
|
+
flight.settled = true;
|
|
159
|
+
if (!flight.controller.signal.aborted)
|
|
160
|
+
flight.controller.abort();
|
|
161
|
+
for (const waiter of [...flight.waiters]) {
|
|
162
|
+
flight.waiters.delete(waiter);
|
|
163
|
+
waiter.resolve({ status: 'cancelled' });
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
/** A warm, unexpired entry, promoted to the MRU end. */
|
|
168
|
+
read(key) {
|
|
169
|
+
const entry = this.entries.get(key);
|
|
170
|
+
if (entry === undefined)
|
|
171
|
+
return undefined;
|
|
172
|
+
// Lazy expiry: no timer, no sweep — an expired entry is absent on read.
|
|
173
|
+
if (this.ttlMs <= 0 || this.now() - entry.storedAt >= this.ttlMs) {
|
|
174
|
+
this.entries.delete(key);
|
|
175
|
+
return undefined;
|
|
176
|
+
}
|
|
177
|
+
this.entries.delete(key);
|
|
178
|
+
this.entries.set(key, entry);
|
|
179
|
+
return entry;
|
|
180
|
+
}
|
|
181
|
+
/** Store one completed judgment, evicting the least recently used entry. */
|
|
182
|
+
store(key, value) {
|
|
183
|
+
if (this.maxEntries <= 0)
|
|
184
|
+
return;
|
|
185
|
+
if (!this.cacheable(value))
|
|
186
|
+
return;
|
|
187
|
+
this.entries.delete(key);
|
|
188
|
+
this.entries.set(key, { value, storedAt: this.now() });
|
|
189
|
+
while (this.entries.size > this.maxEntries) {
|
|
190
|
+
const oldest = this.entries.keys().next();
|
|
191
|
+
if (oldest.done === true)
|
|
192
|
+
return;
|
|
193
|
+
this.entries.delete(oldest.value);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
/** The flight for a key, starting one when this caller is the first. */
|
|
197
|
+
flightOf(key, factory) {
|
|
198
|
+
const existing = this.flights.get(key);
|
|
199
|
+
if (existing !== undefined)
|
|
200
|
+
return existing;
|
|
201
|
+
const flight = { controller: new AbortController(), waiters: new Set(), settled: false };
|
|
202
|
+
this.flights.set(key, flight);
|
|
203
|
+
this.start(key, flight, factory);
|
|
204
|
+
return flight;
|
|
205
|
+
}
|
|
206
|
+
/** Invoke the factory once and settle the flight when it finishes. */
|
|
207
|
+
start(key, flight, factory) {
|
|
208
|
+
let started;
|
|
209
|
+
try {
|
|
210
|
+
started = factory(flight.controller.signal);
|
|
211
|
+
}
|
|
212
|
+
catch (error) {
|
|
213
|
+
// A factory that throws synchronously is a failed run like any other.
|
|
214
|
+
started = Promise.reject(error);
|
|
215
|
+
}
|
|
216
|
+
// The rejection is always handled here, so an abandoned run whose factory
|
|
217
|
+
// aborts and then rejects never surfaces as an unhandled rejection.
|
|
218
|
+
void started.then(value => this.complete(key, flight, value), error => this.fail(key, flight, error));
|
|
219
|
+
}
|
|
220
|
+
/** Store (when allowed), then wake every remaining waiter with the value. */
|
|
221
|
+
complete(key, flight, value) {
|
|
222
|
+
this.detach(key, flight);
|
|
223
|
+
flight.settled = true;
|
|
224
|
+
// A run that lost its last waiter was aborted; it is never cached, even if
|
|
225
|
+
// the factory resolved anyway.
|
|
226
|
+
if (!flight.controller.signal.aborted)
|
|
227
|
+
this.store(key, value);
|
|
228
|
+
for (const waiter of [...flight.waiters]) {
|
|
229
|
+
flight.waiters.delete(waiter);
|
|
230
|
+
waiter.resolve({ status: 'ok', value });
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
/** Propagate a failed run to every remaining waiter; nothing is cached. */
|
|
234
|
+
fail(key, flight, error) {
|
|
235
|
+
this.detach(key, flight);
|
|
236
|
+
flight.settled = true;
|
|
237
|
+
for (const waiter of [...flight.waiters]) {
|
|
238
|
+
flight.waiters.delete(waiter);
|
|
239
|
+
waiter.reject(error);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
/** Forget the flight for a key, leaving a newer one in place if it replaced this. */
|
|
243
|
+
detach(key, flight) {
|
|
244
|
+
if (this.flights.get(key) === flight)
|
|
245
|
+
this.flights.delete(key);
|
|
246
|
+
}
|
|
247
|
+
/** Remove one waiter, aborting the shared request when it was the last. */
|
|
248
|
+
leave(key, flight, waiter) {
|
|
249
|
+
flight.waiters.delete(waiter);
|
|
250
|
+
if (flight.settled || flight.waiters.size > 0)
|
|
251
|
+
return;
|
|
252
|
+
// Last waiter gone: nothing can publish this run, so abort it and stop
|
|
253
|
+
// coalescing onto it. The late settlement above caches nothing.
|
|
254
|
+
this.detach(key, flight);
|
|
255
|
+
if (!flight.controller.signal.aborted)
|
|
256
|
+
flight.controller.abort();
|
|
257
|
+
}
|
|
258
|
+
/** Register one caller as a waiter of a flight. */
|
|
259
|
+
awaitFlight(key, flight, signal) {
|
|
260
|
+
return new Promise((resolve, reject) => {
|
|
261
|
+
let settled = false;
|
|
262
|
+
const unwatch = () => signal?.removeEventListener('abort', onAbort);
|
|
263
|
+
const onAbort = () => {
|
|
264
|
+
if (settled)
|
|
265
|
+
return;
|
|
266
|
+
settled = true;
|
|
267
|
+
// THIS caller leaves; the judgment continues for the other waiters.
|
|
268
|
+
this.leave(key, flight, waiter);
|
|
269
|
+
resolve({ status: 'cancelled' });
|
|
270
|
+
};
|
|
271
|
+
const waiter = {
|
|
272
|
+
resolve: (outcome) => {
|
|
273
|
+
if (settled)
|
|
274
|
+
return;
|
|
275
|
+
settled = true;
|
|
276
|
+
unwatch();
|
|
277
|
+
resolve(outcome);
|
|
278
|
+
},
|
|
279
|
+
reject: (error) => {
|
|
280
|
+
if (settled)
|
|
281
|
+
return;
|
|
282
|
+
settled = true;
|
|
283
|
+
unwatch();
|
|
284
|
+
reject(error);
|
|
285
|
+
},
|
|
286
|
+
};
|
|
287
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
288
|
+
flight.waiters.add(waiter);
|
|
289
|
+
// The signal may have aborted between the pre-check and the listener
|
|
290
|
+
// registration; an already-aborted signal never fires the event.
|
|
291
|
+
if (signal?.aborted === true)
|
|
292
|
+
onAbort();
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
//# sourceMappingURL=discovery-cache.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery-cache.js","sourceRoot":"","sources":["../src/discovery-cache.ts"],"names":[],"mappings":"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"}
|