dsh-skill-pool 0.0.0-stage → 0.3.7

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/src/mount.js ADDED
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Mount primitives shared by the panel API and boot-time re-mounting.
3
+ *
4
+ * One MCP mount is: create or update the managed `mcp-client` Loader row, then
5
+ * wait until that server's public `mcp__<server>__*` tools are registered. The
6
+ * wait is what makes "ready" mean "usable" — a row alone proves nothing, an
7
+ * unreachable server creates a row and never connects.
8
+ *
9
+ * @module dsh-skill-pool/mount
10
+ */
11
+
12
+ import { serverToolPrefix, upsertMcpServer } from './uploads.js'
13
+
14
+ /** Default readiness window for one MCP mount (§6: 20s). */
15
+ export const DEFAULT_PROBE_TIMEOUT_MS = 20_000
16
+
17
+ /** Default readiness polling interval. */
18
+ export const DEFAULT_PROBE_INTERVAL_MS = 500
19
+
20
+ /**
21
+ * Whether at least one of the server's public tools is registered right now.
22
+ * @param {object} ctx - plugin context.
23
+ * @param {string} serverName - pool server name.
24
+ * @returns {boolean} true when the server exposed at least one tool.
25
+ */
26
+ export function hasServerTools(ctx, serverName) {
27
+ const tools = ctx.get('tools')
28
+ if (tools === undefined || typeof tools.schemas !== 'function') return false
29
+ const prefix = serverToolPrefix(serverName)
30
+ if (prefix.length === 0) return false
31
+ try {
32
+ return tools.schemas().some((schema) => typeof schema?.name === 'string' && schema.name.startsWith(prefix))
33
+ } catch {
34
+ return false
35
+ }
36
+ }
37
+
38
+ /**
39
+ * Mount one server in the background, tracking progress for the panel.
40
+ *
41
+ * The row is created/updated synchronously-ish (awaited inside the tracked
42
+ * run); readiness is polled until the window expires. Failure is reported, not
43
+ * thrown, so one dead server never blocks another.
44
+ *
45
+ * @param {object} options - mount options.
46
+ * @param {object} options.ctx - plugin context.
47
+ * @param {string} options.serverName - pool server name.
48
+ * @param {object} options.definition - stored connection definition.
49
+ * @param {{start: Function}} options.mounts - mount tracker.
50
+ * @param {number} [options.timeoutMs] - readiness window.
51
+ * @param {number} [options.intervalMs] - polling interval.
52
+ * @param {{info?: Function, warn?: Function}} [options.logger] - logger.
53
+ * @param {string} [options.origin] - `import` | `boot`, for the log line.
54
+ * @returns {void}
55
+ */
56
+ export function mountServer({ ctx, serverName, definition, mounts, timeoutMs, intervalMs, logger, origin = 'import' }) {
57
+ const waitMs = Number.isFinite(timeoutMs) ? timeoutMs : DEFAULT_PROBE_TIMEOUT_MS
58
+ const everyMs = Number.isFinite(intervalMs) ? intervalMs : DEFAULT_PROBE_INTERVAL_MS
59
+ mounts.start(serverName, async () => {
60
+ await upsertMcpServer(ctx, serverName, definition)
61
+ const deadline = Date.now() + waitMs
62
+ while (Date.now() < deadline) {
63
+ if (hasServerTools(ctx, serverName)) {
64
+ logger?.info?.(`[skill-pool] MCP server ready (${origin}): ${serverName}`)
65
+ return
66
+ }
67
+ await new Promise((resolve) => setTimeout(resolve, everyMs))
68
+ }
69
+ throw new Error(
70
+ `已创建连接,但 ${Math.round(waitMs / 1000)}s 内没有观察到该 Server 的工具:请检查 URL/命令、鉴权与服务是否可达`,
71
+ )
72
+ })
73
+ }
@@ -0,0 +1,309 @@
1
+ /**
2
+ * Skill provider for the resource-pool library.
3
+ *
4
+ * The resource pool owns its own directory (`<dshHome>/resource-pool/library/skills`)
5
+ * instead of sharing `$DSH_HOME/skills`, so imported resources never mix with
6
+ * hand-written or packaged skills. Owning the directory means owning the supply:
7
+ * this provider is what makes those skills visible.
8
+ *
9
+ * It is registered **per Agent** (`agent.ctx.skills.registerProvider`), which is
10
+ * what implements the pool's conditions. `SkillRegistry.registerProvider` files
11
+ * a provider into the layer of the calling context's scope, and an Agent's scope
12
+ * key is the Agent object itself, so an Agent sees exactly the skills its own
13
+ * registration lists. Strict hiding therefore needs no tool replacement: a skill
14
+ * excluded by the pool simply does not exist in that Agent's catalog and cannot
15
+ * be loaded.
16
+ *
17
+ * @module dsh-skill-pool/provider
18
+ */
19
+
20
+ import { watch } from 'node:fs'
21
+ import { mkdir, readFile, readdir, stat } from 'node:fs/promises'
22
+ import { join } from 'node:path'
23
+
24
+ import { parseSkillDocument } from './library.js'
25
+
26
+ /** Provider name inside the skill registry. */
27
+ export const PROVIDER_NAME = 'resource-pool'
28
+
29
+ /** Precedence inside one layer; irrelevant across layers (the nearest scope wins). */
30
+ const PROVIDER_RANK = 350
31
+
32
+ /** Skill-name grammar shared with the registry. */
33
+ const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
34
+
35
+ /** Coalesce a burst of filesystem events into one invalidation. */
36
+ const WATCH_DEBOUNCE_MS = 120
37
+
38
+ /** Fallback poll period when the platform cannot watch the library directory. */
39
+ const POLL_INTERVAL_MS = 1_000
40
+
41
+ /**
42
+ * Parse a frontmatter boolean with the documented strict grammar.
43
+ *
44
+ * An unrecognized spelling returns `undefined`, which drops the skill rather
45
+ * than silently permitting a surface the author tried to restrict.
46
+ *
47
+ * @param {unknown} value - raw frontmatter value.
48
+ * @returns {boolean|undefined} parsed boolean, or `undefined` when invalid.
49
+ */
50
+ function parseBoolean(value) {
51
+ if (typeof value !== 'string') return undefined
52
+ const text = value.trim().toLowerCase()
53
+ if (['true', 'yes', 'on', '1'].includes(text)) return true
54
+ if (['false', 'no', 'off', '0'].includes(text)) return false
55
+ return undefined
56
+ }
57
+
58
+ /**
59
+ * Build one candidate from a parsed document.
60
+ *
61
+ * @param {object} parsed - `parseSkillDocument` output.
62
+ * @param {string} dirName - directory name, used when frontmatter omits `name`.
63
+ * @param {string} dir - absolute skill directory.
64
+ * @param {string} file - absolute `SKILL.md` path.
65
+ * @returns {object|undefined} candidate, or `undefined` when the skill is invalid.
66
+ */
67
+ function candidateOf(parsed, dirName, dir, file) {
68
+ const declared = typeof parsed.meta.name === 'string' ? parsed.meta.name.trim() : ''
69
+ const name = NAME_PATTERN.test(declared) ? declared : NAME_PATTERN.test(dirName) ? dirName : ''
70
+ if (name.length === 0) return undefined
71
+ const description = typeof parsed.meta.description === 'string' ? parsed.meta.description.trim() : ''
72
+ if (description.length === 0) return undefined
73
+ const noModel = parseBoolean(parsed.meta['disable-model-invocation'])
74
+ const userInvocable = parseBoolean(parsed.meta['user-invocable'])
75
+ if (noModel === undefined && parsed.meta['disable-model-invocation'] !== undefined) return undefined
76
+ if (userInvocable === undefined && parsed.meta['user-invocable'] !== undefined) return undefined
77
+ const whenToUse = typeof parsed.meta.whenToUse === 'string' ? parsed.meta.whenToUse.trim() : ''
78
+ return {
79
+ name,
80
+ description,
81
+ ...(whenToUse.length > 0 ? { whenToUse } : {}),
82
+ invocation: {
83
+ modelInvocable: parsed.meta['disable-model-invocation'] === undefined ? true : noModel !== true,
84
+ userInvocable: parsed.meta['user-invocable'] === undefined ? true : userInvocable !== false,
85
+ },
86
+ source: 'custom',
87
+ provider: PROVIDER_NAME,
88
+ rank: PROVIDER_RANK,
89
+ path: file,
90
+ resourceBase: { kind: 'directory', path: dir },
91
+ locator: { dir, file, name },
92
+ }
93
+ }
94
+
95
+ /**
96
+ * Create the library-backed skill provider.
97
+ *
98
+ * @param {object} options - provider options.
99
+ * @param {string} options.root - absolute library skills root.
100
+ * @param {Iterable<string>} options.allowed - skill names this Agent may see.
101
+ * @param {{ warn?: Function, debug?: Function }} [options.logger] - logger.
102
+ * @param {{ invalidate?: Function }} [options.control] - registration control from
103
+ * `skills.registerProvider`, used to invalidate the registry's catalog cache
104
+ * when the library changes on disk.
105
+ * @returns {{name: string, list: Function, get: Function}} provider.
106
+ */
107
+ export function createLibraryProvider({ root, allowed, logger, control } = {}) {
108
+ const wanted = new Set([...allowed].map((name) => String(name)).filter((name) => NAME_PATTERN.test(name)))
109
+ /** @type {Map<string, {mtimeMs: number, size: number, candidate: object|undefined}>} */
110
+ const cache = new Map()
111
+ const warned = new Set()
112
+
113
+ /**
114
+ * Invalidate the registry's catalog cache when the library changes on disk.
115
+ *
116
+ * This cannot be done from `list()`: once the registry has a cached catalog it
117
+ * stops calling `list()` altogether, so a provider that only notices changes
118
+ * while listing would never notice them at all. The trigger therefore has to
119
+ * come from outside the collection, which is what the watcher below is for.
120
+ */
121
+ let invalidationTimer
122
+ let watcher
123
+ let watcherErrors = 0
124
+ let pollTimer
125
+
126
+ const scheduleInvalidate = () => {
127
+ if (invalidationTimer !== undefined) return
128
+ invalidationTimer = setTimeout(() => {
129
+ invalidationTimer = undefined
130
+ try {
131
+ control?.invalidate?.()
132
+ } catch {
133
+ /* the registration was disposed in the meantime */
134
+ }
135
+ }, WATCH_DEBOUNCE_MS)
136
+ invalidationTimer.unref?.()
137
+ }
138
+
139
+ /** Stop every watcher; also the registration's teardown path. */
140
+ const stopWatching = () => {
141
+ if (invalidationTimer !== undefined) {
142
+ clearTimeout(invalidationTimer)
143
+ invalidationTimer = undefined
144
+ }
145
+ if (pollTimer !== undefined) {
146
+ clearInterval(pollTimer)
147
+ pollTimer = undefined
148
+ }
149
+ if (watcher !== undefined) {
150
+ try {
151
+ watcher.close()
152
+ } catch {
153
+ /* already closed */
154
+ }
155
+ watcher = undefined
156
+ }
157
+ }
158
+
159
+ /** Compare a cheap stat signature of the library; used when watching is unavailable. */
160
+ let polledSignature
161
+ const poll = async () => {
162
+ let entries
163
+ try {
164
+ entries = await readdir(root, { withFileTypes: true })
165
+ } catch {
166
+ return
167
+ }
168
+ const parts = []
169
+ for (const entry of entries) {
170
+ if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
171
+ try {
172
+ const info = await stat(join(root, entry.name, 'SKILL.md'))
173
+ parts.push(`${entry.name}:${info.mtimeMs}:${info.size}`)
174
+ } catch {
175
+ parts.push(`${entry.name}:-`)
176
+ }
177
+ }
178
+ parts.sort()
179
+ const signature = parts.join('|')
180
+ if (polledSignature !== undefined && polledSignature !== signature) scheduleInvalidate()
181
+ polledSignature = signature
182
+ }
183
+
184
+ const startPolling = () => {
185
+ if (pollTimer !== undefined) return
186
+ void poll()
187
+ pollTimer = setInterval(() => void poll(), POLL_INTERVAL_MS)
188
+ pollTimer.unref?.()
189
+ }
190
+
191
+ // Watch the library so an edit made by anyone but this plugin still reaches the
192
+ // catalog. `recursive` covers each skill's own files; the poll is the fallback
193
+ // for platforms or mounts where watching the directory is not supported.
194
+ try {
195
+ watcher = watch(root, { recursive: true, persistent: false }, () => scheduleInvalidate())
196
+ watcher.on('error', () => {
197
+ watcherErrors += 1
198
+ stopWatching()
199
+ if (watcherErrors > 0) startPolling()
200
+ })
201
+ } catch {
202
+ startPolling()
203
+ }
204
+ if (control?.signal !== undefined) {
205
+ if (control.signal.aborted) stopWatching()
206
+ else control.signal.addEventListener('abort', stopWatching, { once: true })
207
+ }
208
+
209
+ /** Read one directory's candidate, reusing the parse while the file is unchanged. */
210
+ const entryOf = async (dirName) => {
211
+ const dir = join(root, dirName)
212
+ const file = join(dir, 'SKILL.md')
213
+ let info
214
+ try {
215
+ info = await stat(file)
216
+ } catch {
217
+ cache.delete(dirName)
218
+ return undefined
219
+ }
220
+ const cached = cache.get(dirName)
221
+ if (cached !== undefined && cached.mtimeMs === info.mtimeMs && cached.size === info.size) return cached.candidate
222
+ let text
223
+ try {
224
+ text = await readFile(file, 'utf8')
225
+ } catch {
226
+ cache.delete(dirName)
227
+ return undefined
228
+ }
229
+ const candidate = candidateOf(parseSkillDocument(text), dirName, dir, file)
230
+ if (candidate === undefined && !warned.has(dirName)) {
231
+ warned.add(dirName)
232
+ logger?.warn?.(`[skill-pool] 跳过技能目录 ${dirName}:name/description 缺失或 invocation 取值非法`)
233
+ }
234
+ cache.set(dirName, { mtimeMs: info.mtimeMs, size: info.size, candidate })
235
+ return candidate
236
+ }
237
+
238
+ return {
239
+ name: PROVIDER_NAME,
240
+
241
+ /**
242
+ * List the allowed library skills for this Agent.
243
+ *
244
+ * Change notification lives in the watcher above, not here: a provider that
245
+ * only reacted while listing would never react, because the registry serves
246
+ * a cached catalog without calling `list()` at all.
247
+ *
248
+ * @returns {Promise<Array<object>>} candidates, sorted by name.
249
+ */
250
+ async list() {
251
+ if (wanted.size === 0) return []
252
+ let entries
253
+ try {
254
+ entries = await readdir(root, { withFileTypes: true })
255
+ } catch {
256
+ return []
257
+ }
258
+ const candidates = []
259
+ for (const entry of entries) {
260
+ if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
261
+ const candidate = await entryOf(entry.name)
262
+ // Filter on the effective name, never the directory name: a bundle may
263
+ // declare a frontmatter name that the pool did not admit.
264
+ if (candidate === undefined || !wanted.has(candidate.name)) continue
265
+ candidates.push(candidate)
266
+ }
267
+ candidates.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
268
+ return candidates
269
+ },
270
+
271
+ /**
272
+ * Load one skill body. The body is re-read on every call so an update needs
273
+ * no cache invalidation protocol.
274
+ *
275
+ * The candidate is re-validated against the file: a bundle may declare a
276
+ * frontmatter name different from the one it was listed under, and a forged
277
+ * candidate must never load a name the pool did not admit.
278
+ *
279
+ * @param {object} candidate - candidate returned by {@link list}.
280
+ * @returns {Promise<object|undefined>} full definition, or `undefined` when gone.
281
+ */
282
+ async get(candidate) {
283
+ const file = candidate?.locator?.file
284
+ if (typeof file !== 'string' || !wanted.has(candidate.name)) return undefined
285
+ let text
286
+ try {
287
+ text = await readFile(file, 'utf8')
288
+ } catch {
289
+ return undefined
290
+ }
291
+ const parsed = parseSkillDocument(text)
292
+ const dirName = String(candidate?.locator?.dir ?? '').split('/').pop() ?? ''
293
+ const effective = candidateOf(parsed, dirName, String(candidate?.locator?.dir ?? ''), file)
294
+ if (effective === undefined || effective.name !== candidate.name) return undefined
295
+ return {
296
+ name: effective.name,
297
+ description: effective.description,
298
+ ...(typeof effective.whenToUse === 'string' ? { whenToUse: effective.whenToUse } : {}),
299
+ invocation: effective.invocation,
300
+ source: effective.source,
301
+ provider: PROVIDER_NAME,
302
+ path: file,
303
+ resourceBase: effective.resourceBase,
304
+ content: parsed.body,
305
+ ...(parsed.frontmatter.length > 0 ? { metadata: parsed.meta } : {}),
306
+ }
307
+ },
308
+ }
309
+ }
package/src/remount.js ADDED
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Boot-time re-mount of persisted MCP servers.
3
+ *
4
+ * Membership alone is not a connection: `state.json` used to keep only
5
+ * `{enabled, modes, workspaces}`, so every Host restart came back with members
6
+ * that listed zero tools — the pool looked configured but had no MCP interface
7
+ * at all, and nothing short of re-importing repaired it.
8
+ *
9
+ * Since the member now stores its `definition`, the pool can rebuild its own
10
+ * `mcp-client` rows when the plugin activates. This module does exactly that,
11
+ * after the Loader service exists, without blocking boot: each server mounts in
12
+ * the background through the same tracker the panel polls.
13
+ *
14
+ * @module dsh-skill-pool/remount
15
+ */
16
+
17
+ import { mountServer } from './mount.js'
18
+
19
+ /**
20
+ * Re-mount every stored MCP member that carries a definition.
21
+ *
22
+ * A member is skipped when it is explicitly disabled, has no definition (an
23
+ * older document, or a membership created before this version), or is already
24
+ * ready/mounting in the tracker. Failures stay in the tracker as `failed` and
25
+ * are logged; they never reject the caller.
26
+ *
27
+ * @param {object} options - remount options.
28
+ * @param {object} options.ctx - plugin context.
29
+ * @param {() => Promise<object>} options.getState - effective document reader.
30
+ * @param {{start: Function, status: Function}} options.mounts - mount tracker.
31
+ * @param {{info?: Function, warn?: Function}} [options.logger] - logger.
32
+ * @param {{timeoutMs?: number, intervalMs?: number}} [options.mountProbe] - readiness window.
33
+ * @returns {Promise<{mounted: string[], skipped: string[]}>} what was started.
34
+ */
35
+ export async function remountPoolServers({ ctx, getState, mounts, logger, mountProbe } = {}) {
36
+ const mounted = []
37
+ const skipped = []
38
+ let state
39
+ try {
40
+ state = await getState()
41
+ } catch (error) {
42
+ logger?.warn?.(`[skill-pool] remount skipped: ${error instanceof Error ? error.message : String(error)}`)
43
+ return { mounted, skipped }
44
+ }
45
+
46
+ const members = state?.mcp !== null && typeof state?.mcp === 'object' ? state.mcp : {}
47
+ const status = typeof mounts?.status === 'function' ? mounts.status() : {}
48
+ for (const [serverName, member] of Object.entries(members)) {
49
+ const definition = member?.definition
50
+ if (definition === undefined || definition === null || typeof definition !== 'object') {
51
+ skipped.push(serverName)
52
+ continue
53
+ }
54
+ if (member.enabled === false) {
55
+ skipped.push(serverName)
56
+ continue
57
+ }
58
+ const current = status[serverName]?.state
59
+ if (current === 'ready' || current === 'mounting') {
60
+ skipped.push(serverName)
61
+ continue
62
+ }
63
+ mounted.push(serverName)
64
+ mountServer({
65
+ ctx,
66
+ serverName,
67
+ definition,
68
+ mounts,
69
+ timeoutMs: mountProbe?.timeoutMs,
70
+ intervalMs: mountProbe?.intervalMs,
71
+ logger,
72
+ origin: 'boot',
73
+ })
74
+ }
75
+
76
+ if (mounted.length > 0) logger?.info?.(`[skill-pool] re-mounting stored MCP servers: ${mounted.join(', ')}`)
77
+ return { mounted, skipped }
78
+ }