relay-dsh-plugin-manager 0.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [0.1.0-rc.1] - 2026-08-26
+
+### Added
+
+- Conversation-first DSH plugin discovery and lifecycle management.
+- One `/plugins` command and two model tools.
+- npm and GitHub discovery with immutable install-source resolution.
+- Confirmed install, remove, update, enable, disable, and restart operations.
+- Loader HMR verification, restart fallbacks, rollback, and operation tracking.
+- Versioned search-provider extension registry.
+- Unit, integration, package E2E, and opt-in live Codex acceptance coverage.
+
+[0.1.0-rc.1]: https://github.com/yangbobo2021/relay-dsh-plugin-manager/releases/tag/v0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yangbobo2021 and Relay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Relay DSH Plugin Manager
+
+Conversation-first plugin discovery and lifecycle management for the DeepSeek
+Harness `web` profile. The package has no settings UI and registers no public
+management HTTP routes.
+
+## Conversation Surface
+
+The bundle contributes one human command and two model tools:
+
+- `/plugins [request]` sends the request to the current Agent;
+- `plugin_discover` lists, searches, inspects, and reports status;
+- `plugin_manage` plans, executes, polls, and cancels mutations.
+
+Ordinary natural-language requests use the same tools. Every install, update,
+remove, enable, disable, or restart is a two-stage operation: the Agent first
+shows a plan, then uses its one-use token only after a later explicit user
+confirmation. The token is bound to that DSH conversation, and same-turn or
+cross-conversation execution is rejected in code.
+
+Examples:
+
+```text
+/plugins 找一个能连接飞书的插件
+/plugins 安装 example-dsh-plugin
+卸载 example-dsh-plugin
+列出当前插件以及是否需要重启
+```
+
+## Installation
+
+Install with the DSH instance that will run the profile:
+
+```sh
+dsh plugin --profile web add --save-exact relay-dsh-plugin-manager@0.1.0-rc.1
+```
+
+The official DSH command adds the package to profile dependencies and mounts
+both bundle rows. Restart DSH after the manager itself is first installed.
+
+## Behavior
+
+- npm sources resolve to an exact version and SHA-512 registry integrity.
+- GitHub sources resolve to a full commit before execution.
+- Package mutations call the current official DSH CLI with argv arrays.
+- New simple insert-only bundles may activate without restart; complex bundles
+  and updates report `restartRequired`.
+- Enable/disable owns only exact Loader override rows written by this manager.
+- Disabling a plugin used by the current conversation can interrupt that turn;
+  use another backend or Session when continuity matters.
+- Mutations are serialized, cancellable, and retain pollable terminal status.
+- Automatic restart is a separate confirmed operation and is disabled for a
+  detected systemd main process unless explicitly configured.
+
+Set `allowRestart: false` on the `relay-plugin-manager-host` bundle row to
+disable automatic restart in other deployments as well.
+
+## Search Extensions
+
+Installed Host plugins can inject `pluginSearch`, require `apiVersion === 1`,
+and register a provider:
+
+```ts
+export const inject = ['pluginSearch']
+
+export function apply(ctx) {
+  ctx.pluginSearch.register({
+    id: 'internal-catalog',
+    async search({ query, maxResults, signal }) {
+      return lookupCatalog(query, { maxResults, signal })
+    },
+  })
+}
+```
+
+Providers return npm/GitHub candidates only. Core inspection, immutable source
+resolution, confirmation, installation, rollback, and activation are not
+extension points.
+
+## Verification
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+npm run acceptance:live:codex
+npm run release:dry-run
+```
+
+`verify` runs type checking, unit/integration tests, the production build, and
+a local package E2E that installs the tarball through the immutable official
+DSH checkout. The live command additionally uses the public npm/GitHub services
+and the real `relay-dsh-plugin-codex` package. The RC dry run uses npm's
+`next` dist-tag. See [SPEC.md](./SPEC.md) and
+[docs/acceptance.md](./docs/acceptance.md) for the release contract and
+traceability matrix. The current real-session release record is
+[docs/acceptance/release-candidate-2026-08-26.md](./docs/acceptance/release-candidate-2026-08-26.md).
+Tag-triggered npm publication is defined in
+[docs/releasing.md](./docs/releasing.md).
+
+## Repository Boundary
+
+This is an independently installable package. It imports no Relay parent or
+KeySync implementation code. The local KeySync prototype handoff was used as
+reference material and is intentionally excluded from both git and the npm
+package.

package/SPEC.md

@@ -0,0 +1,85 @@
+# Relay DSH Plugin Manager Specification
+
+Status: implementation contract
+Target package: `relay-dsh-plugin-manager`
+Target profile: the running `web` profile
+
+## Product Contract
+
+Relay DSH Plugin Manager is a conversation-first, independently installable
+DeepSeek Harness bundle. It discovers and manages DSH profile plugins without a
+management UI or public management HTTP routes.
+
+The user may enter `/plugins <request>` or describe the same request in ordinary
+conversation. Both paths use the same model-facing tools and Host management
+service.
+
+## Requirements
+
+| ID | Requirement |
+|---|---|
+| PM-001 | Register exactly one human command, `/plugins [request]`. It submits the request to the receiving Agent; it does not implement a second command-only management path. |
+| PM-002 | Keep the model surface compact: one discovery tool and one management tool. Natural-language and slash-command requests use these tools. |
+| PM-003 | List profile dependencies with installed source, bundle membership, package-level enablement, runtime phase, and pending-restart state. |
+| PM-004 | Provide a versioned `ctx.pluginSearch` registry. Other installed plugins may register abortable search providers. Providers discover candidates only and cannot install or mutate the profile. |
+| PM-005 | Search all registered providers concurrently with bounded results, timeout/cancellation, provenance, provider-error isolation, and repository/package-identity deduplication. |
+| PM-006 | Ship npm and GitHub search providers. Preserve a syntactically valid exact npm package-name query even when npm search ranking omits it. Search results are inspected before being reported as installable DSH plugins. |
+| PM-007 | Accept only core-owned npm and GitHub install-source types. Resolve npm to an exact semantic version with registry integrity and GitHub to a full 40-character commit. |
+| PM-008 | Inspect the resolved package manifest and require a valid package name plus a DSH surface (`dsh.bundle.patch` or `dsh.client`). Search providers cannot bypass this validation. |
+| PM-009 | Every install, remove, update, enable, disable, or restart starts with an immutable plan. A later execute call requires the unexpired, one-use confirmation token returned by that plan. The token is bound to the planning DSH Session and cannot execute until that Session contains a newer user message; the original request is mechanically not confirmation. Execution also refuses a stale plan when the target profile dependency changed after planning. |
+| PM-010 | Install and update through argv-only invocation of the currently running DSH CLI: `dsh plugin --profile web add --save-exact <immutable-source>`. Never build a shell command string. |
+| PM-011 | Remove through argv-only `dsh plugin --profile web remove <package>`. Verify dependency and bundle postconditions and reconcile a half-removed profile conservatively. |
+| PM-012 | Enable and disable are package-level projections over owned Cordis Loader entries. Persist manager-owned `disabled` overrides in the profile patch, report `mixed` or `unknown` when ownership is not safely reducible, and never disable the manager itself or protected DSH infrastructure. A disable plan warns that conversations using the target plugin may be interrupted. |
+| PM-013 | Attempt restart-free activation for newly installed client-only packages and bundles whose patches contain only plain insert rows. Attempt live disposal for removals. Otherwise report `restartRequired` with a concrete reason. |
+| PM-014 | Enable/disable changes use Loader HMR and normally require no restart. A failed or unverifiable live transition reports pending restart rather than claiming success. |
+| PM-015 | Mutations run as tracked operations with stable ids, progress snapshots, terminal exit state, cooperative cancellation, and one active mutation at a time. |
+| PM-016 | Restart is a separately planned operation. When allowed, relaunch the exact current DSH entry/argv/environment through a detached helper, then stop the old process. Refuse automatic restart under a detected service supervisor or explicit disable setting. |
+| PM-017 | Snapshot the profile manifest before package mutations. Restore failed install/update manifest residue; detect and reconcile a remove that deleted package files before pnpm failed. Never report success before dependency source, installed package identity/version, DSH surface, and bundle-membership postconditions pass. |
+| PM-018 | Reject unsafe source tokens, flags, whitespace/control characters, shell metacharacters, unsupported URL hosts, ambiguous package names, and mutable execution sources. Build scripts remain governed by pnpm/DSH and are never silently authorized. |
+| PM-019 | Expose no public plugin-management HTTP routes and impose no client-address, Origin, CORS, or loopback policy. The callable surface is the in-process DSH command/tool plane. |
+| PM-020 | Remain independently installable. Do not import Relay parent implementation code or KeySync implementation code. Runtime interactions use DSH/Cordis public services and the official CLI. |
+
+## Command Grammar
+
+Only `/plugins` is registered.
+
+- `/plugins` submits a request to list installed plugins.
+- `/plugins <text>` submits `<text>` as a plugin-management request.
+- The command does not parse install/remove synonyms. The Agent interprets the
+  same natural language that it would receive without the slash command.
+
+This keeps command discovery and persistent prompt cost small while avoiding
+behavior drift between direct commands and conversation.
+
+## Model Tool Contract
+
+### `plugin_discover`
+
+Read-only actions: `list`, `search`, `inspect`, `status`.
+
+### `plugin_manage`
+
+State-changing workflow actions: `plan`, `execute`, `status`, `cancel`.
+`plan` carries one operation from `install`, `remove`, `update`, `enable`,
+`disable`, or `restart`. `execute` accepts only a confirmation token.
+
+## Search Extension Contract
+
+A search provider registers a stable id and an abortable `search()` function.
+It returns typed npm/GitHub candidates with provenance and optional local score.
+The manager owns inspection, immutable resolution, deduplication, ranking,
+confirmation, installation, rollback, activation, and restart.
+
+Provider scores are not globally comparable. The manager uses them only within
+one provider before deterministic cross-provider ordering.
+
+## Explicit Non-Goals
+
+- Settings page, dashboard, or any other management UI.
+- Public management REST/HTTP endpoints.
+- Provider-defined installers, shell commands, or arbitrary pnpm arguments.
+- Arbitrary tarball, filesystem, SSH Git, or non-GitHub Git installation in the
+  first release.
+- Automatic mutation based only on a search query.
+- Automatic restart as part of install/update/remove.
+- Managing profiles other than the running `web` profile in the first release.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: relay-plugin-search-runtime
+      name: 'relay-dsh-plugin-manager/search'
+    - id: relay-plugin-manager-host
+      name: 'relay-dsh-plugin-manager'

package/docs/acceptance/live-codex-2026-08-26.md

@@ -0,0 +1,67 @@
+# Live Codex Plugin Acceptance - 2026-08-26
+
+## Scope
+
+Opt-in live-network acceptance of `relay-dsh-plugin-codex` through the plugin
+manager implementation. The run used two fresh temporary `DSH_HOME` roots and
+the immutable official DSH checkout. Both temporary roots were removed after
+the run.
+
+Command:
+
+```sh
+npm run acceptance:live:codex
+```
+
+## Environment
+
+| Item | Value |
+|---|---|
+| Date/time zone | 2026-08-26, Asia/Shanghai |
+| Node | `v25.5.0` |
+| npm | `11.8.0` |
+| pnpm | `11.19.0` |
+| Official DSH commit | `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e` |
+| Codex plugin repository commit | `56324ecd9f2df4c172af2967fb347517d0770270` |
+
+The Codex plugin checkout was clean after acceptance. The official DSH checkout
+retained its pre-existing untracked development symlink
+`packages/core/tools/dsh-tools` (created 2026-08-25); the acceptance did not
+create or modify it.
+
+## Source Evidence
+
+| Source | Resolved immutable value |
+|---|---|
+| npm | `relay-dsh-plugin-codex@0.1.2` |
+| npm integrity | `sha512-UD3Ud3zTsxRY/0ZlLsAqbAopXb7fPY5zXjefMRWsAqG+wBaZMNSrYd5XpI453xBe8M/KdNFdae+Ha3HNI+aQ4w==` |
+| GitHub | `github:yangbobo2021/relay-dsh-plugin-codex#56324ecd9f2df4c172af2967fb347517d0770270` |
+
+The real search result merged npm and GitHub provenance into one candidate and
+recommended the exact npm source. Initial execution exposed that npm Registry
+ranking omitted the exact package from the bounded keyword result; PM-006 was
+fixed so an exact valid npm package-name query remains a candidate and still
+passes full core inspection.
+
+## Lifecycle Evidence
+
+| Scenario | Result |
+|---|---|
+| npm search and inspection | Passed; exact semver, SHA-512 integrity, repository, bundle patch |
+| GitHub search and inspection | Passed; full 40-character commit and bundle patch |
+| npm install through official DSH CLI | Passed; dependency, installed identity/version, DSH surface, and one bundle verified |
+| Installed status | Passed; bundle enabled and restart required outside the booted process |
+| `--dump-config` | Passed; `relay-codex-host` present |
+| Real `dsh web --no-open --port 0` boot | Passed; readiness URL returned HTTP 200 |
+| Disable | Passed; manager-owned `relay-codex-host` override persisted |
+| Enable | Passed; only manager-owned override removed |
+| Update | Passed; exact official add path and restart boundary verified |
+| npm remove | Passed; dependency and bundle absent |
+| Immutable GitHub install | Passed; exact commit dependency and bundle verified |
+| GitHub remove | Passed; dependency and bundle absent |
+
+The final successful RC boot URL used a random ephemeral port
+(`http://127.0.0.1:52149`) and the process was terminated cleanly. No model
+request, Codex conversation, or automatic DSH restart was performed in this
+script; real conversation and Loader HMR evidence is recorded separately in
+[`release-candidate-2026-08-26.md`](./release-candidate-2026-08-26.md).

