dsh-web-search-workbuddy 0.0.0-stage → 0.2.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/README.md CHANGED
@@ -1,3 +1,114 @@
1
- # Temporary Holding Version
1
+ # dsh-web-search-workbuddy
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
+ WorkBuddy gateway-backed search provider for the DeepSeek Harness web capability
4
+ seam (`ctx.web`). Bridges the model-facing `web_search` tool to the
5
+ workbuddy2api-go gateway's agenttool web-search passthrough, with
6
+ [workbuddy-manager](https://github.com/WaveBird/workbuddy-manager) as the
7
+ entry proxy — so **one `wbk_` key serves both the chat route and `web_search`**.
8
+
9
+ ```
10
+ DSH session ── ctx.web.search() ──▶ this provider
11
+ │ POST {manager}:7864/v1/tools/search (wbk_ key)
12
+ ▼
13
+ workbuddy-manager (auth + upstream resolve + logging)
14
+ │ POST {wb2api-go}:7863/v1/tools/search
15
+ ▼
16
+ wb2api-go (account-pool rotation + 15001 quota cooldown)
17
+ ▼
18
+ https://www.workbuddy.cn/agenttool/v1/search
19
+ ```
20
+
21
+ ## ⚠️ Compatibility requirements(兼容性要求)
22
+
23
+ This plugin is **not standalone**. It depends on a specific feature set that
24
+ landed in the WorkBuddy ecosystem at pinned versions; running against an
25
+ unpatched stack fails with `404` (route missing) or `401` (search endpoint
26
+ expecting the gateway key):
27
+
28
+ | Component | Required version / state | Why |
29
+ |---|---|---|
30
+ | **workbuddy-manager** | **≥ the `feat/web-search-passthrough` branch** ([PR #2](https://github.com/WaveBird/workbuddy-manager/pull/2)). Baseline tested: `v2.11.14` + the PR's 3 commits (`dce9acc` route, `5e88629` realm fix, `c33e122` docs). It will ship in a release **after v2.11.14** — until then, deploy the branch or cherry-pick. | The `POST /v1/tools/search` passthrough route **does not exist** in upstream releases ≤ v2.11.14. Older managers return `405` and this provider cannot work through them. |
31
+ | **workbuddy2api-go gateway** | Built from the upstream snapshot **`upstream-id 801cebba` (v2.11.14 / 0056 patches)** plus [`0057-web-search-tool.patch`](https://github.com/WaveBird/workbuddy-manager/blob/feat/web-search-passthrough/dev/upstream-patches/0057-web-search-tool.patch) (shipped inside the manager PR above). | The `POST /v1/tools/search` handler, account-pool rotation, and 15001 quota cooldown live in this patch; the stock gateway has no agenttool route. |
32
+ | **DeepSeek Harness (DSH)** | `0.2.2-rc.2` (web seam contract `ctx.web.registerSearchProvider` / `WebSearchProvider` shape). Tested against `0.2.2-rc.1` and `rc.2`; any version keeping that seam shape works. | The provider registers into `ctx.web`; a breaking seam change would require a plugin update. |
33
+
34
+ Quick self-check per component:
35
+
36
+ ```bash
37
+ # manager: route exists and accepts the wbk_ key (405/401 → wrong manager version)
38
+ curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:7864/v1/tools/search \
39
+ -H "Authorization: Bearer <wbk_ key>" -H 'content-type: application/json' \
40
+ -d '{"query":"ping"}'
41
+
42
+ # gateway (bypassing manager): 401 with the gateway's own api_key configured means alive
43
+ curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:7863/v1/tools/search \
44
+ -H 'content-type: application/json' -d '{"query":"ping"}'
45
+ ```
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ npm install dsh-web-search-workbuddy
51
+ # or inside the DSH profile (recommended):
52
+ cd ~/.dsh/profiles/web && pnpm add dsh-web-search-workbuddy
53
+ ```
54
+
55
+ Peer dependencies (`@deepseek-ai/dsh-web`, `@deepseek-ai/dsh-credentials`,
56
+ `@deepseek-ai/cordis`) resolve from the DSH profile's own `node_modules` when
57
+ installed this way; `@deepseek-ai/schemastery` ships as a direct dependency.
58
+
59
+ ## DSH profile assembly
60
+
61
+ ```yaml
62
+ # ~/.dsh/profiles/web/cordis.patch.yml
63
+ - insert:
64
+ - id: web-search-workbuddy
65
+ name: dsh-web-search-workbuddy
66
+ config:
67
+ baseURL: http://127.0.0.1:7864 # workbuddy-manager address
68
+ apiKeyEnv: WORKBUDDY_MANNAGER_CN_API_KEY # same wbk_ key as the chat route
69
+ timeoutMs: 30000
70
+ maxResults: 5
71
+ - id: web
72
+ name: '@deepseek-ai/dsh-web'
73
+ config:
74
+ fetchProvider: http
75
+ searchProvider: workbuddy-gateway # ← pin this provider
76
+ - id: tool-web
77
+ name: '@deepseek-ai/dsh-tool-web'
78
+ config: { fetch: true, search: true, searchTimeoutMs: 60000 }
79
+ # also set search: true in every agent preset's tool-web entry
80
+ ```
81
+
82
+ Fully restart `dsh web` afterwards (patch changes do not HMR). The model's tool
83
+ catalog gains `web_search` in new sessions.
84
+
85
+ ## Protocol
86
+
87
+ ```json
88
+ POST {baseURL}/v1/tools/search
89
+ Authorization: Bearer <wbk_ key>
90
+ { "query": "...", "max_results": 5, "blocked_domains": [...], "freshness": "d1|m1|y1" }
91
+ ```
92
+
93
+ Response is the upstream agenttool envelope passed through verbatim:
94
+
95
+ ```json
96
+ { "code": 0, "msg": "", "results": [{ "title": "...", "url": "...", "snippet": "..." }],
97
+ "total_results": 3, "response_time_ms": 616, "provider": "1" }
98
+ ```
99
+
100
+ This provider maps it to the seam's normalized result (`{url,title,snippet,summary}`
101
+ sources; url-scheme filter + dedupe; `maxResults` truncation owned by the seam).
102
+
103
+ ## Error vocabulary
104
+
105
+ | Situation | WebError code |
106
+ |---|---|
107
+ | No gateway key configured | `WEB_PROVIDER_CREDENTIAL_MISSING` |
108
+ | Manager unreachable / non-2xx / upstream business code ≠ 0 | `WEB_PROVIDER_ERROR` |
109
+ | All-pool search quota exhausted (15001, gateway 429 `quota_web_search`) | `WEB_PROVIDER_ERROR` (message says quota) |
110
+ | Caller cancellation | `WEB_ABORTED` |
111
+
112
+ ## License
113
+
114
+ MIT — see the upstream projects' licenses for their respective code.
package/lib/index.js ADDED
@@ -0,0 +1,192 @@
1
+ /**
2
+ * dsh-web-search-workbuddy
3
+ *
4
+ * WorkBuddy gateway-backed search provider for the DSH web capability seam
5
+ * (ctx.web). Bridges `ctx.web.search()` to the workbuddy2api-go gateway's
6
+ * agenttool web-search passthrough endpoint (0057 patch):
7
+ *
8
+ * POST {baseURL}/v1/tools/search
9
+ * body: {"query": "...", "max_results": 5, "blocked_domains": [...], "freshness": "d1|m1|y1"}
10
+ * resp: {"code":0, "results":[{title,url,snippet}], ...} (agenttool envelope passthrough)
11
+ * or {"error":"...", "code":"quota_web_search", ...} on 429 (all-pool 15001)
12
+ *
13
+ * Provider id registers as "workbuddy-gateway"; pin it with
14
+ * `web.searchProvider: workbuddy-gateway` in the profile patch.
15
+ */
16
+ import z from "@deepseek-ai/schemastery";
17
+ import { credentialRef } from "@deepseek-ai/dsh-credentials";
18
+ import { WebError } from "@deepseek-ai/dsh-web";
19
+
20
+ /** Stable provider id this plugin registers under. */
21
+ const PROVIDER_ID = "workbuddy-gateway";
22
+
23
+ /** Cordis plugin name used by loader diagnostics. */
24
+ const name = "web-search-workbuddy";
25
+
26
+ /** The web seam this provider registers into. */
27
+ const inject = ["web"];
28
+
29
+ const Config = z.object({
30
+ /** Gateway base (manager reverse-proxy or the wb2api-go port directly). */
31
+ baseURL: z.string().default("http://127.0.0.1:7864").volatile(),
32
+ /** Credential reference holding the gateway API key. */
33
+ apiKeyEnv: z.string().role("credential-ref").default("WORKBUDDY_MANNAGER_CN_API_KEY").volatile(),
34
+ /** Single-request timeout; the gateway itself bounds upstream at 20s/account. */
35
+ timeoutMs: z.number().step(1).min(1000).default(30000).volatile(),
36
+ /** Default max_results when the request omits maxResults. */
37
+ maxResults: z.number().step(1).min(1).max(20).default(5).volatile(),
38
+ });
39
+
40
+ /**
41
+ * Resolve the gateway API key for one search: credentials service first,
42
+ * launch environment fallback. Undefined when neither holds a value.
43
+ */
44
+ async function resolveApiKey(ctx, options) {
45
+ const credentials = ctx.get("credentials");
46
+ if (credentials !== undefined) {
47
+ const value = (await credentials.resolve(credentialRef(options.apiKeyEnv)))?.value;
48
+ if (value !== undefined && value.length > 0) return value;
49
+ }
50
+ const ambient = process.env[options.apiKeyEnv];
51
+ return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
52
+ }
53
+
54
+ /**
55
+ * Whether a search for a model request has a gateway key to send. Presence
56
+ * only: no network calls, no secret value read beyond existence.
57
+ */
58
+ async function searchConfigured(ctx, options) {
59
+ const credentials = ctx.get("credentials");
60
+ if (credentials !== undefined) {
61
+ try {
62
+ const described = await credentials.describe(credentialRef(options.apiKeyEnv));
63
+ if (described?.configured === true) return true;
64
+ } catch (_unreadableStore) {
65
+ // fall through to the environment check
66
+ }
67
+ }
68
+ const ambient = process.env[options.apiKeyEnv];
69
+ return ambient !== undefined && ambient.length > 0;
70
+ }
71
+
72
+ /** Map the agenttool envelope to the seam's normalized result. */
73
+ function mapResponse(data) {
74
+ const results = Array.isArray(data?.results) ? data.results : [];
75
+ const sources = [];
76
+ const seen = new Set();
77
+ for (const item of results) {
78
+ const url = String(item?.url ?? "");
79
+ if (!/^https?:\/\//.test(url) || seen.has(url)) continue;
80
+ seen.add(url);
81
+ const snippet = String(item?.snippet ?? "");
82
+ sources.push({
83
+ url,
84
+ ...(item?.title != null && item.title.length > 0 ? { title: String(item.title) } : {}),
85
+ ...(snippet.length > 0
86
+ ? { snippet: snippet.slice(0, 200), summary: snippet.slice(0, 1200) }
87
+ : {}),
88
+ });
89
+ }
90
+ return { sources, truncated: false };
91
+ }
92
+
93
+ /** One search against the gateway. Honors `signal` for cancellation. */
94
+ async function search(ctx, options, request, signal) {
95
+ const apiKey = await resolveApiKey(ctx, options);
96
+ if (apiKey === undefined) {
97
+ throw new WebError(
98
+ `WorkBuddy gateway search has no API key for "${options.apiKeyEnv}"; store it through the credentials service or export it in the launching environment`,
99
+ "WEB_PROVIDER_CREDENTIAL_MISSING",
100
+ );
101
+ }
102
+
103
+ let response;
104
+ try {
105
+ response = await fetch(`${options.baseURL}/v1/tools/search`, {
106
+ method: "POST",
107
+ redirect: "error",
108
+ headers: {
109
+ "content-type": "application/json",
110
+ authorization: `Bearer ${apiKey}`,
111
+ },
112
+ body: JSON.stringify({
113
+ query: request.query,
114
+ max_results: request.maxResults ?? options.maxResults,
115
+ }),
116
+ ...(signal !== undefined ? { signal } : {}),
117
+ });
118
+ } catch (error) {
119
+ if (signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError")) {
120
+ throw new WebError("WorkBuddy gateway search aborted", "WEB_ABORTED", { cause: signal?.reason ?? error });
121
+ }
122
+ throw new WebError(
123
+ `WorkBuddy gateway search request failed: ${String(error)}\n\nThe web request used endpoint ${JSON.stringify(`${options.baseURL}/v1/tools/search`)}. Check that the workbuddy2api gateway (0057 patch build) is running and that web-search-workbuddy.baseURL points at it.`,
124
+ "WEB_PROVIDER_ERROR",
125
+ { cause: error },
126
+ );
127
+ }
128
+
129
+ if (!response.ok) {
130
+ let detail = "";
131
+ let quotaExhausted = false;
132
+ try {
133
+ const parsed = await response.json();
134
+ detail = typeof parsed?.error === "string" ? parsed.error : (parsed?.error?.message ?? parsed?.msg ?? "");
135
+ quotaExhausted = parsed?.code === "quota_web_search";
136
+ } catch (_unparseable) {
137
+ // keep empty detail
138
+ }
139
+ if (quotaExhausted) {
140
+ throw new WebError(
141
+ `WorkBuddy web search quota exhausted on all pool accounts (upstream 15001); quota resets daily`,
142
+ "WEB_PROVIDER_ERROR",
143
+ );
144
+ }
145
+ throw new WebError(
146
+ `WorkBuddy gateway search failed (HTTP ${response.status})${detail.length > 0 ? `: ${detail}` : ""}\n\nThe web request used endpoint ${JSON.stringify(`${options.baseURL}/v1/tools/search`)}.`,
147
+ "WEB_PROVIDER_ERROR",
148
+ );
149
+ }
150
+
151
+ let data;
152
+ try {
153
+ data = await response.json();
154
+ } catch (error) {
155
+ if (signal?.aborted === true) throw new WebError("WorkBuddy gateway search aborted", "WEB_ABORTED", { cause: signal.reason });
156
+ throw new WebError(`WorkBuddy gateway returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
157
+ }
158
+
159
+ // agenttool business envelope: code != 0 is an upstream business failure
160
+ // even on HTTP 200 (the gateway passes non-15001 codes through verbatim).
161
+ if (data?.code !== undefined && data.code !== 0) {
162
+ throw new WebError(
163
+ `WorkBuddy search upstream code ${data.code}: ${data.msg ?? ""}`,
164
+ "WEB_PROVIDER_ERROR",
165
+ );
166
+ }
167
+
168
+ return mapResponse(data);
169
+ }
170
+
171
+ /**
172
+ * Register the gateway-backed search provider with ctx.web. `ready()` answers
173
+ * whether a search has a gateway key configured (tool-web uses this to decide
174
+ * whether the model step admits `web_search`).
175
+ */
176
+ function apply(ctx, config) {
177
+ const options = () => ({
178
+ baseURL: config.baseURL.get().replace(/\/+$/, ""),
179
+ apiKeyEnv: config.apiKeyEnv.get(),
180
+ timeoutMs: config.timeoutMs.get(),
181
+ maxResults: config.maxResults.get(),
182
+ });
183
+
184
+ ctx.web.registerSearchProvider({
185
+ id: PROVIDER_ID,
186
+ available: () => URL.canParse(options().baseURL),
187
+ ready: (async () => searchConfigured(ctx, options())),
188
+ search: (request, signal) => search(ctx, options(), request, signal),
189
+ });
190
+ }
191
+
192
+ export { Config, PROVIDER_ID, apply, inject, name };
@@ -0,0 +1,20 @@
1
+ /**
2
+ * dsh-web-search-workbuddy — WorkBuddy gateway-backed search provider
3
+ * for the DSH web capability seam. See README.md and lib/index.js.
4
+ */
5
+ export interface WebSearchWorkBuddyConfig {
6
+ /** Gateway base (manager reverse-proxy or the wb2api-go port directly). */
7
+ baseURL: string;
8
+ /** Credential reference holding the gateway API key. */
9
+ apiKeyEnv: string;
10
+ /** Single-request timeout in ms. */
11
+ timeoutMs: number;
12
+ /** Default max_results when the search request omits maxResults. */
13
+ maxResults: number;
14
+ }
15
+ /** Stable provider id this plugin registers under. */
16
+ export declare const PROVIDER_ID: "workbuddy-gateway";
17
+ /** Cordis plugin name used by loader diagnostics. */
18
+ export declare const name: "web-search-workbuddy";
19
+ /** The web seam this provider registers into. */
20
+ export declare const inject: readonly ["web"];
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "dsh-web-search-workbuddy",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "description": "WorkBuddy gateway-backed search provider (agenttool /v1/tools/search passthrough via the account-pool gateway) for the DeepSeek Harness web capability seam (ctx.web)",
4
+ "version": "0.2.0",
5
+ "type": "module",
6
+ "main": "lib/index.js",
7
+ "types": "lib/types/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./lib/types/index.d.ts",
11
+ "default": "./lib/index.js"
12
+ },
13
+ "./package.json": "./package.json",
14
+ "./README.md": "./README.md"
15
+ },
16
+ "files": [
17
+ "lib/index.js",
18
+ "lib/types/**/*.d.ts",
19
+ "README.md"
20
+ ],
21
+ "license": "MIT",
22
+ "dependencies": {
23
+ "@deepseek-ai/schemastery": "~3.19.0"
24
+ },
25
+ "peerDependencies": {
26
+ "@deepseek-ai/dsh-web": "0.2.2-rc.2",
27
+ "@deepseek-ai/dsh-credentials": "0.2.2-rc.2",
28
+ "@deepseek-ai/cordis": "~4.1.0"
29
+ },
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/WaveBird/dsh-web-search-workbuddy.git"
33
+ },
34
+ "keywords": [
35
+ "deepseek-harness",
36
+ "dsh",
37
+ "dsh-plugin",
38
+ "web-search",
39
+ "workbuddy",
40
+ "codebuddy",
41
+ "search-provider"
42
+ ],
43
+ "engines": {
44
+ "node": ">=20"
45
+ },
46
+ "scripts": {
47
+ "test": "node test/run.mjs"
48
+ }
49
+ }