dsh-project-mcp 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/LICENSE +21 -0
- package/README.md +983 -0
- package/cordis.patch.yml +7 -0
- package/locale/en.json +6 -0
- package/locale/ru.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +106 -0
- package/src/activation.ts +1632 -0
- package/src/bridge.ts +486 -0
- package/src/client/design-fixtures.ts +399 -0
- package/src/client/design.ts +410 -0
- package/src/client/index.ts +255 -0
- package/src/client/locales/host.ts +570 -0
- package/src/client/locales/ui.ts +914 -0
- package/src/client/plugin-config.ts +721 -0
- package/src/client/policy.ts +277 -0
- package/src/client/settings-tools.ts +1136 -0
- package/src/client/settings.ts +3603 -0
- package/src/client/tab-locale.ts +94 -0
- package/src/client/toasts.ts +553 -0
- package/src/client/usage-view.ts +190 -0
- package/src/client/view.ts +4120 -0
- package/src/discovery.ts +211 -0
- package/src/guidance.ts +415 -0
- package/src/index.ts +685 -0
- package/src/logs.ts +184 -0
- package/src/naming.ts +134 -0
- package/src/notifications.ts +254 -0
- package/src/parse.ts +637 -0
- package/src/policy.ts +425 -0
- package/src/runtime.ts +4222 -0
- package/src/shared.ts +130 -0
- package/src/types.ts +662 -0
- package/src/ui.ts +579 -0
- package/src/usage.ts +442 -0
- package/src/write.ts +447 -0
package/src/types.ts
ADDED
|
@@ -0,0 +1,662 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared row/snapshot vocabulary for `dsh-project-mcp`.
|
|
3
|
+
*
|
|
4
|
+
* The host half publishes a {@link ProjectSnapshot} through the `projectMcp`
|
|
5
|
+
* service so a future Web UI (or a test) can read what is mounted without
|
|
6
|
+
* importing the runtime.
|
|
7
|
+
*
|
|
8
|
+
* @module dsh-project-mcp/types
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Type-only, and imported for its effect on the ambient types rather than for
|
|
13
|
+
* anything this module uses: `@deepseek-ai/dsh-tools` declares `Context.tools`
|
|
14
|
+
* and the `tools/change` / `tools/result` events as module augmentation of
|
|
15
|
+
* `@deepseek-ai/cordis`, and TypeScript applies an augmentation only when the
|
|
16
|
+
* augmenting module is part of the compilation. Nothing of the package reaches
|
|
17
|
+
* the runtime — the import is erased by the compiler, and the plugin still
|
|
18
|
+
* takes the service off the context it is handed instead of importing the
|
|
19
|
+
* module.
|
|
20
|
+
*/
|
|
21
|
+
import type {} from '@deepseek-ai/dsh-tools'
|
|
22
|
+
|
|
23
|
+
/** Runtime state of one project-declared MCP server. */
|
|
24
|
+
export type ServerStatus =
|
|
25
|
+
/** Mounted and its tools are visible in the owning scope. */
|
|
26
|
+
| 'active'
|
|
27
|
+
/** Mounted; activation or the initial connection has not settled yet. */
|
|
28
|
+
| 'connecting'
|
|
29
|
+
/**
|
|
30
|
+
* Declared, parsed, and not mounted: either `lazy` has not seen this
|
|
31
|
+
* session's first turn yet, or the session went idle and its mounts were
|
|
32
|
+
* released (`idleTimeoutMs`). The next turn mounts it again.
|
|
33
|
+
*/
|
|
34
|
+
| 'idle'
|
|
35
|
+
/** Declared with `enabled: false` — never mounted. */
|
|
36
|
+
| 'disabled'
|
|
37
|
+
/** The same `serverName` is reserved by a live profile-level instance. */
|
|
38
|
+
| 'conflict'
|
|
39
|
+
/** The entry or its mount failed; `detail` carries the reason. */
|
|
40
|
+
| 'error'
|
|
41
|
+
|
|
42
|
+
/** One server row of a project snapshot. */
|
|
43
|
+
export interface ServerRow {
|
|
44
|
+
/** `serverName` (the `mcpServers` key, sanitized). */
|
|
45
|
+
name: string
|
|
46
|
+
/** Current lifecycle state. */
|
|
47
|
+
status: ServerStatus
|
|
48
|
+
/** Project root the entry was read from. */
|
|
49
|
+
projectRoot: string
|
|
50
|
+
/** Absolute path of the declaring document. */
|
|
51
|
+
source?: string
|
|
52
|
+
/** `stdio` or `streamable-http`, when the entry parsed. */
|
|
53
|
+
transport?: 'stdio' | 'streamable-http'
|
|
54
|
+
/**
|
|
55
|
+
* Failure, stall or conflict explanation. Redacted on purpose: it names the
|
|
56
|
+
* command but never its arguments, and an HTTP endpoint keeps its path but
|
|
57
|
+
* drops the query string, because both can carry credentials.
|
|
58
|
+
*/
|
|
59
|
+
detail?: string
|
|
60
|
+
/**
|
|
61
|
+
* Stable wire code of `detail` (`projectMcp.host` namespace), for
|
|
62
|
+
* client-side translation. Optional and additive, exactly like
|
|
63
|
+
* {@link blockedCode}: the prose field keeps its byte-identical English and
|
|
64
|
+
* stays the fallback, so a client and a host of different builds degrade
|
|
65
|
+
* rather than break.
|
|
66
|
+
*/
|
|
67
|
+
detailCode?: string
|
|
68
|
+
/**
|
|
69
|
+
* Flat params of {@link detailCode}; a name ending in `Code` is itself a
|
|
70
|
+
* wire code the client resolves two-level.
|
|
71
|
+
*/
|
|
72
|
+
detailParams?: Record<string, string>
|
|
73
|
+
/**
|
|
74
|
+
* Parsed body of the entry, for the editor. Absent when the entry did not
|
|
75
|
+
* parse — there is nothing to edit then.
|
|
76
|
+
*/
|
|
77
|
+
entry?: EntrySnapshot
|
|
78
|
+
/** Where this row may be written back, when it may be written at all. */
|
|
79
|
+
writeScope?: WriteScope
|
|
80
|
+
/** One line saying why writing is unavailable; always set for `readonly`. */
|
|
81
|
+
writeBlockedReason?: string
|
|
82
|
+
/**
|
|
83
|
+
* Stable wire code of `writeBlockedReason` (`projectMcp.host` namespace),
|
|
84
|
+
* for client-side translation. Optional and additive: the prose field keeps
|
|
85
|
+
* its byte-identical English and stays the fallback, so a client and a host
|
|
86
|
+
* of different builds degrade rather than break.
|
|
87
|
+
*/
|
|
88
|
+
blockedCode?: string
|
|
89
|
+
/**
|
|
90
|
+
* Flat params of {@link blockedCode}; a name ending in `Code` is itself a
|
|
91
|
+
* wire code the client resolves two-level.
|
|
92
|
+
*/
|
|
93
|
+
blockedParams?: Record<string, string>
|
|
94
|
+
/**
|
|
95
|
+
* Opaque content revision of the declaring document at snapshot time. A save
|
|
96
|
+
* must carry the revision it was built from: a mismatch means the document
|
|
97
|
+
* changed underneath the editor, and the write is refused rather than merged.
|
|
98
|
+
*/
|
|
99
|
+
documentRevision?: string
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* How one `env` or `headers` entry is known to the host.
|
|
104
|
+
*
|
|
105
|
+
* A value can come from the declaring document, be answered outside it (the
|
|
106
|
+
* project's own `.env` or the credentials file), or be withheld because it is a
|
|
107
|
+
* credential. {@link EntryField.masked} is the field
|
|
108
|
+
* that changes how a write treats it: a masked key submitted without a `value` is
|
|
109
|
+
* kept exactly as the document declares it, so an editor that cannot see a secret
|
|
110
|
+
* can never erase or replace one.
|
|
111
|
+
*/
|
|
112
|
+
export interface EntryField {
|
|
113
|
+
/** Key exactly as declared. */
|
|
114
|
+
readonly key: string
|
|
115
|
+
/** Literal value; absent when the host withholds it. */
|
|
116
|
+
readonly value?: string
|
|
117
|
+
/** `true` when `value` is absent because the value is a secret. */
|
|
118
|
+
readonly masked?: true
|
|
119
|
+
/**
|
|
120
|
+
* `true` when the key is answered outside the document — by the project's
|
|
121
|
+
* `.env` or by the credentials file. The name predates the project dotenv
|
|
122
|
+
* sources; the meaning the write path reads is "never write this value back".
|
|
123
|
+
*/
|
|
124
|
+
readonly fromCredentials?: true
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* One server entry as the host parsed it, for an editor.
|
|
129
|
+
*
|
|
130
|
+
* Every field is what the declaring document holds — a resolved default is never
|
|
131
|
+
* folded in, because a save replaces the declaration, not the runtime config.
|
|
132
|
+
*/
|
|
133
|
+
export interface EntrySnapshot {
|
|
134
|
+
/** Transport the entry declares. */
|
|
135
|
+
readonly transport: 'stdio' | 'streamable-http'
|
|
136
|
+
/** `stdio`: the program to run. */
|
|
137
|
+
readonly command?: string
|
|
138
|
+
/** `stdio`: its arguments, verbatim. */
|
|
139
|
+
readonly args?: readonly string[]
|
|
140
|
+
/** `stdio`: working directory, when the entry declares one. */
|
|
141
|
+
readonly cwd?: string
|
|
142
|
+
/** `stdio`: declared environment, secrets masked. */
|
|
143
|
+
readonly env?: readonly EntryField[]
|
|
144
|
+
/** `streamable-http`: the endpoint, with a credential-bearing query dropped. */
|
|
145
|
+
readonly url?: string
|
|
146
|
+
/** `streamable-http`: declared headers, secrets masked. */
|
|
147
|
+
readonly headers?: readonly EntryField[]
|
|
148
|
+
/** `false` when the declaration disables the server; absent means enabled. */
|
|
149
|
+
readonly enabled?: boolean
|
|
150
|
+
/** Declared connect timeout in milliseconds, when the entry sets one. */
|
|
151
|
+
readonly connectTimeoutMs?: number
|
|
152
|
+
/**
|
|
153
|
+
* Keys the editor does not present, kept in their declared order and written
|
|
154
|
+
* back untouched. A save replaces the entry wholesale, so dropping them would
|
|
155
|
+
* delete configuration the panel never showed.
|
|
156
|
+
*/
|
|
157
|
+
readonly extra?: Readonly<Record<string, unknown>>
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Whether one row's declaring document may be rewritten.
|
|
162
|
+
*
|
|
163
|
+
* - `project` — one of the deployment's project documents (`localFiles`,
|
|
164
|
+
* `<project>/.dsh/mcp.json` out of the box);
|
|
165
|
+
* - `global` — one of its global documents (`globalFiles`), written only with an
|
|
166
|
+
* explicit per-write consent;
|
|
167
|
+
* - `readonly` — the profile, `<DSH_HOME>` or a bundled document: never written.
|
|
168
|
+
*/
|
|
169
|
+
export type WriteScope = 'project' | 'global' | 'readonly'
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* One document a project is configured to read.
|
|
173
|
+
*
|
|
174
|
+
* The list a project publishes is exactly its read order — global documents
|
|
175
|
+
* first, then the project's own — so the panel's priority number is an index
|
|
176
|
+
* into it and never a table of hardcoded file names.
|
|
177
|
+
*/
|
|
178
|
+
export interface ConfiguredFile {
|
|
179
|
+
/** Absolute path of the document. */
|
|
180
|
+
readonly path: string
|
|
181
|
+
/**
|
|
182
|
+
* `global` — read for every project, before its own documents; `project` —
|
|
183
|
+
* read from the project root.
|
|
184
|
+
*/
|
|
185
|
+
readonly scope: 'global' | 'project'
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** Diagnostics surfaced alongside the rows. */
|
|
189
|
+
export interface SnapshotIssue {
|
|
190
|
+
/** Absolute path of the declaring document. */
|
|
191
|
+
source: string
|
|
192
|
+
/** Server the diagnostic belongs to, when entry-scoped. */
|
|
193
|
+
server?: string
|
|
194
|
+
/** `error` or `warning`. */
|
|
195
|
+
level: 'error' | 'warning'
|
|
196
|
+
/** Human-readable text. */
|
|
197
|
+
message: string
|
|
198
|
+
/**
|
|
199
|
+
* Stable wire code of `message` (`projectMcp.host` namespace), for
|
|
200
|
+
* client-side translation. Optional and additive: `message` keeps its
|
|
201
|
+
* byte-identical English and stays the fallback. Behavioural matches key on
|
|
202
|
+
* this field — never on the prose, which the client may have translated.
|
|
203
|
+
*/
|
|
204
|
+
code?: string
|
|
205
|
+
/**
|
|
206
|
+
* Flat params of {@link SnapshotIssue.code}; a name ending in `Code` is
|
|
207
|
+
* itself a wire code the client resolves two-level.
|
|
208
|
+
*/
|
|
209
|
+
params?: Record<string, string>
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* One session's own view of the project it works in.
|
|
214
|
+
*
|
|
215
|
+
* Sessions of one project are independent: each mounts its own servers, and one
|
|
216
|
+
* may have them running while another has not started a turn yet. The panel
|
|
217
|
+
* needs that split, because a project-level merge alone cannot say *which*
|
|
218
|
+
* session holds a mount.
|
|
219
|
+
*/
|
|
220
|
+
export interface SessionSnapshot {
|
|
221
|
+
/** Agent (session) id. */
|
|
222
|
+
id: string
|
|
223
|
+
/** Rows for this session alone, in document order. */
|
|
224
|
+
rows: ServerRow[]
|
|
225
|
+
/** Diagnostics this session surfaced. */
|
|
226
|
+
issues: SnapshotIssue[]
|
|
227
|
+
/** What this session offers the model, when the host has mounted for it. */
|
|
228
|
+
tools?: SessionTools
|
|
229
|
+
/**
|
|
230
|
+
* How many events of the project's ring belong to this session. Absent for a
|
|
231
|
+
* session that produced none, so the tab's log badge reads a real `0`.
|
|
232
|
+
*/
|
|
233
|
+
logCount?: number
|
|
234
|
+
/**
|
|
235
|
+
* `serverName` conflicts this session last reconciled: a profile-level
|
|
236
|
+
* instance that already owns a name, or one name two project documents
|
|
237
|
+
* declare. Published even when empty, so a reader can tell "this session
|
|
238
|
+
* reported none" from a host that does not report conflicts at all.
|
|
239
|
+
*/
|
|
240
|
+
conflicts?: readonly ServerConflict[]
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** One tool a session offers the model, and what put it in the request. */
|
|
244
|
+
export interface OfferedTool {
|
|
245
|
+
/** Public registry name, eg `mcp__tglider__workspace`. */
|
|
246
|
+
readonly name: string
|
|
247
|
+
/**
|
|
248
|
+
* The tier that offered it: `session` activated on demand through the search
|
|
249
|
+
* tool, `context` ranked from the task text of the current conversation. The
|
|
250
|
+
* counter-seeded baseline is not this shape — it is a plain name list in
|
|
251
|
+
* {@link SessionTools.baseline}.
|
|
252
|
+
*/
|
|
253
|
+
readonly via: 'session' | 'context'
|
|
254
|
+
/**
|
|
255
|
+
* Epoch milliseconds of the last offer or call. Absent for the context tier,
|
|
256
|
+
* whose live state stamps an advance rather than a clock reading.
|
|
257
|
+
*/
|
|
258
|
+
readonly at?: number
|
|
259
|
+
/**
|
|
260
|
+
* Number of the agent step (from `1`) the tool was offered at, or `undefined`
|
|
261
|
+
* for a host that does not count steps. A panel that reads no number draws no
|
|
262
|
+
* step tag at all rather than a made-up one.
|
|
263
|
+
*/
|
|
264
|
+
readonly step?: number
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* Another loaded plugin that owns the assembled tool list.
|
|
269
|
+
*
|
|
270
|
+
* The plugin and such an owner cannot shape one request together: the outer
|
|
271
|
+
* listener of whoever assembles last rewrites `assembly.tools`, so the plugin's
|
|
272
|
+
* own deferral would be re-applied over an already-trimmed list. The host
|
|
273
|
+
* reports the owner instead of silently composing with it, and a panel prints
|
|
274
|
+
* the coexistence note only when this record is published.
|
|
275
|
+
*/
|
|
276
|
+
export interface PresentationOwner {
|
|
277
|
+
/** Loader entry name, for example `dsh-progressive-tools`. */
|
|
278
|
+
readonly name: string
|
|
279
|
+
/** One line saying why coexisting in one request is impossible. */
|
|
280
|
+
readonly note: string
|
|
281
|
+
/**
|
|
282
|
+
* The `projectMcp.host` code of {@link note} (F-48): the client translates
|
|
283
|
+
* by it and falls back to `note`'s English, byte-identical, when the code is
|
|
284
|
+
* absent or unknown. No params — the note is one fixed sentence.
|
|
285
|
+
*/
|
|
286
|
+
readonly noteCode?: string
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* One `serverName` two declarations fight over.
|
|
291
|
+
*
|
|
292
|
+
* `profile` is the profile-level `mcp-client` instance that already owns the
|
|
293
|
+
* name: the project entry mounts only through the local alias the user chose,
|
|
294
|
+
* and never under the contested name itself. `duplicate` is one name declared by
|
|
295
|
+
* more than one project document: the highest-priority document wins and the
|
|
296
|
+
* others are ignored.
|
|
297
|
+
*/
|
|
298
|
+
export interface ServerConflict {
|
|
299
|
+
/** `serverName` the declarations share. */
|
|
300
|
+
readonly server: string
|
|
301
|
+
/** `profile` — a profile-level instance owns the name; `duplicate` — two documents. */
|
|
302
|
+
readonly kind: 'profile' | 'duplicate'
|
|
303
|
+
/** Declaring documents, the winner first. */
|
|
304
|
+
readonly sources: readonly string[]
|
|
305
|
+
/** One line: who wins, and why. */
|
|
306
|
+
readonly message: string
|
|
307
|
+
/**
|
|
308
|
+
* The `projectMcp.host` code of {@link message} (F-48): the client translates
|
|
309
|
+
* by it and falls back to `message`'s English, byte-identical, when the code
|
|
310
|
+
* is absent (a host older than the field) or unknown to its dictionaries.
|
|
311
|
+
*/
|
|
312
|
+
readonly code?: string
|
|
313
|
+
/**
|
|
314
|
+
* Flat params of {@link code}; numbers stringify at emission. A name ending
|
|
315
|
+
* in `Code` is itself a wire code, resolved two-level through the same
|
|
316
|
+
* namespace and substituted under the plain name.
|
|
317
|
+
*/
|
|
318
|
+
readonly params?: Record<string, string>
|
|
319
|
+
/**
|
|
320
|
+
* The local name this project's entry mounts under when the user chose
|
|
321
|
+
* `local`, as `mcp__<alias>__<tool>` in the model's own list. Published on a
|
|
322
|
+
* `profile` conflict even while the choice is still the profile's, so the
|
|
323
|
+
* panel can offer the alias it would use rather than inventing one.
|
|
324
|
+
*/
|
|
325
|
+
readonly alias?: string
|
|
326
|
+
/**
|
|
327
|
+
* What the project's policy says about this name. Absent on a `duplicate`,
|
|
328
|
+
* which no choice resolves, and on a host older than this field.
|
|
329
|
+
*/
|
|
330
|
+
readonly choice?: ConflictChoice
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/**
|
|
334
|
+
* What one live session currently offers the model.
|
|
335
|
+
*
|
|
336
|
+
* Measured from the session's own state, not from the project: two sessions of
|
|
337
|
+
* one project differ as soon as one of them has called a tool, and the panel's
|
|
338
|
+
* promise is to show what *this* session's model sees.
|
|
339
|
+
*/
|
|
340
|
+
export interface SessionTools {
|
|
341
|
+
/** Live agent (session) id this row describes. */
|
|
342
|
+
readonly sessionId: string
|
|
343
|
+
/**
|
|
344
|
+
* Names offered because the durable counters proved them hot, plus the pins;
|
|
345
|
+
* empty in `off`, which offers none of the project's tools.
|
|
346
|
+
*/
|
|
347
|
+
readonly baseline: readonly string[]
|
|
348
|
+
/** Names this session activated on demand, oldest first; empty in `off`. */
|
|
349
|
+
readonly activated: readonly OfferedTool[]
|
|
350
|
+
/** Names the task context offered, oldest first; empty in `off`. */
|
|
351
|
+
readonly context: readonly OfferedTool[]
|
|
352
|
+
/**
|
|
353
|
+
* Names mounted for the project but not offered by this plugin, sorted. In
|
|
354
|
+
* `disclosure` these are the names the budget pushed out of the request; in
|
|
355
|
+
* `direct` the list is empty, because nothing is filtered; in `off` it is the
|
|
356
|
+
* whole mounted surface, because a project that is switched off is offered not
|
|
357
|
+
* at all. Its length is exactly the count a panel shows as hidden — and such a
|
|
358
|
+
* panel has to read {@link ToolPolicy.mode} first, since tools another
|
|
359
|
+
* presentation plugin leaves in the request are not this one's offers.
|
|
360
|
+
*/
|
|
361
|
+
readonly deferred: readonly string[]
|
|
362
|
+
/** Tools mounted for the project in total. */
|
|
363
|
+
readonly mounted: number
|
|
364
|
+
/** Serialized size of the mounted surface, in characters. */
|
|
365
|
+
readonly surfaceChars: number
|
|
366
|
+
/**
|
|
367
|
+
* Serialized size of the offered set — {@link SessionTools.baseline} plus the
|
|
368
|
+
* `activated` and `context` names — in characters. Absent from a host that
|
|
369
|
+
* does not split the surface, and then a panel prints no request estimate
|
|
370
|
+
* rather than inventing one.
|
|
371
|
+
*/
|
|
372
|
+
readonly visibleChars?: number
|
|
373
|
+
/**
|
|
374
|
+
* Serialized size of {@link SessionTools.deferred}, in characters: exactly the
|
|
375
|
+
* part of the mounted surface this plugin leaves out of the request. `0` when
|
|
376
|
+
* nothing is deferred, so a panel that found this field may divide it by four
|
|
377
|
+
* for a token estimate.
|
|
378
|
+
*/
|
|
379
|
+
readonly deferredChars?: number
|
|
380
|
+
/**
|
|
381
|
+
* Configured deferral budget in characters. `0` means there is no threshold at
|
|
382
|
+
* all: every surface counts as over budget, so tools are deferred however small
|
|
383
|
+
* the project is. Read {@link SessionTools.deferring} rather than comparing this
|
|
384
|
+
* with {@link SessionTools.surfaceChars} — the host owns the rule.
|
|
385
|
+
*/
|
|
386
|
+
readonly budgetChars: number
|
|
387
|
+
/**
|
|
388
|
+
* `true` while the surface is over the budget, so tools really are deferred.
|
|
389
|
+
* Only `disclosure` can defer: `direct` filters nothing and `off` offers
|
|
390
|
+
* nothing, so both report `false` however large the mounted surface is.
|
|
391
|
+
*/
|
|
392
|
+
readonly deferring: boolean
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
/** How one project's MCP tools are offered to the model. */
|
|
396
|
+
export type ToolMode =
|
|
397
|
+
/** Offer the baseline and the on-demand tiers (the shipped behaviour). */
|
|
398
|
+
| 'disclosure'
|
|
399
|
+
/** Never defer: every mounted tool is listed in every request. */
|
|
400
|
+
| 'direct'
|
|
401
|
+
/** Do not offer this project's MCP tools at all. */
|
|
402
|
+
| 'off'
|
|
403
|
+
|
|
404
|
+
/**
|
|
405
|
+
* How one `serverName` a project shares with a live profile instance is shown.
|
|
406
|
+
*
|
|
407
|
+
* The profile's instance owns the name in every scope, so the two declarations
|
|
408
|
+
* cannot both mount under it. `profile` keeps the profile's tools exactly as
|
|
409
|
+
* they are and leaves the project's entry unmounted; `local` mounts the
|
|
410
|
+
* project's entry under a local namespace (see `src/naming.ts`) so both toolsets
|
|
411
|
+
* reach the model — the only difference being the names they carry; `native`
|
|
412
|
+
* mounts the project's entry under the name it declares, which is the nearer
|
|
413
|
+
* declaration in this project's own sessions and so shadows the profile's tools
|
|
414
|
+
* of that name there, while every other project keeps seeing the profile's.
|
|
415
|
+
*/
|
|
416
|
+
export type ConflictChoice =
|
|
417
|
+
/** The profile instance keeps the name; the project entry does not mount. */
|
|
418
|
+
| 'profile'
|
|
419
|
+
/** The project entry mounts under its local alias, next to the profile's. */
|
|
420
|
+
| 'local'
|
|
421
|
+
/** The project entry mounts under the declared name, shadowing the profile's in this project. */
|
|
422
|
+
| 'native'
|
|
423
|
+
|
|
424
|
+
/**
|
|
425
|
+
* One project's tool policy.
|
|
426
|
+
*
|
|
427
|
+
* The mode decides whether tools are deferred, the pins are the names the user
|
|
428
|
+
* insists on — a pinned tool is offered from the first step of every request, is
|
|
429
|
+
* never dropped by idle pruning or by a compaction, and is not counted against
|
|
430
|
+
* the deferral budget's reading of what is hidden — and the aliases remember, per
|
|
431
|
+
* conflicting `serverName`, which of the two declarations the user chose to see.
|
|
432
|
+
*/
|
|
433
|
+
export interface ToolPolicy {
|
|
434
|
+
/** Mode in force. */
|
|
435
|
+
readonly mode: ToolMode
|
|
436
|
+
/**
|
|
437
|
+
* Public registry names pinned for this project, in the order the user pinned
|
|
438
|
+
* them. A name the project no longer mounts is kept: the declaration may come
|
|
439
|
+
* back, and a pin that silently disappeared would be a surprise.
|
|
440
|
+
*/
|
|
441
|
+
readonly pins: readonly string[]
|
|
442
|
+
/**
|
|
443
|
+
* Choice per contested `serverName`. Optional so every fixture, host and
|
|
444
|
+
* stored document written before this field existed keeps meaning exactly
|
|
445
|
+
* what it meant: a name that is absent is one the user never chose about,
|
|
446
|
+
* and the shipped answer is the profile's instance. The store publishes an
|
|
447
|
+
* empty map rather than dropping the field, so a reader may treat `undefined`
|
|
448
|
+
* and `{}` alike.
|
|
449
|
+
*/
|
|
450
|
+
readonly aliases?: Readonly<Record<string, ConflictChoice>>
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
/** The policy every project follows until one is configured. */
|
|
454
|
+
export const DEFAULT_TOOL_POLICY: ToolPolicy = { mode: 'disclosure', pins: [], aliases: {} }
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* How much one MCP server of one project has been used.
|
|
458
|
+
*
|
|
459
|
+
* Counted on the host from the tool registry's own events, so it is exact rather
|
|
460
|
+
* than sampled, and keyed by project root: sessions come and go, the numbers
|
|
461
|
+
* stay, which is what makes them usable for later decisions about a project.
|
|
462
|
+
*/
|
|
463
|
+
export interface ServerUsage {
|
|
464
|
+
/** Calls dispatched through the registry, successful or not. */
|
|
465
|
+
calls: number
|
|
466
|
+
/** Calls whose result carried an error. */
|
|
467
|
+
errors: number
|
|
468
|
+
/** ISO timestamp of the most recent call. */
|
|
469
|
+
lastUsedAt?: string
|
|
470
|
+
/**
|
|
471
|
+
* Per tool counts, keyed by the tool name as declared by the server, i.e.
|
|
472
|
+
* without the `mcp__<serverName>__` prefix the registry publishes it under.
|
|
473
|
+
*/
|
|
474
|
+
tools: Record<string, number>
|
|
475
|
+
/**
|
|
476
|
+
* The same readings split by session, keyed by the session (agent) id the
|
|
477
|
+
* panel already uses everywhere else.
|
|
478
|
+
*
|
|
479
|
+
* Additive since F-34: a document written before this field existed is read as
|
|
480
|
+
* it is — `USAGE_VERSION` does not move, because a reader that meets an unknown
|
|
481
|
+
* version refuses the whole document and every counter would start from zero.
|
|
482
|
+
* Absent means "counted before the split", never "no calls".
|
|
483
|
+
*/
|
|
484
|
+
sessions?: Record<string, SessionUsage>
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* One session's share of a server's counters.
|
|
489
|
+
*
|
|
490
|
+
* A server is mounted for a project and a project's sessions share it, so the
|
|
491
|
+
* project total says what the project used while this says what *this* session
|
|
492
|
+
* did; the two differ exactly when other sessions of the project called the
|
|
493
|
+
* server, which is the case a panel scoped to one session could not show.
|
|
494
|
+
*/
|
|
495
|
+
export interface SessionUsage {
|
|
496
|
+
/** Calls this session dispatched through the registry. */
|
|
497
|
+
calls: number
|
|
498
|
+
/** Of those, the ones whose result carried an error. */
|
|
499
|
+
errors: number
|
|
500
|
+
/** ISO timestamp of this session's most recent call. */
|
|
501
|
+
lastUsedAt?: string
|
|
502
|
+
/** This session's counts, keyed by the tool name as the server declares it. */
|
|
503
|
+
tools: Record<string, number>
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* How serious one plugin event is, as the Logs tab colours it.
|
|
508
|
+
*
|
|
509
|
+
* Four levels, mapped from the lifecycle line the host already writes: `info`
|
|
510
|
+
* for a mount being registered, `up` for one whose tools became visible, `warn`
|
|
511
|
+
* for a stall or a release, `error` for a failed mount and the unmount that
|
|
512
|
+
* follows it. They are the labels the tab draws, not a host severity scale.
|
|
513
|
+
*/
|
|
514
|
+
export type LogLevel =
|
|
515
|
+
/** The instance is being registered (`project-mcp: mounting …`). */
|
|
516
|
+
| 'info'
|
|
517
|
+
/** The instance's tools are visible (`… is up …`). */
|
|
518
|
+
| 'up'
|
|
519
|
+
/** A stall, a repeated pass, or a release the operator did not ask for. */
|
|
520
|
+
| 'warn'
|
|
521
|
+
/** The mount failed, or a failed mount is being torn down. */
|
|
522
|
+
| 'error'
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* One lifecycle event, as the Logs tab lists it.
|
|
526
|
+
*
|
|
527
|
+
* The plugin's own events only — a mount, a start, a stop, a failure — mirroring
|
|
528
|
+
* the lines the host writes to the DSH log, so the two readers see the same
|
|
529
|
+
* facts. Events live in a per-project ring (`src/logs.ts`); the newest ones ride
|
|
530
|
+
* in the snapshot, the rest are paged over the route.
|
|
531
|
+
*/
|
|
532
|
+
export interface LogEvent {
|
|
533
|
+
/** When the event happened, epoch ms. */
|
|
534
|
+
readonly at: number
|
|
535
|
+
/** How serious it is, as the tab colours it. */
|
|
536
|
+
readonly level: LogLevel
|
|
537
|
+
/** Project root the event belongs to; the ring is keyed by it. */
|
|
538
|
+
readonly projectRoot: string
|
|
539
|
+
/**
|
|
540
|
+
* Session the event is attributed to. Set exactly when the lifecycle line it
|
|
541
|
+
* mirrors names one — `mounting`, `is up`, a stall — and absent on a
|
|
542
|
+
* project-level event such as a shared instance's unmount.
|
|
543
|
+
*/
|
|
544
|
+
readonly sessionId?: string
|
|
545
|
+
/** `serverName` the event is about; absent for an event with no server. */
|
|
546
|
+
readonly server?: string
|
|
547
|
+
/** One line, without a newline: one event is one row of the tab. */
|
|
548
|
+
readonly message: string
|
|
549
|
+
/**
|
|
550
|
+
* The three facts an error carries — the failure, the endpoint, the declaring
|
|
551
|
+
* document — and no advice: the server row already offers the retry.
|
|
552
|
+
*/
|
|
553
|
+
readonly detail?: string
|
|
554
|
+
/**
|
|
555
|
+
* Wire code of {@link LogEvent.message} (F-48), into the `projectMcp.host`
|
|
556
|
+
* namespace. Optional: a host older than the field sends prose only, and the
|
|
557
|
+
* client falls back to {@link LogEvent.message}.
|
|
558
|
+
*/
|
|
559
|
+
readonly code?: string
|
|
560
|
+
/** Flat params of {@link LogEvent.code}; numbers are stringified at emission. */
|
|
561
|
+
readonly params?: Record<string, string>
|
|
562
|
+
/** Wire code of {@link LogEvent.detail}, the same additive companion. */
|
|
563
|
+
readonly detailCode?: string
|
|
564
|
+
/** Flat params of {@link LogEvent.detailCode}. */
|
|
565
|
+
readonly detailParams?: Record<string, string>
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
/** Everything one project contributes to the live runtime. */
|
|
569
|
+
export interface ProjectSnapshot {
|
|
570
|
+
/** Project root the agents below resolved to. */
|
|
571
|
+
projectRoot: string
|
|
572
|
+
/**
|
|
573
|
+
* Documents this project is configured to read, in priority order — global
|
|
574
|
+
* ones first, then the project's own. Published even when empty, so a panel
|
|
575
|
+
* can tell "this deployment reads nothing" from a host that does not report
|
|
576
|
+
* its documents at all. Absent only from a snapshot a host older than this
|
|
577
|
+
* field produced, and then a reader falls back to the shipped names rather
|
|
578
|
+
* than inventing a priority.
|
|
579
|
+
*/
|
|
580
|
+
files?: readonly ConfiguredFile[]
|
|
581
|
+
/**
|
|
582
|
+
* The tool policy in force for this project. Absent only from a snapshot a host
|
|
583
|
+
* older than the policy store produced; a reader treats that as the shipped
|
|
584
|
+
* default, {@link DEFAULT_TOOL_POLICY}.
|
|
585
|
+
*/
|
|
586
|
+
policy?: ToolPolicy
|
|
587
|
+
/** Live agent (session) ids currently bound to this project. */
|
|
588
|
+
sessionIds: string[]
|
|
589
|
+
/**
|
|
590
|
+
* Merged rows for every declared server, in document order. When sessions
|
|
591
|
+
* disagree about one server, the more actionable state wins, so a mounted or
|
|
592
|
+
* broken server is never hidden behind a session that has not turned yet.
|
|
593
|
+
*/
|
|
594
|
+
rows: ServerRow[]
|
|
595
|
+
/** Parse and lifecycle diagnostics, deduplicated across the sessions. */
|
|
596
|
+
issues: SnapshotIssue[]
|
|
597
|
+
/** The same data split per session, in session-registration order. */
|
|
598
|
+
sessions: SessionSnapshot[]
|
|
599
|
+
/**
|
|
600
|
+
* Usage counters keyed by `serverName`, remembered across sessions. Absent
|
|
601
|
+
* while the host half has counted nothing for this project yet.
|
|
602
|
+
*/
|
|
603
|
+
usage?: Record<string, ServerUsage>
|
|
604
|
+
/**
|
|
605
|
+
* Another loaded plugin that owns the assembled tool list, when the profile
|
|
606
|
+
* has one. Absent means this plugin is the only owner — a panel that reads no
|
|
607
|
+
* record draws no coexistence notice.
|
|
608
|
+
*/
|
|
609
|
+
presentation?: PresentationOwner
|
|
610
|
+
/**
|
|
611
|
+
* Real `serverName` conflicts of this project: a profile-level instance that
|
|
612
|
+
* already owns a name, or one name two project documents declare. The list is
|
|
613
|
+
* always published — an empty one is the honest answer "no conflicts", which
|
|
614
|
+
* is what lets a panel report that instead of offering a disabled button.
|
|
615
|
+
*/
|
|
616
|
+
conflicts?: readonly ServerConflict[]
|
|
617
|
+
/**
|
|
618
|
+
* The newest events of this project's ring, oldest first, at most the page
|
|
619
|
+
* size (50). Absent for a project that has recorded nothing, so a tab draws
|
|
620
|
+
* its empty state rather than an empty list.
|
|
621
|
+
*/
|
|
622
|
+
logs?: readonly LogEvent[]
|
|
623
|
+
/**
|
|
624
|
+
* How many events the project's ring holds right now, `0…200`. Absent exactly
|
|
625
|
+
* when {@link ProjectSnapshot.logs} is: no events, nothing to count.
|
|
626
|
+
*/
|
|
627
|
+
logCount?: number
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/** Whole-plugin snapshot: one entry per project with live agents. */
|
|
631
|
+
export interface McpSnapshot {
|
|
632
|
+
/** `true` while the agents service has been observed. */
|
|
633
|
+
ready: boolean
|
|
634
|
+
/** Projects with at least one live agent. */
|
|
635
|
+
projects: ProjectSnapshot[]
|
|
636
|
+
/**
|
|
637
|
+
* Documents this deployment is configured to read, exactly as the config
|
|
638
|
+
* spells them — `local` relative to a project root, `global` relative to
|
|
639
|
+
* `$HOME` (or absolute). Published for the surfaces that must speak about the
|
|
640
|
+
* deployment itself, with no project at hand: the empty state names what would
|
|
641
|
+
* be read instead of a file name baked into the client. Absent from a snapshot
|
|
642
|
+
* a host older than this field produced.
|
|
643
|
+
*/
|
|
644
|
+
sources?: { readonly local: readonly string[]; readonly global: readonly string[] }
|
|
645
|
+
/** Absolute paths currently watched for config edits. */
|
|
646
|
+
watchedFiles: string[]
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
/**
|
|
650
|
+
* One pushed picture: what the status channel sends.
|
|
651
|
+
*
|
|
652
|
+
* The snapshot travels whole rather than as a delta, so a frame that arrives
|
|
653
|
+
* after a gap is still a complete answer — the panel can apply it without
|
|
654
|
+
* asking for anything back. `revision` counts the changes the host has announced
|
|
655
|
+
* and is what a late or repeated frame is judged by.
|
|
656
|
+
*/
|
|
657
|
+
export interface SnapshotChange {
|
|
658
|
+
/** Monotonic change counter, starting at `0` for the picture a stream opens on. */
|
|
659
|
+
revision: number
|
|
660
|
+
/** The whole picture at that revision. */
|
|
661
|
+
snapshot: McpSnapshot
|
|
662
|
+
}
|