package/docs/acceptance/release-candidate-2026-08-26.md

@@ -0,0 +1,51 @@
+# Release Candidate Acceptance - 2026-08-26
+
+## Scope
+
+Release acceptance for `relay-dsh-plugin-manager@0.1.0-rc.1` in an isolated
+real DSH Web profile. The manager was installed from its packed tarball and
+`relay-dsh-plugin-codex@0.1.2` was installed from npm through the official
+DSH CLI.
+
+## Environment
+
+| Item | Value |
+|---|---|
+| Official DSH commit | `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e` |
+| Codex plugin | `relay-dsh-plugin-codex@0.1.2` |
+| Codex CLI | `0.149.0-alpha.4.3` |
+| Codex model route | `relay-codex/gpt-5.4-mini` |
+| Profile | fresh temporary `web` profile |
+
+No production DSH profile or repository checkout was modified.
+
+## Conversation Evidence
+
+| Scenario | Result |
+|---|---|
+| Real Web boot | Passed; DSH returned a readiness URL and HTTP 200 |
+| Agent preset roster | Passed; `relay-codex` was available |
+| Compact model surface | Passed; request header contained exactly `plugin_discover` and `plugin_manage` |
+| Slash command | Passed; `/plugins 搜索 Codex 插件` produced merged live search results |
+| Natural language | Passed; a Chinese discovery request ran on the real Codex backend and returned inspected DSH candidates |
+| No mutation on search | Passed |
+| Same-turn confirmation | Passed; “disable and confirm now” produced a plan, execution was rejected, and `cordis.patch.yml` stayed byte-identical |
+| Later confirmation | Passed; a later `确认禁用` message wrote the owned `relay-codex-host` disabled row |
+| Loader hot unload | Passed; the Codex provider was disposed without restarting DSH |
+| Loader hot reload | Passed; removing the temporary acceptance override restored the Codex provider without restarting DSH; a new real Codex Session replied `CODEX_HMR_OK` |
+
+## Review Finding
+
+Disabling the backend serving the executing conversation interrupts that turn
+when Loader HMR disposes the provider. The profile mutation is successful and
+DSH itself does not restart, but the conversation cannot deliver a final
+success message from the disabled backend.
+
+The release contract, plan output, README, technical design, and integration
+test now warn about this behavior. Continuity-sensitive disable operations
+should be confirmed from another backend or Session.
+
+## Cleanup
+
+The temporary override was removed, the Codex provider was verified live again,
+and the temporary DSH process and profile were deleted after the release run.

