dsh-seek 0.0.0-stage → 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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
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
+
20
+ ## 0.0.1
21
+
22
+ - Reserve the `dsh-seek` package name.
23
+ - Publish the bundle manifest and an empty, side-effect-free plugin entry.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PerryLink contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,131 @@
1
- # Temporary Holding Version
1
+ # Seek · `dsh-seek`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Cross-source evidence search for DeepSeek Harness: one query, many providers,
4
+ > verifiable `dsh://` refs, and partial results when a provider fails.
5
+
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.
12
+
13
+ **Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
14
+ of their respective owners.
15
+
16
+ ## Install
17
+
18
+ ```sh
19
+ dsh plugin --profile web add dsh-seek
20
+ ```
21
+
22
+ The bundle patch mounts the plugin and provides `ctx.evidence`.
23
+
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).
@@ -0,0 +1,4 @@
1
+ # dsh-seek bundle patch: mount the plugin.
2
+ - insert:
3
+ - id: dsh-seek
4
+ name: dsh-seek
package/index.js ADDED
@@ -0,0 +1,266 @@
1
+ /**
2
+ * dsh-seek — cross-source evidence search for DeepSeek Harness.
3
+ *
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.
8
+ * @module dsh-seek
9
+ */
10
+
11
+ /** Cordis plugin name. */
12
+ export const name = 'dsh-seek'
13
+
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,51 @@
1
1
  {
2
2
  "name": "dsh-seek",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Cross-source evidence search for DeepSeek Harness with verifiable refs and freshness.",
5
+ "type": "module",
6
+ "main": "index.js",
7
+ "exports": {
8
+ ".": "./index.js",
9
+ "./package.json": "./package.json"
10
+ },
11
+ "files": [
12
+ "index.js",
13
+ "cordis.patch.yml",
14
+ "README.md",
15
+ "CHANGELOG.md"
16
+ ],
17
+ "keywords": [
18
+ "dsh",
19
+ "dsh-plugin",
20
+ "deepseek-harness",
21
+ "agent-os",
22
+ "seek"
23
+ ],
24
+ "license": "MIT",
25
+ "author": "PerryLink contributors",
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "git+https://github.com/PerryLink/dsh-os.git",
29
+ "directory": "packages/seek"
30
+ },
31
+ "homepage": "https://github.com/PerryLink/dsh-os/tree/main/packages/seek#readme",
32
+ "bugs": {
33
+ "url": "https://github.com/PerryLink/dsh-os/issues"
34
+ },
35
+ "engines": {
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"
38
+ },
39
+ "dsh": {
40
+ "manifestVersion": 1,
41
+ "bundle": {
42
+ "patch": "./cordis.patch.yml"
43
+ }
44
+ },
45
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "scripts": {
49
+ "test": "node --test"
50
+ }
51
+ }