dsh-seek 0.0.1 → 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 +34 -0
- package/README.md +134 -7
- package/index.js +319 -5
- package/package.json +21 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,39 @@
|
|
|
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
|
+
|
|
20
|
+
## 0.1.0
|
|
21
|
+
|
|
22
|
+
- Implement `SeekService` and provide it as the `ctx.evidence` host seam with
|
|
23
|
+
`registerProvider`, `unregisterProvider`, `providers` and `search`.
|
|
24
|
+
- Fan a query out to selected providers in parallel; a rejected or malformed
|
|
25
|
+
provider only adds an entry to `errors` and never fails the whole query.
|
|
26
|
+
- Validate `dsh://<source>/<id>` refs, normalize hits to
|
|
27
|
+
`{ ref, source, title, snippet, score?, freshness? }`, and drop invalid or
|
|
28
|
+
ref/source-mismatched hits with an `invalid_hit` error.
|
|
29
|
+
- Deduplicate by `ref` (highest score wins), sort by score descending then
|
|
30
|
+
source, and apply the caller's limit after merging.
|
|
31
|
+
- Add plain-object `seek_search` and `seek_providers` agent tools.
|
|
32
|
+
- 0.1.0 is the provider protocol MVP only: locator, library, memento and web
|
|
33
|
+
adapters, `seek_resolve`, permissions, caching and timeouts are 0.2.0 work.
|
|
34
|
+
- Add `node --test` coverage for fan-out, filtering, deduplication, ordering,
|
|
35
|
+
ref validation, registration and provider failure isolation.
|
|
36
|
+
|
|
3
37
|
## 0.0.1
|
|
4
38
|
|
|
5
39
|
- 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
|
|
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.
|
|
6
|
-
|
|
6
|
+
**Status: 0.1.1 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.x.
|
|
7
12
|
|
|
8
13
|
**Not affiliated with DeepSeek.** DeepSeek and DeepSeek Harness are trademarks
|
|
9
14
|
of their respective owners.
|
|
@@ -14,8 +19,130 @@ of their respective owners.
|
|
|
14
19
|
dsh plugin --profile web add dsh-seek
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
The bundle patch mounts the plugin and provides `ctx.evidence`.
|
|
18
23
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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, signal, timeoutMs }) {
|
|
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, 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.
|
|
65
|
+
- If a hit supplies `source`, it must equal the source inside its ref.
|
|
66
|
+
Otherwise the hit is dropped.
|
|
67
|
+
|
|
68
|
+
Invalid or mismatched hits are omitted from the result and reported as one
|
|
69
|
+
`invalid_hit` error per provider; they never poison the rest of the query.
|
|
70
|
+
|
|
71
|
+
### Search semantics
|
|
72
|
+
|
|
73
|
+
`evidence.search(query, { sources, limit, timeoutMs, signal })`:
|
|
74
|
+
|
|
75
|
+
- Requires a non-empty string query (trimmed); `limit` is a positive integer,
|
|
76
|
+
default 10, capped at 100.
|
|
77
|
+
- `sources` selects providers by name; unknown names are ignored, and an empty
|
|
78
|
+
array returns an empty result without calling any provider.
|
|
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`.
|
|
92
|
+
- Merges hits by `ref`, keeping the highest `score` (missing score sorts as 0).
|
|
93
|
+
- Sorts by `score` descending, then by `source` ascending.
|
|
94
|
+
- Applies `limit` after deduplication and sorting; `total` is the number of
|
|
95
|
+
returned 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.
|
|
98
|
+
|
|
99
|
+
## Agent tools
|
|
100
|
+
|
|
101
|
+
| Tool | Arguments | Result |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| `seek_search` | `query` (required), `sources?`, `limit?` | `{ query, hits, total, errors }`; forwards `exec.signal` |
|
|
104
|
+
| `seek_providers` | none | `{ providers: string[] }` |
|
|
105
|
+
|
|
106
|
+
Both are plain-object tools (no `@deepseek-ai/dsh-tools` dependency) and return
|
|
107
|
+
lossless JSON through the host tool pipeline.
|
|
108
|
+
|
|
109
|
+
## Errors
|
|
110
|
+
|
|
111
|
+
Expected failures throw an `Error` with a stable `code`:
|
|
112
|
+
`invalid_provider`, `provider_exists`, `invalid_query`, `invalid_limit`,
|
|
113
|
+
`invalid_options`, `invalid_sources`, `invalid_timeout`, `invalid_signal` and
|
|
114
|
+
`aborted`.
|
|
115
|
+
|
|
116
|
+
Per-query provider problems are returned, not thrown:
|
|
117
|
+
|
|
118
|
+
```js
|
|
119
|
+
{
|
|
120
|
+
source: 'notes',
|
|
121
|
+
code: 'provider_failed', // or 'provider_timeout', 'invalid_hit'
|
|
122
|
+
message: 'boom',
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Limits of 0.1.x
|
|
127
|
+
|
|
128
|
+
- No first-party providers: registering locator/library/memento/web adapters is
|
|
129
|
+
the 0.2.0 milestone.
|
|
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.
|
|
133
|
+
- No network I/O and no writes to provider data. Seek only reads.
|
|
134
|
+
- Provider callers should still apply their own ACLs before returning hits;
|
|
135
|
+
Seek does not expose a permission model in this release.
|
|
136
|
+
|
|
137
|
+
## Development
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
cd packages/seek
|
|
141
|
+
node --test
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Pure ESM JavaScript, Node 22+, no runtime dependencies and no build step.
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
MIT. See [LICENSE](./LICENSE).
|
package/index.js
CHANGED
|
@@ -1,13 +1,327 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* dsh-seek —
|
|
2
|
+
* dsh-seek — cross-source evidence search for DeepSeek Harness.
|
|
3
3
|
*
|
|
4
|
-
* 0.0
|
|
5
|
-
*
|
|
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
|
-
/**
|
|
13
|
-
export
|
|
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
|
+
/** 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
|
|
23
|
+
|
|
24
|
+
/** Provider names use the same token grammar as the `<source>` ref segment. */
|
|
25
|
+
const SOURCE_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/
|
|
26
|
+
|
|
27
|
+
/** `dsh://<source>/<id>`, where id is one or more non-empty path segments. */
|
|
28
|
+
const REF_PATTERN = /^dsh:\/\/([a-z][a-z0-9._-]{0,63})\/([^\s/?#]+(?:\/[^\s/?#]+)*)$/
|
|
29
|
+
|
|
30
|
+
function fail(code, message) {
|
|
31
|
+
return Object.assign(new Error(message), { code })
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function plainObject(value) {
|
|
35
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function messageOf(error) {
|
|
39
|
+
if (error instanceof Error) return error.message
|
|
40
|
+
if (plainObject(error) && typeof error.message === 'string') return error.message
|
|
41
|
+
return String(error)
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Parse and validate a `dsh://<source>/<id>` ref. Empty, overlong, malformed
|
|
46
|
+
* and dot-segment (`..`) ids are rejected.
|
|
47
|
+
* @param {unknown} ref
|
|
48
|
+
* @returns {{ source: string, id: string } | undefined}
|
|
49
|
+
*/
|
|
50
|
+
export function parseRef(ref) {
|
|
51
|
+
if (typeof ref !== 'string' || ref.length === 0 || ref.length > MAX_REF_LENGTH) return undefined
|
|
52
|
+
const match = REF_PATTERN.exec(ref)
|
|
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] }
|
|
56
|
+
}
|
|
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
|
+
|
|
78
|
+
/** Normalize the caller's limit; invalid explicit values fail closed. */
|
|
79
|
+
function limitOf(value) {
|
|
80
|
+
if (value === undefined) return DEFAULT_LIMIT
|
|
81
|
+
if (!Number.isInteger(value) || value < 1) {
|
|
82
|
+
throw fail('invalid_limit', 'seek: limit must be a positive integer')
|
|
83
|
+
}
|
|
84
|
+
return Math.min(value, MAX_LIMIT)
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Validate one provider hit and reduce it to the documented shape. Invalid
|
|
89
|
+
* refs and ref/source mismatches are dropped by the caller and reported.
|
|
90
|
+
*/
|
|
91
|
+
function normalizeHit(value) {
|
|
92
|
+
if (!plainObject(value)) return undefined
|
|
93
|
+
const parsed = parseRef(value.ref)
|
|
94
|
+
if (parsed === undefined) return undefined
|
|
95
|
+
if (value.source !== undefined && value.source !== parsed.source) return undefined
|
|
96
|
+
|
|
97
|
+
const hit = {
|
|
98
|
+
ref: value.ref,
|
|
99
|
+
source: parsed.source,
|
|
100
|
+
title: typeof value.title === 'string' ? value.title : '',
|
|
101
|
+
snippet: typeof value.snippet === 'string' ? value.snippet : '',
|
|
102
|
+
}
|
|
103
|
+
if (typeof value.score === 'number' && Number.isFinite(value.score)) hit.score = value.score
|
|
104
|
+
if (value.freshness !== undefined) hit.freshness = value.freshness
|
|
105
|
+
return hit
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Missing scores sort as zero. */
|
|
109
|
+
function scoreOf(hit) {
|
|
110
|
+
return hit.score ?? 0
|
|
111
|
+
}
|
|
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
|
+
|
|
131
|
+
/** Named provider registry and fan-out search exposed to plugins as `ctx.evidence`. */
|
|
132
|
+
export class SeekService {
|
|
133
|
+
#providers = new Map()
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Register `{ name, search(query, opts) }`. Returns a disposer.
|
|
137
|
+
* @throws {Error} `invalid_provider` or `provider_exists`.
|
|
138
|
+
*/
|
|
139
|
+
registerProvider(provider) {
|
|
140
|
+
if (!plainObject(provider)) {
|
|
141
|
+
throw fail('invalid_provider', 'seek: provider must be an object')
|
|
142
|
+
}
|
|
143
|
+
if (typeof provider.name !== 'string' || !SOURCE_PATTERN.test(provider.name)) {
|
|
144
|
+
throw fail('invalid_provider', `seek: invalid provider name: ${String(provider.name)}`)
|
|
145
|
+
}
|
|
146
|
+
if (typeof provider.search !== 'function') {
|
|
147
|
+
throw fail('invalid_provider', `seek: provider "${provider.name}" requires a search function`)
|
|
148
|
+
}
|
|
149
|
+
if (this.#providers.has(provider.name)) {
|
|
150
|
+
throw fail('provider_exists', `seek: provider "${provider.name}" is already registered`)
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
const entry = Object.freeze({ name: provider.name, search: provider.search.bind(provider) })
|
|
154
|
+
this.#providers.set(entry.name, entry)
|
|
155
|
+
return () => (this.#providers.get(entry.name) === entry ? this.#providers.delete(entry.name) : false)
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** Remove a provider by name; true when it existed. */
|
|
159
|
+
unregisterProvider(name) {
|
|
160
|
+
return this.#providers.delete(name)
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** Registered provider names, in registration order. */
|
|
164
|
+
providers() {
|
|
165
|
+
return [...this.#providers.keys()]
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Query selected providers in parallel.
|
|
170
|
+
*
|
|
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`.
|
|
178
|
+
*
|
|
179
|
+
* @param {string} query
|
|
180
|
+
* @param {{ sources?: string[], limit?: number, timeoutMs?: number, signal?: AbortSignal }} [options]
|
|
181
|
+
* @returns {Promise<{ query: string, hits: object[], total: number, errors: object[] }>}
|
|
182
|
+
*/
|
|
183
|
+
async search(query, options = {}) {
|
|
184
|
+
if (typeof query !== 'string' || query.trim() === '') {
|
|
185
|
+
throw fail('invalid_query', 'seek: query must be a non-empty string')
|
|
186
|
+
}
|
|
187
|
+
if (!plainObject(options)) {
|
|
188
|
+
throw fail('invalid_options', 'seek: options must be an object')
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const text = query.trim()
|
|
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()
|
|
196
|
+
const selected = this.#select(options.sources)
|
|
197
|
+
const settled = await Promise.allSettled(
|
|
198
|
+
selected.map(provider => askProvider(provider, text, { limit, timeoutMs, signal })),
|
|
199
|
+
)
|
|
200
|
+
if (signal !== undefined && signal.aborted) throw abortedError()
|
|
201
|
+
|
|
202
|
+
const errors = []
|
|
203
|
+
const byRef = new Map()
|
|
204
|
+
settled.forEach((outcome, index) => {
|
|
205
|
+
const source = selected[index].name
|
|
206
|
+
if (outcome.status === 'rejected') {
|
|
207
|
+
errors.push({
|
|
208
|
+
source,
|
|
209
|
+
code: outcome.reason?.code === 'provider_timeout' ? 'provider_timeout' : 'provider_failed',
|
|
210
|
+
message: messageOf(outcome.reason),
|
|
211
|
+
})
|
|
212
|
+
return
|
|
213
|
+
}
|
|
214
|
+
if (!Array.isArray(outcome.value)) {
|
|
215
|
+
errors.push({
|
|
216
|
+
source,
|
|
217
|
+
code: 'provider_failed',
|
|
218
|
+
message: 'provider must return an array of hits',
|
|
219
|
+
})
|
|
220
|
+
return
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
let invalid = 0
|
|
224
|
+
for (const raw of outcome.value) {
|
|
225
|
+
const hit = normalizeHit(raw)
|
|
226
|
+
if (hit === undefined) {
|
|
227
|
+
invalid += 1
|
|
228
|
+
continue
|
|
229
|
+
}
|
|
230
|
+
const current = byRef.get(hit.ref)
|
|
231
|
+
if (current === undefined || scoreOf(hit) > scoreOf(current)) byRef.set(hit.ref, hit)
|
|
232
|
+
}
|
|
233
|
+
if (invalid > 0) {
|
|
234
|
+
errors.push({
|
|
235
|
+
source,
|
|
236
|
+
code: 'invalid_hit',
|
|
237
|
+
message: `${invalid} hit(s) omitted: refs must use dsh://<source>/<id> (at most ${MAX_REF_LENGTH} characters) and match hit.source`,
|
|
238
|
+
})
|
|
239
|
+
}
|
|
240
|
+
})
|
|
241
|
+
|
|
242
|
+
const hits = [...byRef.values()].sort((a, b) => scoreOf(b) - scoreOf(a)
|
|
243
|
+
|| (a.source < b.source ? -1 : a.source > b.source ? 1 : 0))
|
|
244
|
+
if (hits.length > limit) hits.length = limit
|
|
245
|
+
return { query: text, hits, total: hits.length, errors }
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** Snapshot the providers selected by `sources` (all when omitted). */
|
|
249
|
+
#select(sources) {
|
|
250
|
+
const providers = [...this.#providers.values()]
|
|
251
|
+
if (sources === undefined) return providers
|
|
252
|
+
if (!Array.isArray(sources) || sources.some(source => typeof source !== 'string')) {
|
|
253
|
+
throw fail('invalid_sources', 'seek: sources must be an array of provider names')
|
|
254
|
+
}
|
|
255
|
+
const wanted = new Set(sources)
|
|
256
|
+
return providers.filter(provider => wanted.has(provider.name))
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** Build a plain-object tool definition accepted by the host. */
|
|
261
|
+
function tool(name, description, parameters, execute) {
|
|
262
|
+
return {
|
|
263
|
+
name,
|
|
264
|
+
description,
|
|
265
|
+
parameters,
|
|
266
|
+
output: {
|
|
267
|
+
schema: { type: 'object', additionalProperties: true },
|
|
268
|
+
render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
|
|
269
|
+
},
|
|
270
|
+
execute,
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** `seek_search` tool: one query across all or selected providers. */
|
|
275
|
+
function searchTool(service) {
|
|
276
|
+
return tool(
|
|
277
|
+
'seek_search',
|
|
278
|
+
'Search registered evidence providers and return deduplicated hits with dsh:// refs and per-provider errors.',
|
|
279
|
+
{
|
|
280
|
+
type: 'object',
|
|
281
|
+
additionalProperties: false,
|
|
282
|
+
required: ['query'],
|
|
283
|
+
properties: {
|
|
284
|
+
query: { type: 'string', description: 'Text to search for.' },
|
|
285
|
+
sources: {
|
|
286
|
+
type: 'array',
|
|
287
|
+
items: { type: 'string' },
|
|
288
|
+
description: 'Provider names to query; defaults to every registered provider.',
|
|
289
|
+
},
|
|
290
|
+
limit: {
|
|
291
|
+
type: 'integer',
|
|
292
|
+
minimum: 1,
|
|
293
|
+
maximum: MAX_LIMIT,
|
|
294
|
+
description: 'Maximum hits to return (default 10).',
|
|
295
|
+
},
|
|
296
|
+
},
|
|
297
|
+
},
|
|
298
|
+
async (args, exec) => service.search(args?.query, {
|
|
299
|
+
sources: args?.sources,
|
|
300
|
+
limit: args?.limit,
|
|
301
|
+
signal: exec?.signal,
|
|
302
|
+
}),
|
|
303
|
+
)
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
/** `seek_providers` tool: provider discovery for agents. */
|
|
307
|
+
function providersTool(service) {
|
|
308
|
+
return tool(
|
|
309
|
+
'seek_providers',
|
|
310
|
+
'List the names of registered Seek evidence providers.',
|
|
311
|
+
{ type: 'object', additionalProperties: false, properties: {} },
|
|
312
|
+
async () => ({ providers: service.providers() }),
|
|
313
|
+
)
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* Mount dsh-seek: provide `ctx.evidence` and register the two agent tools.
|
|
318
|
+
* @param {object} ctx - Cordis context with `provide` and `tools.register`.
|
|
319
|
+
* @param {object} [_config] - Reserved for 0.2.0; unused by the MVP.
|
|
320
|
+
*/
|
|
321
|
+
export function apply(ctx, _config = {}) {
|
|
322
|
+
const service = new SeekService()
|
|
323
|
+
ctx.provide('evidence', service)
|
|
324
|
+
ctx.tools.register(searchTool(service))
|
|
325
|
+
ctx.tools.register(providersTool(service))
|
|
326
|
+
return service
|
|
327
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-seek",
|
|
3
|
-
"version": "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,15 +34,33 @@
|
|
|
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/"
|
|
62
|
+
},
|
|
63
|
+
"scripts": {
|
|
64
|
+
"test": "node --test"
|
|
47
65
|
}
|
|
48
66
|
}
|