package/docs/acceptance.md

@@ -0,0 +1,81 @@
+# Delivery Acceptance
+
+This matrix is the release contract. Tests name the relevant `PM-*` ids.
+
+## Scenario Matrix
+
+| Scenario | Requirement coverage | Automated evidence |
+|---|---|---|
+| A-001 `/plugins` without arguments submits one list request to the receiving Agent | PM-001, PM-002 | command unit/integration |
+| A-002 `/plugins install X` and ordinary `install X` expose the same two model tools and management workflow | PM-001, PM-002 | command/tool integration |
+| A-003 list an empty and populated profile with bundle, enablement, runtime, and restart fields | PM-003 | profile unit + manager integration |
+| A-004 external search provider registers, returns results, disposes, times out, fails, and cancels without breaking siblings | PM-004, PM-005 | search-registry unit |
+| A-005 npm and GitHub search results are inspected, exact npm package names survive ranking omission, invalid bundles are dropped, aliases deduplicated, and provenance retained | PM-005, PM-006, PM-008 | provider/search integration with fake network + live Codex acceptance |
+| A-006 npm bare name resolves to exact semver/integrity; mutable or malformed npm specs cannot execute | PM-007, PM-008, PM-018 | source unit |
+| A-007 GitHub URL/slug resolves to a full commit; non-GitHub URLs and unsafe refs are rejected | PM-007, PM-008, PM-018 | source unit |
+| A-008 install plan performs no mutation, returns digest/token/expiry, binds the token to its Session, and rejects same-turn/cross-session execution so the original request is not confirmation | PM-009 | plan unit + tool integration |
+| A-009 token is one-use, expires, cannot substitute another operation, rejects stale profile state, and execution creates one tracked operation | PM-009, PM-015 | plan/operation unit + manager integration |
+| A-010 install invokes exact official argv, verifies dependency source, installed identity/version, DSH surface, and one bundle membership, then reports hot or restart-required activation | PM-010, PM-013, PM-017 | fake-CLI integration |
+| A-011 failed install restores manifest residue and never reports installed | PM-017 | fake-CLI integration |
+| A-012 update resolves an immutable newer source, invokes exact add argv, verifies installed spec, and supports rollback reporting | PM-009, PM-010, PM-017 | fake-CLI integration |
+| A-013 remove invokes exact official argv, verifies absence, live-disposes when possible, and reconciles half-removal | PM-011, PM-013, PM-017 | fake-CLI integration |
+| A-014 disable warns about active-conversation interruption, writes only manager-owned patch rows, HMR-verifies state, survives reload, and enable removes only owned rows | PM-012, PM-014 | plan + profile/loader integration + real DSH walkthrough |
+| A-015 mixed, unknown, user-patch conflict, self-disable, and protected-infrastructure disable are refused or reported accurately | PM-012, PM-014 | enablement unit/integration |
+| A-016 simple insert bundle hot-mounts; complex/config patch, unavailable Include, timeout, and thrown activation require restart | PM-013 | hot-runtime unit/integration |
+| A-017 operation progress is bounded, a concurrent mutation is refused, cancellation reaches the runner, and terminal status is retained | PM-015 | operation integration |
+| A-018 restart requires a separate plan, is refused under supervisor/disabled config, and schedules exact invocation otherwise | PM-016 | restart unit |
+| A-019 package exposes no client entry or management HTTP route and registers exactly one command/two tools | PM-001, PM-002, PM-019 | package/loader integration |
+| A-020 packed tarball installs through official DSH CLI into a clean profile and contributes both Host rows without modifying DSH | PM-020 | local checkout E2E + CI against the locked published DSH runtime fixture |
+| A-021 optional live-network acceptance discovers the real Codex plugin through npm/GitHub, installs npm and immutable GitHub sources in isolated DSH homes, boots the npm-installed Web profile, exercises enable/disable/update, and removes both | PM-003-PM-017 | `npm run acceptance:live:codex` |
+| A-022 a real DSH Web Session exposes both tools, serves slash-command and natural-language search, rejects same-turn confirmation, executes later confirmation, and observes Loader HMR without restarting DSH | PM-001, PM-002, PM-009, PM-012, PM-014 | release-candidate walkthrough with real Codex backend |
+
+## Test Layers
+
+### Unit
+
+Pure parsing, source resolution, search registry, deduplication, plans, profile
+projection, patch ownership, hot-patch classification, operation state, and
+restart policy. Network, clock, random values, process spawning, and Loader
+entries are injected fakes.
+
+### Integration
+
+Use temporary profiles and an in-process fake official CLI runner that performs
+the same manifest/bundle changes DSH owns. Exercise real manager orchestration,
+postconditions, rollback, operation polling, cancellation, Loader state, actual
+DSH command/tool registries, and model-tool execution.
+
+### E2E
+
+Build and pack the package, install the tarball through an official DSH CLI
+into a new temporary `web` profile, and run `--dump-config`. Local acceptance
+uses the immutable official checkout; CI and release acceptance use the
+published DSH version locked under `test/fixtures/dsh-runtime`. Assert package
+dependency, bundle membership, search-service row, manager row, and an
+unchanged upstream Git status when a checkout is present.
+
+### Optional release acceptance
+
+Real npm/GitHub requests are opt-in because they are network-dependent. They
+use isolated temporary DSH homes and pinned public fixtures. The release record
+must capture DSH version/commit, Node, pnpm, exact npm version, exact GitHub
+commit, and sanitized output.
+
+The current evidence record is
+[`live-codex-2026-08-26.md`](./live-codex-2026-08-26.md). The real
+conversation and Loader record is
+[`release-candidate-2026-08-26.md`](./release-candidate-2026-08-26.md).
+
+## Review Gates
+
+After each implementation slice:
+
+1. Compare changed behavior to every affected `PM-*` row.
+2. Confirm each positive path has mutation/postcondition assertions.
+3. Confirm rejection, cancellation, partial failure, and retry behavior.
+4. Run the smallest affected suite and inspect that it actually reaches the
+   intended boundary rather than only testing a mock's return value.
+5. Update this matrix before accepting behavior that was not previously named.
+
+Release requires typecheck/build, all unit/integration tests, local package E2E,
+and a final SPEC-code-test traceability review.

