dsh-seek 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +117 -7
  3. package/index.js +258 -5
  4. package/package.json +4 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.0
4
+
5
+ - Implement `SeekService` and provide it as the `ctx.evidence` host seam with
6
+ `registerProvider`, `unregisterProvider`, `providers` and `search`.
7
+ - Fan a query out to selected providers in parallel; a rejected or malformed
8
+ provider only adds an entry to `errors` and never fails the whole query.
9
+ - Validate `dsh://<source>/<id>` refs, normalize hits to
10
+ `{ ref, source, title, snippet, score?, freshness? }`, and drop invalid or
11
+ ref/source-mismatched hits with an `invalid_hit` error.
12
+ - Deduplicate by `ref` (highest score wins), sort by score descending then
13
+ source, and apply the caller's limit after merging.
14
+ - Add plain-object `seek_search` and `seek_providers` agent tools.
15
+ - 0.1.0 is the provider protocol MVP only: locator, library, memento and web
16
+ adapters, `seek_resolve`, permissions, caching and timeouts are 0.2.0 work.
17
+ - Add `node --test` coverage for fan-out, filtering, deduplication, ordering,
18
+ ref validation, registration and provider failure isolation.
19
+
3
20
  ## 0.0.1
4
21
 
5
22
  - Reserve the `dsh-seek` package name.
package/README.md CHANGED
@@ -1,9 +1,14 @@
1
1
  # Seek · `dsh-seek`
2
2
 
3
- > Cross-source evidence search for DeepSeek Harness with verifiable refs and freshness.
3
+ > Cross-source evidence search for DeepSeek Harness: one query, many providers,
4
+ > verifiable `dsh://` refs, and partial results when a provider fails.
4
5
 
