dsh-project-mcp 0.2.0 → 0.4.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
@@ -48,6 +48,7 @@ other tool's file) is one config line away, never an implicit second source.
48
48
  - [Resource behaviour](#resource-behaviour)
49
49
  - [Runtimes](#runtimes)
50
50
  - [Verifying](#verifying)
51
+ - [Releasing](#releasing)
51
52
  - [Limitations](#limitations)
52
53
  - [Dogfooding](#dogfooding)
53
54
 
@@ -58,9 +59,9 @@ Implementation notes: [how it works](#how-it-works) · [bundle format](#bundle-f
58
59
  ```bash
59
60
  pnpm install && pnpm check # typecheck + build + tests under the coverage gate + resource audit
60
61
  pnpm coverage # the same suite with the coverage report only
61
- pnpm pack # -> dsh-project-mcp-0.2.0.tgz
62
- mv dsh-project-mcp-0.2.0.tgz ~/.dsh/packages/
63
- dsh plugin --profile web add file:$HOME/.dsh/packages/dsh-project-mcp-0.2.0.tgz
62
+ pnpm pack # -> dsh-project-mcp-<version>.tgz (builds first, via prepack)
63
+ mv dsh-project-mcp-<version>.tgz ~/.dsh/packages/
64
+ dsh plugin --profile web add file:$HOME/.dsh/packages/dsh-project-mcp-<version>.tgz
64
65
  ```
65
66
 
66
67
  `pnpm check` runs the suite through `--coverage`, and `vitest.config.ts` gates all
@@ -170,12 +171,12 @@ Plugin config is the `cordis.patch.yml` row (defaults shown):
170
171
  credentialsFile: '' # default: $DSH_HOME/.credentials.yaml
171
172
  allowGlobalWrite: false # let the editor write the documents of globalFiles
172
173
  activationEnabled: true # offer MCP tools through `mcp_search_tools` + activation
173
- activationSeeded: 8 # counter-seeded tools that are always offered
174
- activationMinCalls: 5 # calls one tool needs before it is seeded
175
- toolIdleMs: 1800000 # drop a session-activated tool after this long without a call; 0 disables
174
+ activationSeeded: 16 # counter-seeded tools that are always offered
175
+ activationMinCalls: 1 # calls one tool needs before it is seeded
176
+ toolIdleMs: 0 # drop a session-activated tool after this long without a call; 0 keeps it for the session
176
177
  guidanceEnabled: true # one short project-MCP guidance section in the session system prompt
177
178
  activationAutoLimit: 12 # names the task-context tier may offer at once; 0 disables that tier
178
- activationAutoStickySteps: 2 # extra user messages a context offer stays offered
179
+ activationAutoStickySteps: 100 # extra user messages a context offer stays offered
179
180
  activationToolBudgetChars: 40000 # serialized MCP surface above which tools are deferred; 0 defers always
180
181
  projectMarkers: ['.git', '.dsh', '.kimi-code', 'package.json']
181
182
  fileMarkers: ['.sln', '.slnx', '.csproj']
@@ -344,10 +345,12 @@ deployment wants, without touching the registry (this is the `disclosure` mode o
344
345
  *Tool policy* above; a project can be switched to `direct` or `off` instead):
345
346
 
346
347
  - **Hot tools are offered directly.** A tool whose project counters reached
347
- `activationMinCalls` (default 5) is seeded into a **baseline** that appears in
348
- the request from the first step on; `activationSeeded` (default 8) caps how
349
- many names the counters may seed. The counters are the ones above, so the
350
- baseline is remembered across sessions and restarts.
348
+ `activationMinCalls` (default 1) is seeded into a **baseline** that appears in
349
+ the request from the first step on; `activationSeeded` (default 16) caps how
350
+ many names the counters may seed. One call is enough, so the baseline follows
351
+ what the project really uses, and the counters only ever add names to it — a
352
+ tool that was called once stays offered. The counters are the ones above, so
353
+ the baseline is remembered across sessions and restarts.
351
354
  - **Matching tools are offered from the task context.** The host ranks the
352
355
  project's mounted tools against the newest task text with BM25 — over the tool
353
356
  name and description, tokenized on case boundaries, separators and punctuation,
@@ -363,14 +366,16 @@ deployment wants, without touching the registry (this is the `disclosure` mode o
363
366
  The counters keep accumulating either way, so the decision follows a project
364
367
  as it grows.
365
368
  - **The offered set is sticky, so it rarely changes.** A name stays offered for
366
- the task text that offered it plus `activationAutoStickySteps` (default 2)
367
- later messages, one input per recomputation, so several steps share one tool
368
- list instead of following every dip of the ranking. Because the inner listeners
369
- rebuild the registry list on every step, the additions are re-applied each time
370
- from what those listeners actually returned; when that list already carries
371
- everything, the listener hands back the **identical** assembly object. A
372
- changing tool list rewrites the prompt prefix and invalidates the model's
373
- cache, so the plugin changes it deliberately and rarely.
369
+ the task text that offered it plus `activationAutoStickySteps` (default 100)
370
+ later messages, one input per recomputation, so the whole session shares one
371
+ tool list instead of following every dip of the ranking. Because the inner
372
+ listeners rebuild the registry list on every step, the additions are re-applied
373
+ each time from what those listeners actually returned; when that list already
374
+ carries everything, the listener hands back the **identical** assembly object.
375
+ A changing tool list rewrites the prompt prefix and invalidates the model's
376
+ cache — the provider re-reads the prompt from the first altered token — so the
377
+ shipped window is wide enough that an offer outlives the task that produced it
378
+ and the list changes at most a compaction or an activation, not every turn.
374
379
  - **The rest are found, not listed.** The plugin registers `mcp_search_tools` in
375
380
  the session's own scope and also offers it from its own assembly listener — a
376
381
  presentation plugin that trims the list to an allowlist would otherwise drop
@@ -389,12 +394,21 @@ deployment wants, without touching the registry (this is the `disclosure` mode o
389
394
  activated tools join the offered
390
395
  list from the **next** model step on; only the tools already listed are
391
396
  reliable until then.
392
- - **Everything falls away again.** A session-activated tool that is not called
393
- within `toolIdleMs` (default 30 minutes) is dropped at the next `agent/status`
394
- transition, and a `compaction/end` clears the session's activations and the
395
- context offers outright. The counter baseline survives both — it is derived
396
- from durable counters, not from the session — and a pin survives them for the
397
- same reason (*Tool policy* above).
397
+ - **What does fall away is opt-in.** The shipped `toolIdleMs: 0` disables the
398
+ idle sweep, so a searched tool stays offered for the rest of the session, and
399
+ the offered set only ever grows there. A positive `toolIdleMs` restores the
400
+ old behaviour: a session-activated tool that is not called within the window
401
+ is dropped at the next `agent/status` transition. A `compaction/end` is the one
402
+ boundary that shrinks the set on its own: the conversation those offers
403
+ belonged to is rewritten there, so the provider recomputes the prompt prefix
404
+ anyway and a shorter list costs nothing newly. It drops the offers the model
405
+ never acted on — a context match or a search it did not call — and keeps the
406
+ activations a call backs: a tool the model called at least once stays offered
407
+ from the next step on, stamped with the time of that call. A tool called
408
+ without ever being activated is kept for the same reason — the session used it
409
+ — and the context tier restarts from scratch at that boundary. The counter
410
+ baseline survives both — it is derived from durable counters, not from the
411
+ session — and a pin survives them for the same reason (*Tool policy* above).
398
412
 
399
413
  **Where the task text comes from.** The context tier reads the session's own
400
414
  `session/event` stream: the newest committed `user/message` supplies the text,
@@ -565,9 +579,11 @@ a clock:
565
579
 
566
580
  ## Sidebar panel
567
581
 
568
- The package has a browser half (`./client`) that registers a tab with
569
- [`dsh-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar). A tab
570
- belongs to one conversation, so it shows **only that session's project** — never
582
+ The package has a browser half (`./client`) that registers a tab type with DSH's
583
+ **own right sidebar** — `ctx.sidebarRightTabs` for the type, the keyed
584
+ `sidebar.right.pane.tab` seat for the body (see `src/client/sidebar-tab.ts`) —
585
+ which the sidebar's guide page lists. A tab belongs to one conversation, so it
586
+ shows **only that session's project** — never
571
587
  another one: the servers it declares and their merged live status, then the same
572
588
  project broken down **per session** — which session holds a mount, which has not
573
589
  turned yet, which one is this tab's — with `Sync` / `Release` actions. `Release`
@@ -590,12 +606,14 @@ that has nothing to list names what is missing instead of showing an empty box
590
606
  no session, no project marker above the session cwd, no declared server, or
591
607
  nothing that needs attention.
592
608
 
593
- The same tab declares its own settings panel in the side card settings popup, and
594
- that panel is where the whole picture lives: **every** project with a live
595
- session, not just this tab's, plus the panel's poll interval, persisted in the
596
- sidebar's `pluginSettings`.
609
+ The tab chip's actions menu carries one row of this plugin's own — `Panel
610
+ settings…` — and the popup it opens is where the whole picture lives: **every**
611
+ project with a live session, not just this tab's, plus the panel's poll interval,
612
+ persisted in browser-local storage (`dsh-project-mcp:servers:refreshMs`). The row
613
+ dismisses the menu and the popup renders in DSH's `shell.overlay` floating layer,
614
+ so it outlives the menu it was opened from.
597
615
 
598
- `ctx.betterSidebar` exists only in the browser half, so the panel does not call
616
+ The browser half runs in its own process, so the panel does not call
599
617
  the runtime in process: the host half registers HTTP routes on the DSH web server
600
618
  (`/project-mcp/snapshot|events|logs|sync|retry|release|save|pin|policy`, see
601
619
  `src/ui.ts`) and the panel fetches them. Responses are `{ ok: true, value }` or
@@ -636,14 +654,16 @@ what the `change` frames of `GET /project-mcp/events` say, and the baseline
636
654
  servers starting at once.
637
655
 
638
656
  ```
639
- browser: ctx.inject(['betterSidebar'], s => s.betterSidebar.registerTab({ … }))
657
+ browser: ctx.inject(['slots', 'sidebarRightTabs'], s => s.sidebarRightTabs.register({ id, kind, … }))
658
+ s.slots.register({ name: 'sidebar.right.pane.tab', key: id }, Panel)
640
659
  fetch('/project-mcp/snapshot')
641
660
  host: ctx.webServer.register({ kind: 'prefix', path: '/project-mcp', … })
642
661
  ```
643
662
 
644
- Requirements: `react` in the composition. If the host already provides a
645
- `betterSidebar` service, the sidebar tab is registered; otherwise the host half
646
- keeps mounting servers. Client changes hot-reload (hard-refresh the browser);
663
+ Requirements: `react` in the composition. If the composition has DSH's right
664
+ sidebar (`slots` + `sidebarRightTabs`), the tab type is registered; otherwise the
665
+ host half keeps mounting servers and the settings page, the configuration card and
666
+ the toasts still work. Client changes hot-reload (hard-refresh the browser);
647
667
  host changes need a `dsh web` restart.
648
668
 
649
669
  ### Settings page
@@ -688,13 +708,13 @@ ctx.inject(['slots', 'locale'], (scope) => { // optional client service
688
708
  })
689
709
  ```
690
710
 
691
- The module-level `inject` is empty, and neither `betterSidebar` nor `locale` is
692
- listed there: an entry that waits on an optional service stays **pending**, and
693
- DSH's web boot audit refuses to start while any entry is pending. Both are read
694
- without gating the entry instead — the sidebar tab parks behind
695
- `ctx.inject(['betterSidebar'], …)` (so it registers whenever that service exists,
696
- in a composition that has one), and the tab's translate seat comes from
697
- `ctx.get('locale')`. A property read of a service the fiber did not declare
711
+ The module-level `inject` is empty, and neither `slots`, nor `sidebarRightTabs`,
712
+ nor `locale` is listed there: an entry that waits on an optional service stays
713
+ **pending**, and DSH's web boot audit refuses to start while any entry is pending.
714
+ All three are read without gating the entry instead — the tab type and its two
715
+ seats park behind `ctx.inject(['slots', 'sidebarRightTabs'], …)` (so they register
716
+ whenever the composition has a right sidebar), and the tab's translate seat comes
717
+ from `ctx.get('locale')`. A property read of a service the fiber did not declare
698
718
  throws `cannot get property "…" without inject` and fails the entry, which is
699
719
  what took the whole GUI down in 0.1.9. The host half and every slot-based surface
700
720
  continue without either service. The bundle requests
@@ -789,7 +809,7 @@ check passes on both:
789
809
  | 600 unrelated writes (`node_modules`, `dist`, `.git`) | 3 watch events → 1 pass, 0 catalog scans, 0 remounts |
790
810
  | mount → dispose | MCP child process exits, its pid file is removed |
791
811
  | server that cannot start | one detailed `error` row, no respawn storm, no leaked child |
792
- | 10 × session create/dispose | 0 surviving children, file descriptors flat, heap +0.9 MB |
812
+ | 10 × session create/dispose | 0 surviving children, file descriptors flat, heap +0.3 MB (settled: read after a collection; a runtime exposing no collector reads raw under the same 8 MB budget) |
793
813
  | two sessions, one project | 1 mount attempt, 1 child, 1 creation line — the second session's turn reuses it |
794
814
  | a release while another session holds | child stays up for the remaining holder, goes down with the last one |
795
815
  | teardown | watchers closed, descriptors released, 0 passes and ~1 ms CPU afterwards |
@@ -866,6 +886,46 @@ Manual acceptance on a running GUI:
866
886
  4. Editing the file adds/removes tools after the debounce (~300 ms), without a
867
887
  restart and without disturbing the profile-level servers.
868
888
 
889
+ ## Releasing
890
+
891
+ `package.json`'s `version` is the published version; a `v<version>` tag only selects
892
+ the commit, and the two are checked against each other before every publish.
893
+
894
+ Every push to `main` releases, when the commits since the last tag ask for one
895
+ (Conventional Commits: `feat` → minor, `fix`/`perf`/`revert` → patch, `!` or a
896
+ `BREAKING CHANGE:` paragraph → major; `docs`, `chore`, `ci`, `test` and `refactor`
897
+ release nothing on their own). `.github/workflows/release.yml` runs the full
898
+ `pnpm check` gate, decides the version with `scripts/next-version.mjs`, writes that one
899
+ line of `package.json`, commits it as `release: dsh-project-mcp <version>`, tags it,
900
+ creates the GitHub Release, and calls `npm-publish.yml` to publish the tag to npm —
901
+ called rather than triggered, because a Release created with the workflow's own
902
+ `GITHUB_TOKEN` starts no other run. The decision reads both `package.json` and the
903
+ highest `v*` tag and takes the newer of the two, so a tag that outran its manifest
904
+ cannot publish the wrong number twice; before tagging, the job refuses to reuse a tag
905
+ or an already-published version rather than failing later inside `npm publish`.
906
+
907
+ To see what the next push would release:
908
+
909
+ ```bash
910
+ node scripts/next-version.mjs # the decision, as JSON (nothing is written)
911
+ node scripts/next-version.mjs --bump patch # force a level over a docs-only range
912
+ ```
913
+
914
+ The `Release` workflow also has a manual entry point (*Run workflow*: `bump`, `dry_run`)
915
+ for re-driving a run that died between its tag and npm. To publish by hand, create a
916
+ GitHub Release for a tag whose `package.json` already carries that version; the publish
917
+ job fails loudly when the two disagree. `pnpm pack` builds by itself (`prepack`), so a
918
+ hand-made tarball cannot ship the package without its `lib/` — the shape the published
919
+ `0.2.0` had.
920
+
921
+ The publish credential is an **OIDC token**, not a repository secret: the job asks for
922
+ `id-token: write` and exchanges it with npm's trusted publishing (registered for this
923
+ repository and `npm-publish.yml` on npmjs.com), so nothing has to be rotated and a
924
+ stale `NODE_AUTH_TOKEN` must not be set — it would take precedence over the exchange.
925
+ That job pins Node 24, because the exchange needs npm ≥ 11.5.1 and is performed by the
926
+ **npm CLI**: the pnpm 10 line has no trusted-publishing support, so `pnpm publish` there
927
+ would send the PUT unauthenticated and the registry would mask that as a `404`.
928
+
869
929
  ## Limitations
870
930
 
871
931
  - Per-project cost: one MCP instance per project per server, shared by every
@@ -973,8 +1033,9 @@ src/usage.ts durable per-project tool-call counters
973
1033
  src/policy.ts durable per-project tool policy: mode (disclosure/direct/off), pins
974
1034
  src/guidance.ts project-MCP guidance section: deterministic text + wiring
975
1035
  src/types.ts snapshot/row vocabulary
976
- src/client/ browser half: sidebar tab, side card settings, native
977
- Settings page (`settings.section`), shared view helpers
1036
+ src/client/ browser half: the right-sidebar tab and its settings popup,
1037
+ the native Settings page (`settings.section`), shared view
1038
+ helpers
978
1039
  tests/ unit tests (parse, discovery, runtime, guidance, both views),
979
1040
  plus a load-path guard for the wrapped client bundle
980
1041
  scripts/ MCP fixture server, live smoke test, resource audit,
@@ -0,0 +1,77 @@
1
+ import { ReactNode } from "react";
2
+ import { Context } from "@deepseek-ai/cordis";
3
+ //#region src/client/view.d.ts
4
+ /** Translate one key, with optional `{name}` template params (the DSH seat). */
5
+ type Translate = (key: string, params?: Record<string, unknown>) => string;
6
+ //#endregion
7
+ //#region src/client/sidebar-tab.d.ts
8
+ /** The tab body's props: the framework's own, plus the seats this module binds. */
9
+ interface SidebarTabBodyProps {
10
+ /** The session the tab belongs to — the panel shows that session's project only. */
11
+ sessionId: string | undefined;
12
+ /** Whether the tab is on screen; an off-screen panel stops polling. */
13
+ visible: boolean;
14
+ /** The poll interval, followed live so a change in the settings popup reaches the panel. */
15
+ refreshMs: number;
16
+ t: Translate;
17
+ hostT: Translate;
18
+ }
19
+ /** The settings popup's content, with the seats it needs. */
20
+ interface SidebarSettingsProps {
21
+ refreshMs: number;
22
+ /** Write a new interval; the popup's own row is the only writer. */
23
+ onRefreshMs: (value: number) => void;
24
+ onClose: () => void;
25
+ t: Translate;
26
+ hostT: Translate;
27
+ }
28
+ //#endregion
29
+ //#region src/client/index.d.ts
30
+ /** Plugin name: matches the package name and the host half. */
31
+ export declare const name = "dsh-project-mcp";
32
+ /**
33
+ * Register the surfaces, each behind the services it actually needs.
34
+ *
35
+ * No module-level dependency is declared, because every one of them is optional:
36
+ * a module-level `inject` would leave this entry **pending** for good in a
37
+ * composition without the right sidebar, and DSH's web boot audit refuses to
38
+ * start while an entry is pending. `ctx.inject(name, …)` waits for the same
39
+ * services without gating the entry, so a composition without the sidebar keeps
40
+ * the native Settings page, the config card and the toast stack.
41
+ *
42
+ * A service this fiber did not declare must never be read as a property: Cordis
43
+ * throws `cannot get property "…" without inject`, and that throw fails the
44
+ * entry, which takes the whole web client boot down. Optional reads go through
45
+ * {@link Context.get}.
46
+ */
47
+ export declare const inject: string[];
48
+ /**
49
+ * Register the browser half's surfaces. Every registration returns a disposer and
50
+ * Cordis runs them on fiber disposal, which is what keeps HMR and plugin
51
+ * disabling free of "already registered" failures.
52
+ * @param ctx - client root context.
53
+ */
54
+ export declare function apply(ctx: Context): void;
55
+ /**
56
+ * The sidebar panel.
57
+ *
58
+ * `./sidebar-tab.ts` already bound the two translate seats — the UI namespace and
59
+ * the host-message one — before calling this, so the adapter has nothing left to
60
+ * do but name the component and let React render it as an element rather than as
61
+ * a bare call.
62
+ * @param props - the body's props, seats included.
63
+ * @returns the panel element.
64
+ */
65
+ export declare function LocalizedPanel(props: SidebarTabBodyProps): ReactNode;
66
+ /**
67
+ * The settings popup's content, with the same two seats.
68
+ *
69
+ * The popup is an entry of the frame-wide floating layer, so its chrome has to
70
+ * repaint on a language switch exactly like the tab's: the seats are bound per
71
+ * render by `./sidebar-tab.ts`, and this adapter only names the component.
72
+ * @param props - the popup's props, seats included.
73
+ * @returns the settings panel element.
74
+ */
75
+ export declare function LocalizedSettings(props: SidebarSettingsProps): ReactNode;
76
+ //#endregion
77
+ //# sourceMappingURL=client.d.ts.map