package/docs/releasing.md

@@ -0,0 +1,46 @@
+# Release Contract
+
+## Version And Tag
+
+- Commit the intended version in both `package.json` and
+  `package-lock.json`.
+- A release tag must be exactly `v<package version>`.
+- Stable versions publish to npm's `latest` dist-tag.
+- SemVer prereleases publish to `next`.
+- The tagged commit must be reachable from `main`.
+
+`scripts/release-metadata.mjs` is the executable source of truth.
+
+## Publication Gates
+
+The tag workflow installs dependencies without dependency lifecycle scripts,
+validates the tag, verifies against the official published DSH CLI locked in
+`test/fixtures/dsh-runtime`, runs the complete test/build/package acceptance
+chain, audits production dependencies, inspects the tarball, refuses to
+republish an existing version, and verifies the resulting npm dist-tag.
+
+## First Publication
+
+The first publication uses a short-lived granular npm token stored as the
+repository's `NPM_TOKEN` Actions secret. The token must allow publishing this
+public package and satisfy the npm account's 2FA policy.
+
+After the first version exists, configure its npm Trusted Publisher:
+
+- provider: GitHub Actions
+- organization or user: `yangbobo2021`
+- repository: `relay-dsh-plugin-manager`
+- workflow filename: `release.yml`
+- allowed action: `npm publish`
+
+Then remove the `NPM_TOKEN` repository secret. The workflow already grants
+`id-token: write` and uses an OIDC-capable npm CLI.
+
+## Release
+
+```bash
+git push origin main
+git push origin v<version>
+```
+
+Do not move or reuse a published version tag. npm versions are immutable.