5
- **Status: 0.0.1 name reservation.** The working design lives in the
6
- [dsh-os design notes](https://github.com/PerryLink/dsh-os#readme). A functional MVP is planned for 0.1.0.
6
+ **Status: 0.1.0 is the provider protocol MVP.** It ships the `ctx.evidence`
7
+ registry and search contract, hit normalization, ref validation, cross-provider
8
+ deduplication, merged ordering and the two agent tools. It deliberately ships
9
+ **no built-in providers**: the locator, library, memento and web adapters land
10
+ in **0.2.0**. There is no locator integration, web access, cache or persistence
11
+ in 0.1.0.
7
12
 
8
13
  **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
9
14
  of their respective owners.
@@ -14,8 +19,113 @@ of their respective owners.
14
19
  dsh plugin --profile web add dsh-seek
15
20
  ```
16
21
 
17
- ## Design
22
+ The bundle patch mounts the plugin and provides `ctx.evidence`.
18
23
 
19
- - Host seam: `ctx.seek` (planned)
20
- - Agent tools and CLI are declared in the package's design doc.
21
- - License: MIT.
24
+ ## Provider protocol
25
+
26
+ A provider is a plain object with a stable lowercase name and an async (or
27
+ sync) `search` function:
28
+
29
+ ```js
30
+ const evidence = ctx.get('evidence')
31
+
32
+ const dispose = evidence.registerProvider({
33
+ name: 'notes',
34
+ async search(query, { limit }) {
35
+ return [{
36
+ ref: 'dsh://notes/retry-policy',
37
+ source: 'notes',
38
+ title: 'Retry policy',
39
+ snippet: `...${query}...`,
40
+ score: 0.8, // optional
41
+ freshness: 'fresh', // optional, passed through
42
+ }]
43
+ },
44
+ })
45
+
46
+ await evidence.search('retry policy', { sources: ['notes'], limit: 10 })
47
+ // { query, hits, total, errors }
48
+
49
+ dispose() // unregister this registration
50
+ evidence.unregisterProvider('notes') // or remove by name
51
+ evidence.providers() // ['notes']
52
+ ```
53
+
54
+ ### Refs
55
+
56
+ Every hit must carry `ref: 'dsh://<source>/<id>'`:
57
+
58
+ - `source` is lowercase, starts with a letter and matches
59
+ `[a-z][a-z0-9._-]{0,63}`.
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.
62
+ - If a hit supplies `source`, it must equal the source inside its ref.
63
+ Otherwise the hit is dropped.
64
+
65
+ Invalid or mismatched hits are omitted from the result and reported as one
66
+ `invalid_hit` error per provider; they never poison the rest of the query.
67
+
68
+ ### Search semantics
69
+
70
+ `evidence.search(query, { sources, limit })`:
71
+
72
+ - Requires a non-empty string query (trimmed); `limit` is a positive integer,
73
+ default 10, capped at 100.
74
+ - `sources` selects providers by name; unknown names are ignored, and an empty
75
+ array returns an empty result without calling any provider.
76
+ - Calls every selected provider **in parallel** with `(query, { limit })`.
77
+ - Merges hits by `ref`, keeping the highest `score` (missing score sorts as 0).
78
+ - Sorts by `score` descending, then by `source` ascending.
79
+ - Applies `limit` after deduplication and sorting; `total` is the number of
80
+ 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.
83
+
84
+ ## Agent tools
85
+
86
+ | Tool | Arguments | Result |
87
+ | --- | --- | --- |
88
+ | `seek_search` | `query` (required), `sources?`, `limit?` | `{ query, hits, total, errors }` |
89
+ | `seek_providers` | none | `{ providers: string[] }` |
90
+
91
+ Both are plain-object tools (no `@deepseek-ai/dsh-tools` dependency) and return
92
+ lossless JSON through the host tool pipeline.
93
+
94
+ ## Errors
95
+
96
+ Expected failures throw an `Error` with a stable `code`:
97
+ `invalid_provider`, `provider_exists`, `invalid_query`, `invalid_limit`,
98
+ `invalid_options` and `invalid_sources`.
99
+
100
+ Per-query provider problems are returned, not thrown:
101
+
102
+ ```js
103
+ {
104
+ source: 'notes',
105
+ code: 'provider_failed', // or 'invalid_hit'
106
+ message: 'boom',
107
+ }
108
+ ```
109
+
110
+ ## Limits of 0.1.0
111
+
112
+ - No first-party providers: registering locator/library/memento/web adapters is
113
+ the 0.2.0 milestone.
114
+ - No `seek_resolve`, permissions, caching, timeouts or tracing yet; `freshness`
115
+ is passed through from providers unchanged.
116
+ - No network I/O and no writes to provider data. Seek only reads.
117
+ - Provider callers should still apply their own ACLs before returning hits;
118
+ Seek does not expose a permission model in this release.
119
+
120
+ ## Development
121
+
122
+ ```sh
123
+ cd packages/seek
124
+ node --test
125
+ ```
126
+
127
+ Pure ESM JavaScript, Node 22+, no runtime dependencies and no build step.
128
+
129
+ ## License
130
+
131
+ MIT. See [LICENSE](./LICENSE).
package/index.js CHANGED
@@ -1,13 +1,266 @@
1
1
  /**
2
- * dsh-seek — Cross-source evidence search for DeepSeek Harness with verifiable refs and freshness.
2
+ * dsh-seek — cross-source evidence search for DeepSeek Harness.
3
3
  *
4
- * 0.0.1 placeholder: the bundle loads and provides a stable package name.
5
- * The functional implementation lands in 0.1.0.
4
+ * 0.1.0 is the provider protocol MVP: `ctx.evidence` fans one query out to
5
+ * named providers, normalizes and deduplicates their hits, and returns a
6
+ * partial result plus per-provider errors. First-party locator / library /
7
+ * memento / web adapters are intentionally out of scope until 0.2.0.
6
8
  * @module dsh-seek
7
9
  */
8
10
 
9
11
  /** Cordis plugin name. */
10
12
  export const name = 'dsh-seek'
11
13
 
12
- /** Mount the plugin. The 0.0.1 placeholder intentionally has no side effects. */
13
- export function apply() {}
14
+ /** The host tool registry is only needed for the two agent tools. */
15
+ export const inject = ['tools']
16
+
17
+ const DEFAULT_LIMIT = 10
18
+ const MAX_LIMIT = 100
19
+
20
+ /** Provider names use the same token grammar as the `<source>` ref segment. */
21
+ const SOURCE_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/
22
+
23
+ /** `dsh://<source>/<id>`, where id is one or more non-empty path segments. */
24
+ const REF_PATTERN = /^dsh:\/\/([a-z][a-z0-9._-]{0,63})\/([^\s/?#]+(?:\/[^\s/?#]+)*)$/
25
+
26
+ function fail(code, message) {
27
+ return Object.assign(new Error(message), { code })
28
+ }
29
+
30
+ function plainObject(value) {
31
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
32
+ }
33
+
34
+ function messageOf(error) {
35
+ if (error instanceof Error) return error.message
36
+ if (plainObject(error) && typeof error.message === 'string') return error.message
37
+ return String(error)
38
+ }
39
+
40
+ /**
41
+ * Parse and validate a `dsh://<source>/<id>` ref.
42
+ * @param {unknown} ref
43
+ * @returns {{ source: string, id: string } | undefined}
44
+ */
45
+ export function parseRef(ref) {
46
+ if (typeof ref !== 'string') return undefined
47
+ const match = REF_PATTERN.exec(ref)
48
+ return match === null ? undefined : { source: match[1], id: match[2] }
49
+ }
50
+
51
+ /** Normalize the caller's limit; invalid explicit values fail closed. */
52
+ function limitOf(value) {
53
+ if (value === undefined) return DEFAULT_LIMIT
54
+ if (!Number.isInteger(value) || value < 1) {
55
+ throw fail('invalid_limit', 'seek: limit must be a positive integer')
56
+ }
57
+ return Math.min(value, MAX_LIMIT)
58
+ }
59
+
60
+ /**
61
+ * Validate one provider hit and reduce it to the documented shape. Invalid
62
+ * refs and ref/source mismatches are dropped by the caller and reported.
63
+ */
64
+ function normalizeHit(value) {
65
+ if (!plainObject(value)) return undefined
66
+ const parsed = parseRef(value.ref)
67
+ if (parsed === undefined) return undefined
68
+ if (value.source !== undefined && value.source !== parsed.source) return undefined
69
+
70
+ const hit = {
71
+ ref: value.ref,
72
+ source: parsed.source,
73
+ title: typeof value.title === 'string' ? value.title : '',
74
+ snippet: typeof value.snippet === 'string' ? value.snippet : '',
75
+ }
76
+ if (typeof value.score === 'number' && Number.isFinite(value.score)) hit.score = value.score
77
+ if (value.freshness !== undefined) hit.freshness = value.freshness
78
+ return hit
79
+ }
80
+
81
+ /** Missing scores sort as zero. */
82
+ function scoreOf(hit) {
83
+ return hit.score ?? 0
84
+ }
85
+
86
+ /** Named provider registry and fan-out search exposed to plugins as `ctx.evidence`. */
87
+ export class SeekService {
88
+ #providers = new Map()
89
+
90
+ /**
91
+ * Register `{ name, search(query, opts) }`. Returns a disposer.
92
+ * @throws {Error} `invalid_provider` or `provider_exists`.
93
+ */
94
+ registerProvider(provider) {
95
+ if (!plainObject(provider)) {
96
+ throw fail('invalid_provider', 'seek: provider must be an object')
97
+ }
98
+ if (typeof provider.name !== 'string' || !SOURCE_PATTERN.test(provider.name)) {
99
+ throw fail('invalid_provider', `seek: invalid provider name: ${String(provider.name)}`)
100
+ }
101
+ if (typeof provider.search !== 'function') {
102
+ throw fail('invalid_provider', `seek: provider "${provider.name}" requires a search function`)
103
+ }
104
+ if (this.#providers.has(provider.name)) {
105
+ throw fail('provider_exists', `seek: provider "${provider.name}" is already registered`)
106
+ }
107
+
108
+ const entry = Object.freeze({ name: provider.name, search: provider.search.bind(provider) })
109
+ this.#providers.set(entry.name, entry)
110
+ return () => (this.#providers.get(entry.name) === entry ? this.#providers.delete(entry.name) : false)
111
+ }
112
+
113
+ /** Remove a provider by name; true when it existed. */
114
+ unregisterProvider(name) {
115
+ return this.#providers.delete(name)
116
+ }
117
+
118
+ /** Registered provider names, in registration order. */
119
+ providers() {
120
+ return [...this.#providers.keys()]
121
+ }
122
+
123
+ /**
124
+ * Query selected providers in parallel.
125
+ *
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.
129
+ *
130
+ * @param {string} query
131
+ * @param {{ sources?: string[], limit?: number }} [options]
132
+ * @returns {Promise<{ query: string, hits: object[], total: number, errors: object[] }>}
133
+ */
134
+ async search(query, options = {}) {
135
+ if (typeof query !== 'string' || query.trim() === '') {
136
+ throw fail('invalid_query', 'seek: query must be a non-empty string')
137
+ }
138
+ if (!plainObject(options)) {
139
+ throw fail('invalid_options', 'seek: options must be an object')
140
+ }
141
+
142
+ const text = query.trim()
143
+ const limit = limitOf(options.limit)
144
+ const selected = this.#select(options.sources)
145
+ const settled = await Promise.allSettled(
146
+ selected.map(async provider => provider.search(text, { limit })),
147
+ )
148
+
149
+ const errors = []
150
+ const byRef = new Map()
151
+ settled.forEach((outcome, index) => {
152
+ const source = selected[index].name
153
+ if (outcome.status === 'rejected') {
154
+ errors.push({ source, code: 'provider_failed', message: messageOf(outcome.reason) })
155
+ return
156
+ }
157
+ if (!Array.isArray(outcome.value)) {
158
+ errors.push({
159
+ source,
160
+ code: 'provider_failed',
161
+ message: 'provider must return an array of hits',
162
+ })
163
+ return
164
+ }
165
+
166
+ let invalid = 0
167
+ for (const raw of outcome.value) {
168
+ const hit = normalizeHit(raw)
169
+ if (hit === undefined) {
170
+ invalid += 1
171
+ continue
172
+ }
173
+ const current = byRef.get(hit.ref)
174
+ if (current === undefined || scoreOf(hit) > scoreOf(current)) byRef.set(hit.ref, hit)
175
+ }
176
+ if (invalid > 0) {
177
+ errors.push({
178
+ source,
179
+ code: 'invalid_hit',
180
+ message: `${invalid} hit(s) omitted: refs must use dsh://<source>/<id> and match hit.source`,
181
+ })
182
+ }
183
+ })
184
+
185
+ const hits = [...byRef.values()].sort((a, b) => scoreOf(b) - scoreOf(a)
186
+ || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0))
187
+ if (hits.length > limit) hits.length = limit
188
+ return { query: text, hits, total: hits.length, errors }
189
+ }
190
+
191
+ /** Snapshot the providers selected by `sources` (all when omitted). */
192
+ #select(sources) {
193
+ const providers = [...this.#providers.values()]
194
+ if (sources === undefined) return providers
195
+ if (!Array.isArray(sources) || sources.some(source => typeof source !== 'string')) {
196
+ throw fail('invalid_sources', 'seek: sources must be an array of provider names')
197
+ }
198
+ const wanted = new Set(sources)
199
+ return providers.filter(provider => wanted.has(provider.name))
200
+ }
201
+ }
202
+
203
+ /** Build a plain-object tool definition accepted by the host. */
204
+ function tool(name, description, parameters, execute) {
205
+ return {
206
+ name,
207
+ description,
208
+ parameters,
209
+ output: {
210
+ schema: { type: 'object', additionalProperties: true },
211
+ render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
212
+ },
213
+ execute,
214
+ }
215
+ }
216
+
217
+ /** `seek_search` tool: one query across all or selected providers. */
218
+ function searchTool(service) {
219
+ return tool(
220
+ 'seek_search',
221
+ 'Search registered evidence providers and return deduplicated hits with dsh:// refs and per-provider errors.',
222
+ {
223
+ type: 'object',
224
+ additionalProperties: false,
225
+ required: ['query'],
226
+ properties: {
227
+ query: { type: 'string', description: 'Text to search for.' },
228
+ sources: {
229
+ type: 'array',
230
+ items: { type: 'string' },
231
+ description: 'Provider names to query; defaults to every registered provider.',
232
+ },
233
+ limit: {
234
+ type: 'integer',
235
+ minimum: 1,
236
+ maximum: MAX_LIMIT,
237
+ description: 'Maximum hits to return (default 10).',
238
+ },
239
+ },
240
+ },
241
+ async args => service.search(args?.query, { sources: args?.sources, limit: args?.limit }),
242
+ )
243
+ }
244
+
245
+ /** `seek_providers` tool: provider discovery for agents. */
246
+ function providersTool(service) {
247
+ return tool(
248
+ 'seek_providers',
249
+ 'List the names of registered Seek evidence providers.',
250
+ { type: 'object', additionalProperties: false, properties: {} },
251
+ async () => ({ providers: service.providers() }),
252
+ )
253
+ }
254
+
255
+ /**
256
+ * Mount dsh-seek: provide `ctx.evidence` and register the two agent tools.
257
+ * @param {object} ctx - Cordis context with `provide` and `tools.register`.
258
+ * @param {object} [_config] - Reserved for 0.2.0; unused by the MVP.
259
+ */
260
+ export function apply(ctx, _config = {}) {
261
+ const service = new SeekService()
262
+ ctx.provide('evidence', service)
263
+ ctx.tools.register(searchTool(service))
264
+ ctx.tools.register(providersTool(service))
265
+ return service
266
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-seek",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "description": "Cross-source evidence search for DeepSeek Harness with verifiable refs and freshness.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -44,5 +44,8 @@
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public"
47
+ },
48
+ "scripts": {
49
+ "test": "node --test"
47
50
  }
48
51
  }