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/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
+ }