package/docs/technical-design.md

@@ -0,0 +1,153 @@
+# Technical Design
+
+## Boundaries
+
+The bundle mounts two Host entries:
+
+1. `PluginSearchRuntime`, the provider registry (`ctx.pluginSearch`).
+2. The manager Host plugin, which owns built-in providers, profile operations,
+   model tools, and `/plugins`.
+
+There is no browser client entry and no management HTTP route.
+
+## Request Flow
+
+```text
+natural language --------------------------+
+                                            v
+/plugins request -> Agent steering -> plugin_discover / plugin_manage
+                                            |
+                                            v
+                                    PluginManager core
+                          +-----------------+------------------+
+                          |                                    |
+                   PluginSearchRuntime                  Operation runtime
+                          |                                    |
+                built-in / external providers         official DSH CLI
+                                                               |
+                                          postcondition -> hot activation
+                                                               |
+                                                     restart fallback
+```
+
+## Compact Conversation Surface
+
+`/plugins` deliberately forwards its unstructured text to the Agent. A direct
+command parser would duplicate the model's language understanding and create a
+second confirmation implementation.
+
+Two model tools are sufficient:
+
+- discovery is read-only and may run without confirmation;
+- management separates planning from execution and also owns operation status
+  and cancellation.
+
+The tool descriptions instruct the model to show a plan and wait for a later
+affirmative user message before calling `execute`. The conversation adapter
+also binds each token to the Agent Session and its latest `user/message` seq at
+planning time. Same-turn and cross-session execution fail before the manager
+can consume the token.
+
+## Source Resolution
+
+The core recognizes only this closed union:
+
+```ts
+type PluginSource =
+  | { kind: 'npm'; package: string; version?: string }
+  | { kind: 'github'; owner: string; repo: string; ref?: string }
+```
+
+npm metadata provides the exact version, integrity, manifest, and repository
+identity. GitHub's API resolves a ref/default branch to a full commit; the raw
+manifest at that commit is then validated. Execution receives only the
+immutable normalized spec.
+
+## Search Providers
+
+Providers are trusted installed code but their result data remains untrusted.
+Registration validates provider identity. Search:
+
+- calls providers concurrently;
+- passes one AbortSignal;
+- isolates provider failures;
+- normalizes typed sources;
+- inspects candidates through the core source resolver;
+- merges npm/GitHub aliases by canonical repository identity;
+- returns provenance and rejected-provider diagnostics.
+
+For an exact npm package-name query, the npm provider inserts that name as a
+candidate when the registry search ranking omits it. This is not trusted as an
+installation result: the same core registry metadata, integrity, manifest, and
+DSH-surface inspection still runs before it can be returned.
+
+No provider callback participates after discovery.
+
+## Confirmation Plans
+
+Plans live in memory for ten minutes. Each carries:
+
+- operation and profile;
+- package/source and immutable target where applicable;
+- impact/restart expectations;
+- creation/expiry timestamps;
+- SHA-256 digest and a random one-use confirmation token.
+
+Execution atomically consumes the token before starting an operation. Retrying
+requires a new plan. Immediately before operation creation, the manager also
+compares the planned dependency source with the current profile and refuses a
+stale plan. This prevents confirmation replay, plan substitution, and mutation
+after an out-of-band profile change.
+
+## Package Mutations
+
+The runner reuses the current DSH installation. When the current Node entry is
+an existing file, it invokes `process.execPath <current-entry> plugin ...`;
+otherwise it uses explicit `DSH_EXECUTABLE` or the `dsh` command. Arguments are
+always an array. Windows shell fallback is limited to a bare `.cmd` executable.
+
+Only one mutation runs at once. Output is bounded and exposed as progress.
+Cancellation sends SIGTERM and later SIGKILL if needed.
+
+After add succeeds, the manager verifies the saved immutable dependency, the
+installed package name and exact npm version, a declared DSH surface, and exact
+bundle membership before reporting success. A failed check restores the saved
+profile manifest and reports a failed operation.
+
+## Enablement
+
+DSH has Loader-entry enablement, not a native package-level boolean. The manager
+derives package ownership from the package's bundle patch insert rows.
+
+Disable appends manager-owned `{ id, disabled: true }` overrides to the profile
+patch and records ownership under `.relay-plugin-manager/state.json`. Enable
+removes only exact overrides still owned by that state. Existing user-authored
+rows are never overwritten. HMR verification reads current Loader entries.
+
+Disabling a plugin that supplies the backend or another capability used by the
+executing conversation can interrupt that turn when Loader HMR disposes it.
+Disable plans state this explicitly so continuity-sensitive operations can be
+confirmed from another backend or Session.
+
+Self and protected infrastructure ids/names cannot be disabled.
+
+## Restart-Free Activation
+
+For a new bundle, the manager may create a process-local Include subtree when
+the bundle patch consists only of insert rows containing `id` and `name`.
+Client-only packages receive a no-op Host shim so the client module can be
+served. Complex patches, activation timeout, missing Include support, and
+runtime failure produce a restart-required result.
+
+Temporary hot inputs are deleted at manager startup. Durable bundle membership
+remains owned by the profile manifest and becomes authoritative at next boot.
+
+## Restart
+
+Restart is never chained automatically after another operation. A confirmed
+restart starts a detached helper which waits for the old process to exit,
+replays the exact DSH invocation, and then terminates the old process.
+
+Automatic restart is unavailable when explicitly disabled or when the running
+process is detected as a systemd-owned main process. The user must then use the
+deployment supervisor.

package/lib/errors-BGx4K2uq.js

@@ -0,0 +1,18 @@
+//#region src/errors.ts
+var PluginManagerError = class extends Error {
+	code;
+	details;
+	constructor(code, message, details) {
+		super(message);
+		this.name = "PluginManagerError";
+		this.code = code;
+		this.details = details;
+	}
+};
+function fail(code, message, details) {
+	throw new PluginManagerError(code, message, details);
+}
+//#endregion
+export { fail as t };
+
+//# sourceMappingURL=errors-BGx4K2uq.js.map