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.
Files changed (4) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +31 -14
  3. package/index.js +72 -11
  4. 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.0 is the provider protocol MVP.** It ships the `ctx.evidence`
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.0.
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 and empty segments are rejected.
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 `(query, { limit })`.
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 only adds an
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` and `invalid_sources`.
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.0
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, timeouts or tracing yet; `freshness`
115
- is passed through from providers unchanged.
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
- return match === null ? undefined : { source: match[1], id: match[2] }
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
- * Hits are keyed by `ref`; the highest-scoring duplicate wins. The merged
127
- * list is sorted by score descending and then source, truncated to `limit`,
128
- * and returned with one error entry per failed (or malformed) provider.
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(async provider => provider.search(text, { limit })),
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({ source, code: 'provider_failed', message: messageOf(outcome.reason) })
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, { sources: args?.sources, limit: args?.limit }),
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.0",
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 || >=0.2.2-0 <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"