@dsh-cc/tool-search 0.9.4 → 0.9.5
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 +56 -1
- package/README.zh.md +56 -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 +341 -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 +15 -4
|
@@ -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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"}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The structural boundary between tool discovery and S1-02's decision runtime:
|
|
3
|
+
* the request/response faces it consumes, the host resolver seam, and the two
|
|
4
|
+
* snapshot digests that pin a judgment to a catalog and an admission set.
|
|
5
|
+
*
|
|
6
|
+
* Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
|
|
7
|
+
* § "File responsibilities" (the runner comes from the optional
|
|
8
|
+
* `ctx.systemoneDecisions` service; re-read the identity after every await and
|
|
9
|
+
* compare all fields), § "Inputs, questions, and output", § "Lifecycle, cache,
|
|
10
|
+
* and failure handling" (what the cache key pins).
|
|
11
|
+
*
|
|
12
|
+
* These interfaces are declared STRUCTURALLY — exactly as `discovery.ts`
|
|
13
|
+
* declares the question and answer shapes — so `@dsh-cc/tool-search` never takes
|
|
14
|
+
* a dependency on the SystemOne client: the host passes its real
|
|
15
|
+
* `BoundDecisionRunner`/`DecisionRun` through these seams unchanged.
|
|
16
|
+
*
|
|
17
|
+
* @module @dsh-cc/tool-search/discovery-contract
|
|
18
|
+
*/
|
|
19
|
+
import type { DeferredEntry, DiscoveryAnswer, DiscoveryCandidate, DiscoveryQuestion, DiscoveryRouteIdentity, DiscoverySettings } from './discovery.ts';
|
|
20
|
+
import type { DiscoveryThresholds } from './discovery-cache.ts';
|
|
21
|
+
/** The actor a judgment is bound to: structurally an `Agent`, opaque here. */
|
|
22
|
+
export type DiscoveryActor = object;
|
|
23
|
+
/**
|
|
24
|
+
* The metering scope S1-02 binds to an actor: the host resolves project,
|
|
25
|
+
* session and agent, and `originSeq` is the persisted session watermark —
|
|
26
|
+
* never `events.length` (§ "Inputs, questions, and output").
|
|
27
|
+
*/
|
|
28
|
+
export interface DiscoveryScope {
|
|
29
|
+
readonly projectKey: string;
|
|
30
|
+
readonly sessionId: string;
|
|
31
|
+
readonly agentId: string;
|
|
32
|
+
readonly originSeq: number;
|
|
33
|
+
}
|
|
34
|
+
/** One parsed answer map, keyed by question key. */
|
|
35
|
+
export type DiscoveryAnswerMap = Readonly<Record<string, DiscoveryAnswer | undefined>>;
|
|
36
|
+
/** The closed unavailable reasons of a runner decision (S1-02 contract). */
|
|
37
|
+
export type DiscoveryUnavailableReason = 'unconfigured' | 'budget' | 'timeout' | 'cancelled' | 'malformed' | 'error';
|
|
38
|
+
/** One runner response, structurally S1-02's `DecisionRun`. */
|
|
39
|
+
export type DiscoveryDecisionRun = {
|
|
40
|
+
readonly status: 'answered';
|
|
41
|
+
readonly answers: DiscoveryAnswerMap;
|
|
42
|
+
readonly decisionId?: string;
|
|
43
|
+
} | {
|
|
44
|
+
readonly status: 'unavailable';
|
|
45
|
+
readonly reason: DiscoveryUnavailableReason;
|
|
46
|
+
readonly decisionId?: string;
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* The one request this layer sends, structurally S1-02's `DecisionRequest`.
|
|
50
|
+
* `state` carries ONLY the query and this batch's candidate metadata — no tool
|
|
51
|
+
* callbacks, credentials, parameter schemas or message history.
|
|
52
|
+
*/
|
|
53
|
+
export interface DiscoveryDecisionRequest {
|
|
54
|
+
readonly feature: 'tool-discovery';
|
|
55
|
+
readonly mode: 'shadow' | 'active';
|
|
56
|
+
readonly routeAlias: string;
|
|
57
|
+
readonly questionVersion: string;
|
|
58
|
+
readonly policyVersion: string;
|
|
59
|
+
readonly scope: DiscoveryScope;
|
|
60
|
+
readonly state: unknown;
|
|
61
|
+
readonly questions: Record<string, DiscoveryQuestion>;
|
|
62
|
+
readonly timeoutMs: number;
|
|
63
|
+
readonly maxInputTokens: number;
|
|
64
|
+
readonly signal: AbortSignal;
|
|
65
|
+
}
|
|
66
|
+
/** The bound runner face this layer consumes: S1-02's `BoundDecisionRunner`. */
|
|
67
|
+
export interface DiscoveryRunner {
|
|
68
|
+
identifyRoute(alias: string, scope: DiscoveryScope): DiscoveryRouteIdentity | undefined;
|
|
69
|
+
scope(originSeq?: number): DiscoveryScope;
|
|
70
|
+
run(request: DiscoveryDecisionRequest): Promise<DiscoveryDecisionRun>;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* The host face the default resolver reads: the optional `systemoneDecisions`
|
|
74
|
+
* service mounted by S1-02's `decision-usage` plugin. Its absence is the
|
|
75
|
+
* design's "runner missing" row — a lexical fallback with no model call.
|
|
76
|
+
*/
|
|
77
|
+
export interface DiscoveryHostFace {
|
|
78
|
+
readonly systemoneDecisions?: {
|
|
79
|
+
forAgent(actor: DiscoveryActor): DiscoveryRunner;
|
|
80
|
+
};
|
|
81
|
+
readonly ccSystemoneDecisions?: {
|
|
82
|
+
forAgent(actor: DiscoveryActor): DiscoveryRunner;
|
|
83
|
+
};
|
|
84
|
+
/** Optional guarded service getter (structurally cordis `ctx.get`). */
|
|
85
|
+
get?(name: string): unknown;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* The default runner resolver: read the optional host service and bind it to
|
|
89
|
+
* the calling actor. Never throws — a service that refuses to bind is
|
|
90
|
+
* "unavailable", not a failed search.
|
|
91
|
+
*
|
|
92
|
+
* Resolution order (issue #359: tool-search is mounted at the bundle layer,
|
|
93
|
+
* the ROOT realm, where the isolate-scoped `systemoneDecisions` name has no
|
|
94
|
+
* implementation — the root-realm bridge `ccSystemoneDecisions`, published by
|
|
95
|
+
* `@dsh-cc/decision-usage` for exactly such out-of-group consumers, is the
|
|
96
|
+
* production landing):
|
|
97
|
+
*
|
|
98
|
+
* 1. `host.get('systemoneDecisions')` — the isolated name, so in-group hosts
|
|
99
|
+
* bind their OWN tree's instance (a second preset tree can overwrite the
|
|
100
|
+
* root bridge while each tree keeps its isolated service).
|
|
101
|
+
* 2. `host.get('ccSystemoneDecisions')` — the root-realm bridge.
|
|
102
|
+
* 3. Property fallbacks — the pre-bridge behavior, for structural hosts
|
|
103
|
+
* without a `get` seam.
|
|
104
|
+
*
|
|
105
|
+
* Each step is individually guarded: a throw (an isolate name crossing
|
|
106
|
+
* realms), an `undefined` result (no implementation in this realm's store) or
|
|
107
|
+
* a wrong-shaped value degrades to the NEXT step, never aborts resolution.
|
|
108
|
+
* @param host - the host context face (structurally the cordis context).
|
|
109
|
+
* @returns the resolver handed to `createDiscoveryRuntime`.
|
|
110
|
+
*/
|
|
111
|
+
export declare function hostRunnerResolver(host: DiscoveryHostFace): (actor: DiscoveryActor) => DiscoveryRunner | undefined;
|
|
112
|
+
/**
|
|
113
|
+
* `catalogHash` — the approved resolution of the design's underspecified
|
|
114
|
+
* "catalog hash": `sha256` over the sorted `(name, description, searchHint)`
|
|
115
|
+
* triples of the eligible pool. A registration, an unload, or a description
|
|
116
|
+
* edit changes it, which invalidates every cached judgment (§ "Lifecycle,
|
|
117
|
+
* cache, and failure handling": "Candidate activation, registration, unload, or
|
|
118
|
+
* a limit change alters the key").
|
|
119
|
+
* @param candidates - the eligible pool.
|
|
120
|
+
* @returns an opaque `sha256:…` digest.
|
|
121
|
+
*/
|
|
122
|
+
export declare function catalogHashOf(candidates: readonly DiscoveryCandidate[]): string;
|
|
123
|
+
/**
|
|
124
|
+
* `admissionHash` — the approved resolution of the design's underspecified
|
|
125
|
+
* "admission hash": `sha256` over the sorted `(name, isAdmitted)` pairs of the
|
|
126
|
+
* pool. The pool only holds admitted entries, so this pins the permission
|
|
127
|
+
* verdict the judgment was made under; a restriction applied during the
|
|
128
|
+
* judgment changes the pool and discards it at step 9.
|
|
129
|
+
* @param candidates - the eligible pool.
|
|
130
|
+
* @param entries - the snapshot the pool was built from (the verdict source).
|
|
131
|
+
* @returns an opaque `sha256:…` digest.
|
|
132
|
+
*/
|
|
133
|
+
export declare function admissionHashOf(candidates: readonly DiscoveryCandidate[], entries: readonly DeferredEntry[]): string;
|
|
134
|
+
/**
|
|
135
|
+
* The judgment-shaping thresholds, camelCase, for the cache key (§ "Settings").
|
|
136
|
+
* The two cache knobs are deliberately absent: they govern reuse, not what a
|
|
137
|
+
* judgment means.
|
|
138
|
+
*/
|
|
139
|
+
export declare function thresholdsOf(settings: DiscoverySettings): DiscoveryThresholds;
|
|
140
|
+
/** Whether two identities agree on ALL SEVEN fields (§ "File responsibilities"). */
|
|
141
|
+
export declare function sameIdentity(left: DiscoveryRouteIdentity, right: DiscoveryRouteIdentity): boolean;
|
|
142
|
+
/** Whether two metering scopes agree: a different scope is a different judgment. */
|
|
143
|
+
export declare function sameScope(left: DiscoveryScope, right: DiscoveryScope): boolean;
|
|
144
|
+
//# sourceMappingURL=discovery-contract.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery-contract.d.ts","sourceRoot":"","sources":["../src/discovery-contract.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The structural boundary between tool discovery and S1-02's decision runtime:
|
|
3
|
+
* the request/response faces it consumes, the host resolver seam, and the two
|
|
4
|
+
* snapshot digests that pin a judgment to a catalog and an admission set.
|
|
5
|
+
*
|
|
6
|
+
* Design: `docs/plans/2026-11-02-systemone-05-tool-discovery.md`
|
|
7
|
+
* § "File responsibilities" (the runner comes from the optional
|
|
8
|
+
* `ctx.systemoneDecisions` service; re-read the identity after every await and
|
|
9
|
+
* compare all fields), § "Inputs, questions, and output", § "Lifecycle, cache,
|
|
10
|
+
* and failure handling" (what the cache key pins).
|
|
11
|
+
*
|
|
12
|
+
* These interfaces are declared STRUCTURALLY — exactly as `discovery.ts`
|
|
13
|
+
* declares the question and answer shapes — so `@dsh-cc/tool-search` never takes
|
|
14
|
+
* a dependency on the SystemOne client: the host passes its real
|
|
15
|
+
* `BoundDecisionRunner`/`DecisionRun` through these seams unchanged.
|
|
16
|
+
*
|
|
17
|
+
* @module @dsh-cc/tool-search/discovery-contract
|
|
18
|
+
*/
|
|
19
|
+
import { createHash } from 'node:crypto';
|
|
20
|
+
/** The service shape both names must carry to be usable. */
|
|
21
|
+
function isRunnerService(value) {
|
|
22
|
+
return typeof value === 'object' && value !== null
|
|
23
|
+
&& typeof value.forAgent === 'function';
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The default runner resolver: read the optional host service and bind it to
|
|
27
|
+
* the calling actor. Never throws — a service that refuses to bind is
|
|
28
|
+
* "unavailable", not a failed search.
|
|
29
|
+
*
|
|
30
|
+
* Resolution order (issue #359: tool-search is mounted at the bundle layer,
|
|
31
|
+
* the ROOT realm, where the isolate-scoped `systemoneDecisions` name has no
|
|
32
|
+
* implementation — the root-realm bridge `ccSystemoneDecisions`, published by
|
|
33
|
+
* `@dsh-cc/decision-usage` for exactly such out-of-group consumers, is the
|
|
34
|
+
* production landing):
|
|
35
|
+
*
|
|
36
|
+
* 1. `host.get('systemoneDecisions')` — the isolated name, so in-group hosts
|
|
37
|
+
* bind their OWN tree's instance (a second preset tree can overwrite the
|
|
38
|
+
* root bridge while each tree keeps its isolated service).
|
|
39
|
+
* 2. `host.get('ccSystemoneDecisions')` — the root-realm bridge.
|
|
40
|
+
* 3. Property fallbacks — the pre-bridge behavior, for structural hosts
|
|
41
|
+
* without a `get` seam.
|
|
42
|
+
*
|
|
43
|
+
* Each step is individually guarded: a throw (an isolate name crossing
|
|
44
|
+
* realms), an `undefined` result (no implementation in this realm's store) or
|
|
45
|
+
* a wrong-shaped value degrades to the NEXT step, never aborts resolution.
|
|
46
|
+
* @param host - the host context face (structurally the cordis context).
|
|
47
|
+
* @returns the resolver handed to `createDiscoveryRuntime`.
|
|
48
|
+
*/
|
|
49
|
+
export function hostRunnerResolver(host) {
|
|
50
|
+
const viaGet = (name) => {
|
|
51
|
+
try {
|
|
52
|
+
const service = host.get?.(name);
|
|
53
|
+
return isRunnerService(service) ? service : undefined;
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
return undefined;
|
|
57
|
+
}
|
|
58
|
+
};
|
|
59
|
+
return (actor) => {
|
|
60
|
+
const service = viaGet('systemoneDecisions')
|
|
61
|
+
?? viaGet('ccSystemoneDecisions')
|
|
62
|
+
?? (isRunnerService(host.systemoneDecisions) ? host.systemoneDecisions : undefined)
|
|
63
|
+
?? (isRunnerService(host.ccSystemoneDecisions) ? host.ccSystemoneDecisions : undefined);
|
|
64
|
+
if (service === undefined)
|
|
65
|
+
return undefined;
|
|
66
|
+
try {
|
|
67
|
+
return service.forAgent(actor);
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
/** Total deterministic digest: `sha256:` over the JSON of the value. */
|
|
75
|
+
function digest(value) {
|
|
76
|
+
return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
|
|
77
|
+
}
|
|
78
|
+
/** Name-ascending order, the id order {@link buildEligiblePool} assigns. */
|
|
79
|
+
function byName(left, right) {
|
|
80
|
+
return left.name.localeCompare(right.name);
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* `catalogHash` — the approved resolution of the design's underspecified
|
|
84
|
+
* "catalog hash": `sha256` over the sorted `(name, description, searchHint)`
|
|
85
|
+
* triples of the eligible pool. A registration, an unload, or a description
|
|
86
|
+
* edit changes it, which invalidates every cached judgment (§ "Lifecycle,
|
|
87
|
+
* cache, and failure handling": "Candidate activation, registration, unload, or
|
|
88
|
+
* a limit change alters the key").
|
|
89
|
+
* @param candidates - the eligible pool.
|
|
90
|
+
* @returns an opaque `sha256:…` digest.
|
|
91
|
+
*/
|
|
92
|
+
export function catalogHashOf(candidates) {
|
|
93
|
+
return digest([...candidates].sort(byName).map(candidate => [candidate.name, candidate.description, candidate.searchHint ?? null]));
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* `admissionHash` — the approved resolution of the design's underspecified
|
|
97
|
+
* "admission hash": `sha256` over the sorted `(name, isAdmitted)` pairs of the
|
|
98
|
+
* pool. The pool only holds admitted entries, so this pins the permission
|
|
99
|
+
* verdict the judgment was made under; a restriction applied during the
|
|
100
|
+
* judgment changes the pool and discards it at step 9.
|
|
101
|
+
* @param candidates - the eligible pool.
|
|
102
|
+
* @param entries - the snapshot the pool was built from (the verdict source).
|
|
103
|
+
* @returns an opaque `sha256:…` digest.
|
|
104
|
+
*/
|
|
105
|
+
export function admissionHashOf(candidates, entries) {
|
|
106
|
+
const admitted = new Map(entries.map(entry => [entry.name, entry.admitted]));
|
|
107
|
+
return digest([...candidates].sort(byName).map(candidate => [candidate.name, admitted.get(candidate.name) === true]));
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* The judgment-shaping thresholds, camelCase, for the cache key (§ "Settings").
|
|
111
|
+
* The two cache knobs are deliberately absent: they govern reuse, not what a
|
|
112
|
+
* judgment means.
|
|
113
|
+
*/
|
|
114
|
+
export function thresholdsOf(settings) {
|
|
115
|
+
return {
|
|
116
|
+
timeoutMs: settings.timeoutMs,
|
|
117
|
+
maxInputTokens: settings.maxInputTokens,
|
|
118
|
+
maxCandidates: settings.maxCandidates,
|
|
119
|
+
batchSize: settings.batchSize,
|
|
120
|
+
maxQueryChars: settings.maxQueryChars,
|
|
121
|
+
maxMetadataChars: settings.maxMetadataChars,
|
|
122
|
+
minRelevanceIndex: settings.minRelevanceIndex,
|
|
123
|
+
minDirectFit: settings.minDirectFit,
|
|
124
|
+
maxActivations: settings.maxActivations,
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
/** Whether two identities agree on ALL SEVEN fields (§ "File responsibilities"). */
|
|
128
|
+
export function sameIdentity(left, right) {
|
|
129
|
+
return left.provider === right.provider
|
|
130
|
+
&& left.model === right.model
|
|
131
|
+
&& left.revision === right.revision
|
|
132
|
+
&& left.perRequestTokens === right.perRequestTokens
|
|
133
|
+
&& left.perQuestionTokens === right.perQuestionTokens
|
|
134
|
+
&& left.maxQuestions === right.maxQuestions
|
|
135
|
+
&& left.maxOutputTokens === right.maxOutputTokens;
|
|
136
|
+
}
|
|
137
|
+
/** Whether two metering scopes agree: a different scope is a different judgment. */
|
|
138
|
+
export function sameScope(left, right) {
|
|
139
|
+
return left.projectKey === right.projectKey
|
|
140
|
+
&& left.sessionId === right.sessionId
|
|
141
|
+
&& left.agentId === right.agentId
|
|
142
|
+
&& left.originSeq === right.originSeq;
|
|
143
|
+
}
|
|
144
|
+
//# sourceMappingURL=discovery-contract.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery-contract.js","sourceRoot":"","sources":["../src/discovery-contract.ts"],"names":[],"mappings":"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"}
|