@auggieteo/dsh-mcp-adapter 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v0.2.2] - 2026-09-06
+
+### Added
+
+- `skillInstall` Config field (`file` by default, `runtime`, or `off`) controlling how the bundled `mcp-adapter` agent skill is installed. `file` copies `skills/mcp-adapter/SKILL.md` verbatim to `$DSH_HOME/skills/mcp-adapter/SKILL.md` at startup (atomic temp-file-then-rename write, never a symlink), so the DSH filesystem skill provider lists it under Settings > Skills > DSH skills. `runtime` keeps the previous in-memory registration; `off` installs nothing. The mode is read once at Adapter startup.
+
+### Changed
+
+- The bundled agent skill now installs as a real file by default instead of registering only in memory. The installed file is never overwritten: an identical file is left untouched, and a file edited by a human wins with one Host warning naming the installed path and the package version — delete `$DSH_HOME/skills/mcp-adapter/` and restart DSH to refresh it from the package. A failed file install (for example a read-only `$DSH_HOME`) falls back to the runtime registration with a warning; the skill stays a convenience and never throws.
+
 ## [v0.2.1] - 2026-09-06
 
 ### Added
@@ -56,5 +66,6 @@ Everything from v0.1.2 through this release: the six deferred v1 features (#8–
 
 Initial releases of the Adapter through v1 issues #1–#7: proxy-first tool surface, Config in the DSH settings namespace, promotion registry, lazy lifecycle, output guard, settings page, and the `/mcp-adapter` RPC channel. See [docs/verification/v1-e2e.md](docs/verification/v1-e2e.md).
 
+[v0.2.2]: https://github.com/auggie246/dsh-mcp-adapter/compare/v0.2.1...v0.2.2
 [v0.2.0]: https://github.com/auggie246/dsh-mcp-adapter/compare/v0.1.2...v0.2.0
 [v0.1.2]: https://github.com/auggie246/dsh-mcp-adapter/releases/tag/v0.1.2

package/README.md

@@ -130,10 +130,13 @@ mcp:
       url: https://mcp.example.com/other
       auth: oauth
       scopes: [repo, read:org]
+  skillInstall: file
 ```
 
 Each Server configures exactly one Transport: `command` for stdio, or `url` for streamable HTTP with SSE fallback. Adapter extension fields are `auth` (`headers` by default, or `oauth` for HTTP Servers), `scopes` (OAuth scopes, requires `auth: oauth`), `disabled`, `autoAllow`, `lifecycle` (`lazy`, `eager`, `keep-alive`, or `lazy-keep-alive`; default `lazy`), `idleTimeoutMinutes` (default `10`), and `promotedTools`.
 
+The one top-level Adapter field is `skillInstall` (`file` by default, `runtime`, or `off`); see [Agent skill](#agent-skill).
+
 The schema rejects unknown fields and invalid transport combinations before they reach `$DSH_HOME/settings.yaml`. Each `env` and `headers` value has the DSH `secret` schema role. Wire views retain each key and redact its value.
 
 #### Workspace Config layer
@@ -211,7 +214,13 @@ The SDK transports refresh expired access tokens through the stored refresh toke
 
 ### Agent skill
 
-The package bundles a model-facing skill in `skills/mcp-adapter/SKILL.md`. When the DSH `skills` service is present, the Adapter registers it at startup as a runtime skill named `mcp-adapter`, so agents learn the search → describe → call workflow, how to read failure messages (including the OAuth sign-in hint), and which commands belong to the human. The frontmatter drives routing; edit the file to change the guidance, and a DSH restart picks the edit up.
+The package bundles a model-facing skill in `skills/mcp-adapter/SKILL.md`, so agents learn the search → describe → call workflow, how to read failure messages (including the OAuth sign-in hint), and which commands belong to the human. The top-level `skillInstall` Config field controls how the Adapter installs it; the mode is read once at Adapter startup, so a change takes effect on the next DSH restart.
+
+- `file` (default): on startup the Adapter copies the bundled `SKILL.md` verbatim to `$DSH_HOME/skills/mcp-adapter/SKILL.md` (an atomic temp-file-then-rename write, never a symlink). The DSH filesystem skill provider discovers the file, so the skill shows under **Settings > Skills > DSH skills** and joins the session catalog without a restart of an already-running session. When the file install fails, the Adapter falls back to the runtime registration below and logs one warning.
+- `runtime`: the Adapter registers the skill in memory on the DSH `skills` service only. It reaches agents but never appears on the Settings > Skills page.
+- `off`: the Adapter installs no skill.
+
+The installed file is never overwritten. If `$DSH_HOME/skills/mcp-adapter/SKILL.md` already exists, your edit wins: an identical file is left untouched, and a differing file gets one Host warning naming the installed path and the package version. To refresh the installed copy from the package, delete `$DSH_HOME/skills/mcp-adapter/` and restart DSH. Editing the installed file changes what the session catalog serves; the edit survives plugin restarts.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auggieteo/dsh-mcp-adapter",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "DSH plugin connecting the agent to MCP servers through one mcp proxy tool and a Settings > MCP page.",
   "type": "module",
   "license": "MIT",

package/src/host/index.js

@@ -19,9 +19,13 @@ export const inject = []
 
 export function apply(ctx) {
   // The bundled agent skill is independent of every other Adapter feature: a
-  // deployment without the skills service simply gets no skill entry.
-  ctx.inject(['skills'], (skillCtx) => installMcpSkill(skillCtx))
+  // deployment without the skills service simply gets no skill entry. Sibling
+  // inject fibers run in registration order while the services exist, so the
+  // settings callback reads `skillInstall` before the skills callback runs;
+  // without the settings service the skill module's 'file' default applies.
+  let skillInstall
   installMcpSettings(ctx, (settingsCtx, scope) => {
+    skillInstall = scope.get()?.skillInstall
     const layeredScope = installWorkspaceLayer(settingsCtx, scope)
     settingsCtx.inject(['timer'], (managerCtx) => {
       const store = createFileTokenStore()
@@ -59,6 +63,7 @@ export function apply(ctx) {
       })
     })
   })
+  ctx.inject(['skills'], (skillCtx) => installMcpSkill(skillCtx, { skillInstall }))
 }
 
 export * from './commands.js'

package/src/host/settings.js

@@ -69,9 +69,18 @@ export const McpSettingsSchema = z.object({
     .dict(McpServerSchema)
     .default({})
     .description('Global MCP servers, keyed by their unique server name.'),
+  skillInstall: z
+    .union(['file', 'runtime', 'off'])
+    .default('file')
+    .description(
+      'How the bundled mcp-adapter agent skill is installed: file (copy to '
+      + '$DSH_HOME/skills/mcp-adapter/ so Settings > Skills lists it; an '
+      + 'existing file is never overwritten), runtime (register in memory '
+      + 'only), or off (no skill). Read once at Adapter startup.',
+    ),
 })
 
-const TOP_LEVEL_KEYS = new Set(['mcpServers'])
+const TOP_LEVEL_KEYS = new Set(['mcpServers', 'skillInstall'])
 const SERVER_KEYS = new Set([
   'command',
   'args',

package/src/host/skill.js

@@ -1,4 +1,12 @@
-import { readFileSync as defaultReadFileSync } from 'node:fs'
+import {
+  mkdirSync as defaultMkdirSync,
+  readFileSync as defaultReadFileSync,
+  renameSync as defaultRenameSync,
+  writeFileSync as defaultWriteFileSync,
+} from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir as defaultHomedir } from 'node:os'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { errorMessage } from './errors.js'
@@ -7,8 +15,26 @@ import { errorMessage } from './errors.js'
 export const SKILL_DIR = fileURLToPath(new URL('../../skills/mcp-adapter/', import.meta.url))
 
 const SKILL_FILE = 'SKILL.md'
+const SKILL_TEMP_FILE = '.SKILL.md.tmp'
 const SKILL_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
 
+/** The Adapter package version, read lazily so a missing manifest never breaks load. */
+function packageVersion() {
+  try {
+    return createRequire(import.meta.url)('../../package.json').version
+  } catch {
+    return 'unknown'
+  }
+}
+
+/**
+ * Resolve the DSH skills root the same way the harness does: `$DSH_HOME`
+ * when set, otherwise `.dsh` under the OS home directory.
+ */
+export function resolveSkillsRoot(env = process.env, homedir = defaultHomedir) {
+  return join(env.DSH_HOME ?? join(homedir(), '.dsh'), 'skills')
+}
+
 /**
  * Split one `SKILL.md` into its frontmatter fields and body. The block must
  * open the file: `---`, flat `key: value` lines, then a closing `---`. Only
@@ -34,16 +60,96 @@ export function parseSkillFrontmatter(text) {
 }
 
 /**
- * Register the bundled `mcp-adapter` skill on the `skills` service so agents
- * discover how to drive the Proxy Tool. The body lives in
- * `skills/mcp-adapter/SKILL.md` next to the package root, so a human can edit
- * the wording without touching code; frontmatter still drives routing.
+ * Copy the bundled `SKILL.md` to `$DSH_HOME/skills/<name>/SKILL.md` so the
+ * filesystem skill provider (and with it Settings > Skills) discovers it.
+ * The copy is atomic — temp file in the target directory, then rename — and
+ * never a symlink or hardlink. An installed file is never overwritten: when
+ * it exists and matches, nothing happens; when it differs, the human's edit
+ * wins and one warning names the path and the package version. Returns true
+ * when the file now carries the skill (install done or already present).
+ */
+function installSkillFile(ctx, text, name, {
+  readInstalledFileSync,
+  writeFileSync,
+  mkdirSync,
+  renameSync,
+  env,
+  homedir,
+}) {
+  const warn = (reason) => {
+    ctx.logger?.warn?.(`dsh-mcp-adapter: ${reason}`)
+  }
+  const targetDir = join(resolveSkillsRoot(env, homedir), name)
+  const target = join(targetDir, SKILL_FILE)
+  let installed
+  try {
+    installed = String(readInstalledFileSync(target, 'utf8'))
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      warn(
+        `cannot read the installed skill file ${target} (${errorMessage(error)}); `
+        + 'registering the bundled skill at runtime instead',
+      )
+      return false
+    }
+  }
+  if (installed !== undefined) {
+    if (installed === text) return true
+    // The human's edit wins: leave the file untouched and treat it as the
+    // one definition for this name.
+    warn(
+      `the installed skill file ${target} differs from the bundled copy `
+      + `(dsh-mcp-adapter ${packageVersion()}); delete ${targetDir} to refresh `
+      + 'it from the package on the next start',
+    )
+    return true
+  }
+  try {
+    mkdirSync(targetDir, { recursive: true })
+    const temp = join(targetDir, SKILL_TEMP_FILE)
+    writeFileSync(temp, text, 'utf8')
+    renameSync(temp, target)
+    return true
+  } catch (error) {
+    warn(
+      `cannot install the skill file at ${target} (${errorMessage(error)}); `
+      + 'registering the bundled skill at runtime instead',
+    )
+    return false
+  }
+}
+
+/**
+ * Install the bundled `mcp-adapter` skill so agents discover how to drive the
+ * Proxy Tool. The body lives in `skills/mcp-adapter/SKILL.md` next to the
+ * package root, so a human can edit the wording without touching code;
+ * frontmatter still drives routing.
  *
- * The skill is a convenience, never a dependency: an unreadable file or bad
- * frontmatter logs a warning and registers nothing. `readFileSync` and `dir`
- * are injectable for tests.
+ * The `skillInstall` mode comes from the Adapter Config (default `'file'`).
+ * `'file'` copies the skill to `$DSH_HOME/skills/<name>/SKILL.md` and lets
+ * the filesystem provider pick it up — one definition per name, so the
+ * runtime registration is skipped. `'runtime'` registers directly on the
+ * `skills` service as before. `'off'` installs nothing.
+ *
+ * The skill is a convenience, never a dependency: an unreadable file, bad
+ * frontmatter, or a failed install logs a warning and never throws; a failed
+ * file install falls back to the runtime registration. Every filesystem
+ * access (`readFileSync` for the bundled copy, `readInstalledFileSync` for
+ * the installed one, plus `writeFileSync`, `mkdirSync`, and `renameSync`)
+ * and `dir`, `env`, and `homedir` are injectable for tests.
  */
-export function installMcpSkill(ctx, { readFileSync = defaultReadFileSync, dir = SKILL_DIR } = {}) {
+export function installMcpSkill(ctx, {
+  readFileSync = defaultReadFileSync,
+  readInstalledFileSync = defaultReadFileSync,
+  writeFileSync = defaultWriteFileSync,
+  mkdirSync = defaultMkdirSync,
+  renameSync = defaultRenameSync,
+  env = process.env,
+  homedir = defaultHomedir,
+  dir = SKILL_DIR,
+  skillInstall = 'file',
+} = {}) {
+  if (skillInstall === 'off') return undefined
   const fail = (reason) => {
     ctx.logger?.warn?.(`dsh-mcp-adapter: bundled skill unavailable (${reason})`)
     return undefined
@@ -57,7 +163,7 @@ export function installMcpSkill(ctx, { readFileSync = defaultReadFileSync, dir =
     if (typeof description !== 'string' || description === '') {
       return fail('frontmatter requires a non-empty description')
     }
-    return ctx.skills.register({
+    const register = () => ctx.skills.register({
       name,
       description,
       ...(whenToUse === undefined ? {} : { whenToUse }),
@@ -65,6 +171,15 @@ export function installMcpSkill(ctx, { readFileSync = defaultReadFileSync, dir =
       content: body,
       resourceBase: { kind: 'directory', path: dir },
     })
+    if (skillInstall !== 'runtime') {
+      const installed = installSkillFile(ctx, text, name, {
+        readInstalledFileSync, writeFileSync, mkdirSync, renameSync, env, homedir,
+      })
+      // One definition per name: the filesystem provider owns the skill once
+      // the file is in place (or the human's edit already covers it).
+      if (installed) return undefined
+    }
+    return register()
   } catch (error) {
     return fail(errorMessage(error))
   }