dsh-seek 0.1.0 → 0.1.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/CHANGELOG.md +17 -0
- package/README.md +31 -14
- package/index.js +72 -11
- package/package.json +18 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Add per-provider deadlines. `search(query, { timeoutMs })` defaults to 10 s
|
|
6
|
+
and calls each provider with `(query, { limit, signal, timeoutMs })`, where
|
|
7
|
+
`signal` is `AbortSignal.any([AbortSignal.timeout(timeoutMs), callerSignal])`.
|
|
8
|
+
A provider that times out is reported as `{ code: 'provider_timeout' }` in
|
|
9
|
+
`errors`; it can no longer block the whole query.
|
|
10
|
+
- Add caller cancellation: `search(query, { signal })` forwards the caller's
|
|
11
|
+
`AbortSignal` (the tools pass the host `exec.signal`) to every provider and
|
|
12
|
+
rejects with `code: 'aborted'` once aborted. Invalid signals throw
|
|
13
|
+
`invalid_signal`; invalid timeouts throw `invalid_timeout`.
|
|
14
|
+
- Harden ref validation: `parseRef` now rejects empty and overlong refs
|
|
15
|
+
(`MAX_REF_LENGTH` = 512) and `.`/`..` path segments, in addition to the
|
|
16
|
+
existing `dsh://<source>/<id>` grammar and source/ref match.
|
|
17
|
+
- Add tests for hanging-provider timeouts, abort forwarding, `exec.signal`
|
|
18
|
+
propagation and overlong/dot-segment refs.
|
|
19
|
+
|
|
3
20
|
## 0.1.0
|
|
4
21
|
|
|
5
22
|
- Implement `SeekService` and provide it as the `ctx.evidence` host seam with
|
package/README.md
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
> Cross-source evidence search for DeepSeek Harness: one query, many providers,
|
|
4
4
|
> verifiable `dsh://` refs, and partial results when a provider fails.
|
|
5
5
|
|
|
6
|
-
**Status: 0.1.
|
|
6
|
+
**Status: 0.1.1 is the provider protocol MVP.** It ships the `ctx.evidence`
|
|
7
7
|
registry and search contract, hit normalization, ref validation, cross-provider
|
|
8
8
|
deduplication, merged ordering and the two agent tools. It deliberately ships
|
|
9
9
|
**no built-in providers**: the locator, library, memento and web adapters land
|
|
10
10
|
in **0.2.0**. There is no locator integration, web access, cache or persistence
|
|
11
|
-
in 0.1.
|
|
11
|
+
in 0.1.x.
|
|
12
12
|
|
|
13
13
|
**Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
|
|
14
14
|
of their respective owners.
|
|
@@ -31,7 +31,7 @@ const evidence = ctx.get('evidence')
|
|
|
31
31
|
|
|
32
32
|
const dispose = evidence.registerProvider({
|
|
33
33
|
name: 'notes',
|
|
34
|
-
async search(query, { limit }) {
|
|
34
|
+
async search(query, { limit, signal, timeoutMs }) {
|
|
35
35
|
return [{
|
|
36
36
|
ref: 'dsh://notes/retry-policy',
|
|
37
37
|
source: 'notes',
|
|
@@ -58,7 +58,10 @@ Every hit must carry `ref: 'dsh://<source>/<id>'`:
|
|
|
58
58
|
- `source` is lowercase, starts with a letter and matches
|
|
59
59
|
`[a-z][a-z0-9._-]{0,63}`.
|
|
60
60
|
- `id` is one or more non-empty path segments (`dsh://notes/src/index.js`).
|
|
61
|
-
- Query strings, fragments, whitespace
|
|
61
|
+
- Query strings, fragments, whitespace, empty segments and `.`/`..` segments
|
|
62
|
+
are rejected.
|
|
63
|
+
- A ref must be at most 512 characters (`MAX_REF_LENGTH`); empty and overlong
|
|
64
|
+
refs are rejected.
|
|
62
65
|
- If a hit supplies `source`, it must equal the source inside its ref.
|
|
63
66
|
Otherwise the hit is dropped.
|
|
64
67
|
|
|
@@ -67,25 +70,37 @@ Invalid or mismatched hits are omitted from the result and reported as one
|
|
|
67
70
|
|
|
68
71
|
### Search semantics
|
|
69
72
|
|
|
70
|
-
`evidence.search(query, { sources, limit })`:
|
|
73
|
+
`evidence.search(query, { sources, limit, timeoutMs, signal })`:
|
|
71
74
|
|
|
72
75
|
- Requires a non-empty string query (trimmed); `limit` is a positive integer,
|
|
73
76
|
default 10, capped at 100.
|
|
74
77
|
- `sources` selects providers by name; unknown names are ignored, and an empty
|
|
75
78
|
array returns an empty result without calling any provider.
|
|
76
|
-
- Calls every selected provider **in parallel** with
|
|
79
|
+
- Calls every selected provider **in parallel** with
|
|
80
|
+
`(query, { limit, signal, timeoutMs })`. `timeoutMs` is a positive integer
|
|
81
|
+
(default 10000) and bounds each provider individually; an invalid value throws
|
|
82
|
+
`invalid_timeout`.
|
|
83
|
+
- `signal` is an optional caller `AbortSignal` (normally the host tool's
|
|
84
|
+
`exec.signal`). Aborting it aborts every provider and rejects the query with
|
|
85
|
+
`code: 'aborted'`.
|
|
86
|
+
- A provider gets `signal: AbortSignal.any([AbortSignal.timeout(timeoutMs),
|
|
87
|
+
callerSignal])`, so a cooperative provider can stop its own work, and the
|
|
88
|
+
query races that signal so even a provider that ignores it cannot block the
|
|
89
|
+
result.
|
|
90
|
+
- A timed-out provider is reported as `{ code: 'provider_timeout' }`; other
|
|
91
|
+
rejections or malformed results are reported as `provider_failed`.
|
|
77
92
|
- Merges hits by `ref`, keeping the highest `score` (missing score sorts as 0).
|
|
78
93
|
- Sorts by `score` descending, then by `source` ascending.
|
|
79
94
|
- Applies `limit` after deduplication and sorting; `total` is the number of
|
|
80
95
|
returned hits.
|
|
81
|
-
- Uses `Promise.allSettled`, so one rejected or malformed provider
|
|
82
|
-
entry to `errors`; the other providers still return hits.
|
|
96
|
+
- Uses `Promise.allSettled`, so one rejected, timed-out or malformed provider
|
|
97
|
+
only adds an entry to `errors`; the other providers still return hits.
|
|
83
98
|
|
|
84
99
|
## Agent tools
|
|
85
100
|
|
|
86
101
|
| Tool | Arguments | Result |
|
|
87
102
|
| --- | --- | --- |
|
|
88
|
-
| `seek_search` | `query` (required), `sources?`, `limit?` | `{ query, hits, total, errors }` |
|
|
103
|
+
| `seek_search` | `query` (required), `sources?`, `limit?` | `{ query, hits, total, errors }`; forwards `exec.signal` |
|
|
89
104
|
| `seek_providers` | none | `{ providers: string[] }` |
|
|
90
105
|
|
|
91
106
|
Both are plain-object tools (no `@deepseek-ai/dsh-tools` dependency) and return
|
|
@@ -95,24 +110,26 @@ lossless JSON through the host tool pipeline.
|
|
|
95
110
|
|
|
96
111
|
Expected failures throw an `Error` with a stable `code`:
|
|
97
112
|
`invalid_provider`, `provider_exists`, `invalid_query`, `invalid_limit`,
|
|
98
|
-
`invalid_options`
|
|
113
|
+
`invalid_options`, `invalid_sources`, `invalid_timeout`, `invalid_signal` and
|
|
114
|
+
`aborted`.
|
|
99
115
|
|
|
100
116
|
Per-query provider problems are returned, not thrown:
|
|
101
117
|
|
|
102
118
|
```js
|
|
103
119
|
{
|
|
104
120
|
source: 'notes',
|
|
105
|
-
code: 'provider_failed', // or 'invalid_hit'
|
|
121
|
+
code: 'provider_failed', // or 'provider_timeout', 'invalid_hit'
|
|
106
122
|
message: 'boom',
|
|
107
123
|
}
|
|
108
124
|
```
|
|
109
125
|
|
|
110
|
-
## Limits of 0.1.
|
|
126
|
+
## Limits of 0.1.x
|
|
111
127
|
|
|
112
128
|
- No first-party providers: registering locator/library/memento/web adapters is
|
|
113
129
|
the 0.2.0 milestone.
|
|
114
|
-
- No `seek_resolve`, permissions, caching
|
|
115
|
-
|
|
130
|
+
- No `seek_resolve`, permissions, caching or tracing yet; `freshness` is passed
|
|
131
|
+
through from providers unchanged. Per-provider timeouts and caller-signal
|
|
132
|
+
cancellation are implemented in 0.1.1.
|
|
116
133
|
- No network I/O and no writes to provider data. Seek only reads.
|
|
117
134
|
- Provider callers should still apply their own ACLs before returning hits;
|
|
118
135
|
Seek does not expose a permission model in this release.
|
package/index.js
CHANGED
|
@@ -16,6 +16,10 @@ export const inject = ['tools']
|
|
|
16
16
|
|
|
17
17
|
const DEFAULT_LIMIT = 10
|
|
18
18
|
const MAX_LIMIT = 100
|
|
19
|
+
/** Default per-provider budget; a hanging provider never blocks the query for longer. */
|
|
20
|
+
export const DEFAULT_TIMEOUT_MS = 10_000
|
|
21
|
+
/** Refs longer than this are rejected instead of being passed around as evidence. */
|
|
22
|
+
export const MAX_REF_LENGTH = 512
|
|
19
23
|
|
|
20
24
|
/** Provider names use the same token grammar as the `<source>` ref segment. */
|
|
21
25
|
const SOURCE_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/
|
|
@@ -38,16 +42,39 @@ function messageOf(error) {
|
|
|
38
42
|
}
|
|
39
43
|
|
|
40
44
|
/**
|
|
41
|
-
* Parse and validate a `dsh://<source>/<id>` ref.
|
|
45
|
+
* Parse and validate a `dsh://<source>/<id>` ref. Empty, overlong, malformed
|
|
46
|
+
* and dot-segment (`..`) ids are rejected.
|
|
42
47
|
* @param {unknown} ref
|
|
43
48
|
* @returns {{ source: string, id: string } | undefined}
|
|
44
49
|
*/
|
|
45
50
|
export function parseRef(ref) {
|
|
46
|
-
if (typeof ref !== 'string') return undefined
|
|
51
|
+
if (typeof ref !== 'string' || ref.length === 0 || ref.length > MAX_REF_LENGTH) return undefined
|
|
47
52
|
const match = REF_PATTERN.exec(ref)
|
|
48
|
-
|
|
53
|
+
if (match === null) return undefined
|
|
54
|
+
if (match[2].split('/').some(segment => segment === '.' || segment === '..')) return undefined
|
|
55
|
+
return { source: match[1], id: match[2] }
|
|
49
56
|
}
|
|
50
57
|
|
|
58
|
+
/** Validate the caller's per-provider timeout; invalid values fail closed. */
|
|
59
|
+
function timeoutOf(value) {
|
|
60
|
+
if (value === undefined) return DEFAULT_TIMEOUT_MS
|
|
61
|
+
if (!Number.isInteger(value) || value < 1) {
|
|
62
|
+
throw fail('invalid_timeout', 'seek: timeoutMs must be a positive integer')
|
|
63
|
+
}
|
|
64
|
+
return value
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Validate the caller's cancellation signal, if one was supplied. */
|
|
68
|
+
function signalOf(value) {
|
|
69
|
+
if (value === undefined) return undefined
|
|
70
|
+
if (!(value instanceof AbortSignal)) {
|
|
71
|
+
throw fail('invalid_signal', 'seek: signal must be an AbortSignal')
|
|
72
|
+
}
|
|
73
|
+
return value
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const abortedError = () => fail('aborted', 'seek: search aborted')
|
|
77
|
+
|
|
51
78
|
/** Normalize the caller's limit; invalid explicit values fail closed. */
|
|
52
79
|
function limitOf(value) {
|
|
53
80
|
if (value === undefined) return DEFAULT_LIMIT
|
|
@@ -83,6 +110,24 @@ function scoreOf(hit) {
|
|
|
83
110
|
return hit.score ?? 0
|
|
84
111
|
}
|
|
85
112
|
|
|
113
|
+
/**
|
|
114
|
+
* Call one provider under a hard per-provider budget. The provider receives
|
|
115
|
+
* `{ limit, signal, timeoutMs }`; `signal` is the caller's signal combined with
|
|
116
|
+
* `AbortSignal.timeout(timeoutMs)`, so a cooperative provider can stop its own
|
|
117
|
+
* work, and racing that signal bounds even a provider that ignores it.
|
|
118
|
+
*/
|
|
119
|
+
async function askProvider(provider, text, { limit, timeoutMs, signal }) {
|
|
120
|
+
const deadline = AbortSignal.timeout(timeoutMs)
|
|
121
|
+
const budget = signal === undefined ? deadline : AbortSignal.any([deadline, signal])
|
|
122
|
+
const timedOut = () => fail('provider_timeout', `seek: provider "${provider.name}" timed out after ${timeoutMs} ms`)
|
|
123
|
+
if (budget.aborted) throw deadline.aborted ? timedOut() : abortedError()
|
|
124
|
+
const work = Promise.resolve().then(() => provider.search(text, { limit, signal: budget, timeoutMs }))
|
|
125
|
+
const failure = new Promise((_, reject) => {
|
|
126
|
+
budget.addEventListener('abort', () => reject(deadline.aborted ? timedOut() : abortedError()), { once: true })
|
|
127
|
+
})
|
|
128
|
+
return await Promise.race([work, failure])
|
|
129
|
+
}
|
|
130
|
+
|
|
86
131
|
/** Named provider registry and fan-out search exposed to plugins as `ctx.evidence`. */
|
|
87
132
|
export class SeekService {
|
|
88
133
|
#providers = new Map()
|
|
@@ -123,12 +168,16 @@ export class SeekService {
|
|
|
123
168
|
/**
|
|
124
169
|
* Query selected providers in parallel.
|
|
125
170
|
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
171
|
+
* Every provider is bounded by `timeoutMs` (default 10 s): it receives
|
|
172
|
+
* `{ limit, signal, timeoutMs }`, where `signal` aborts at the deadline or
|
|
173
|
+
* when the caller aborts. A provider that times out, rejects, aborts or
|
|
174
|
+
* returns a malformed shape only adds one `errors` entry; it never blocks the
|
|
175
|
+
* merged result. Hits are keyed by `ref`; the highest-scoring duplicate wins.
|
|
176
|
+
* The merged list is sorted by score descending and then source, and
|
|
177
|
+
* truncated to `limit`.
|
|
129
178
|
*
|
|
130
179
|
* @param {string} query
|
|
131
|
-
* @param {{ sources?: string[], limit?: number }} [options]
|
|
180
|
+
* @param {{ sources?: string[], limit?: number, timeoutMs?: number, signal?: AbortSignal }} [options]
|
|
132
181
|
* @returns {Promise<{ query: string, hits: object[], total: number, errors: object[] }>}
|
|
133
182
|
*/
|
|
134
183
|
async search(query, options = {}) {
|
|
@@ -141,17 +190,25 @@ export class SeekService {
|
|
|
141
190
|
|
|
142
191
|
const text = query.trim()
|
|
143
192
|
const limit = limitOf(options.limit)
|
|
193
|
+
const timeoutMs = timeoutOf(options.timeoutMs)
|
|
194
|
+
const signal = signalOf(options.signal)
|
|
195
|
+
if (signal !== undefined && signal.aborted) throw abortedError()
|
|
144
196
|
const selected = this.#select(options.sources)
|
|
145
197
|
const settled = await Promise.allSettled(
|
|
146
|
-
selected.map(
|
|
198
|
+
selected.map(provider => askProvider(provider, text, { limit, timeoutMs, signal })),
|
|
147
199
|
)
|
|
200
|
+
if (signal !== undefined && signal.aborted) throw abortedError()
|
|
148
201
|
|
|
149
202
|
const errors = []
|
|
150
203
|
const byRef = new Map()
|
|
151
204
|
settled.forEach((outcome, index) => {
|
|
152
205
|
const source = selected[index].name
|
|
153
206
|
if (outcome.status === 'rejected') {
|
|
154
|
-
errors.push({
|
|
207
|
+
errors.push({
|
|
208
|
+
source,
|
|
209
|
+
code: outcome.reason?.code === 'provider_timeout' ? 'provider_timeout' : 'provider_failed',
|
|
210
|
+
message: messageOf(outcome.reason),
|
|
211
|
+
})
|
|
155
212
|
return
|
|
156
213
|
}
|
|
157
214
|
if (!Array.isArray(outcome.value)) {
|
|
@@ -177,7 +234,7 @@ export class SeekService {
|
|
|
177
234
|
errors.push({
|
|
178
235
|
source,
|
|
179
236
|
code: 'invalid_hit',
|
|
180
|
-
message: `${invalid} hit(s) omitted: refs must use dsh://<source>/<id> and match hit.source`,
|
|
237
|
+
message: `${invalid} hit(s) omitted: refs must use dsh://<source>/<id> (at most ${MAX_REF_LENGTH} characters) and match hit.source`,
|
|
181
238
|
})
|
|
182
239
|
}
|
|
183
240
|
})
|
|
@@ -238,7 +295,11 @@ function searchTool(service) {
|
|
|
238
295
|
},
|
|
239
296
|
},
|
|
240
297
|
},
|
|
241
|
-
async args => service.search(args?.query, {
|
|
298
|
+
async (args, exec) => service.search(args?.query, {
|
|
299
|
+
sources: args?.sources,
|
|
300
|
+
limit: args?.limit,
|
|
301
|
+
signal: exec?.signal,
|
|
302
|
+
}),
|
|
242
303
|
)
|
|
243
304
|
}
|
|
244
305
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-seek",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Cross-source evidence search for DeepSeek Harness with verifiable refs and freshness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -34,16 +34,31 @@
|
|
|
34
34
|
},
|
|
35
35
|
"engines": {
|
|
36
36
|
"node": "^22.19.0 || >=24.9.0",
|
|
37
|
-
"dsh": ">=0.2.1-rc.2 <0.3.0
|
|
37
|
+
"dsh": ">=0.2.1-rc.2 <0.3.0-0"
|
|
38
38
|
},
|
|
39
39
|
"dsh": {
|
|
40
40
|
"manifestVersion": 1,
|
|
41
41
|
"bundle": {
|
|
42
42
|
"patch": "./cordis.patch.yml"
|
|
43
|
+
},
|
|
44
|
+
"os": {
|
|
45
|
+
"service": "evidence",
|
|
46
|
+
"provides": [
|
|
47
|
+
"evidence"
|
|
48
|
+
],
|
|
49
|
+
"capabilities": [],
|
|
50
|
+
"tools": [
|
|
51
|
+
"seek_search",
|
|
52
|
+
"seek_providers"
|
|
53
|
+
],
|
|
54
|
+
"ui": null,
|
|
55
|
+
"stability": "experimental",
|
|
56
|
+
"since": "0.1.0"
|
|
43
57
|
}
|
|
44
58
|
},
|
|
45
59
|
"publishConfig": {
|
|
46
|
-
"access": "public"
|
|
60
|
+
"access": "public",
|
|
61
|
+
"registry": "https://registry.npmjs.org/"
|
|
47
62
|
},
|
|
48
63
|
"scripts": {
|
|
49
64
|
"test": "node --test"
|