dsh-agent-plugins-market 0.7.2 → 0.8.1

package/lib/runtime/user-hooks.js

@@ -0,0 +1,102 @@
+/**
+ * Direct user configuration for command hooks: the Agent layout root's own
+ * hook files, mounted through the same bridge lifecycle a suite's hooks use.
+ *
+ * The files live at `~/.agents/hooks/hooks.json` and `~/.agents/hooks.json`
+ * and are read in that order, merged additively exactly like the project
+ * `.agents` layout reads them. A malformed file fails the suite closed with a
+ * diagnostic, never a thrown discovery, and the hooks carry no
+ * `projectRoot`: the bridge defaults `${CLAUDE_PROJECT_DIR}` to the calling
+ * session's workspace.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { normalizeHookDocuments, standaloneHookDocument } from '../catalog/project-hooks.js';
+import { effectiveSurfaces } from '../model/types.js';
+export const USER_HOOKS_SOURCE = '@user-hooks';
+export const USER_HOOKS_SUITE = 'user-hooks';
+/**
+ * The Agent layout root's hook documents, relative to that root and read in
+ * order. Later files merge additively over earlier ones, the same order and
+ * semantics the project `.agents` layout applies. The first entry is also the
+ * suite's manifest path and the file a suite with no documents is addressed by.
+ */
+export const USER_HOOK_FILES = [join('hooks', 'hooks.json'), 'hooks.json'];
+/** Resolve one Agent-layout-relative hook document against the layout root. */
+export function userHookPath(agentsRoot, file) {
+    return join(agentsRoot, file);
+}
+/**
+ * Load the user's Agent layout hooks as one synthetic suite.
+ *
+ * The suite is always built, so one call answers with both the events and the
+ * reasons a document was rejected: an absent, malformed, or event-free set of
+ * hook files leaves `surfaces.hooks` at 0 and carries the diagnostics.
+ * {@link ../application/catalog.ts} merges the suite into the enabled set only
+ * when it declares events.
+ */
+export async function loadUserHooksSuite(agentsRoot) {
+    const errors = [];
+    const documents = [];
+    for (const file of USER_HOOK_FILES) {
+        const settings = await readHookDocument(agentsRoot, file, errors);
+        // A malformed file fails the whole set closed, the same way one malformed
+        // project hook layer drops every hook the layout declared.
+        if (settings === null)
+            return userHooksSuite(agentsRoot, undefined, errors);
+        // A standalone hook file may carry the bare event table; the shared rule
+        // that recognizes it is the same one the project `.agents` layout applies.
+        if (settings !== undefined)
+            documents.push({ file, settings: standaloneHookDocument(settings) });
+    }
+    return userHooksSuite(agentsRoot, normalizeHookDocuments(undefined, documents, errors), errors);
+}
+/** One synthetic suite for the Agent layout root's hook files. */
+function userHooksSuite(agentsRoot, hooks, errors) {
+    return {
+        sourceId: USER_HOOKS_SOURCE,
+        id: USER_HOOKS_SUITE,
+        root: agentsRoot,
+        manifest: { layout: 'agent-plugin-v1', path: userHookPath(agentsRoot, USER_HOOK_FILES[0]), id: USER_HOOKS_SUITE, name: USER_HOOKS_SUITE },
+        skills: [],
+        ...(hooks === undefined ? {} : { hooks }),
+        surfaces: { skills: 0, mcp: 0, hooks: hookCount(hooks), commands: 0, agents: 0, lsp: 0 },
+        dimension: 'user',
+        enabled: true,
+        // The suite declares hooks only; the other surfaces would otherwise make
+        // the command and LSP registries read this root a second time.
+        activeSurfaces: effectiveSurfaces({ skills: false, mcp: false, commands: false, agents: false, lsp: false }),
+        installedAt: 'user',
+        errors
+    };
+}
+/** One hook file's parsed document: absent is undefined, malformed is null plus a diagnostic. */
+async function readHookDocument(agentsRoot, file, errors) {
+    let text;
+    try {
+        text = await readFile(userHookPath(agentsRoot, file), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        errors.push(`${file}: hook file is unreadable`);
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        errors.push(`${file}: hook file is invalid JSON`);
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        errors.push(`${file}: hook file must be an object`);
+        return null;
+    }
+    return raw;
+}
+/** Declared hook commands, the same count a native suite reports for `surfaces.hooks`. */
+function hookCount(hooks) {
+    return Object.values(hooks?.events ?? {}).reduce((total, groups) => total + groups.reduce((count, group) => count + group.hooks.length, 0), 0);
+}

package/lib/runtime/user-panels.js

@@ -12,20 +12,26 @@
  * personas follow Claude Code agents frontmatter (`name`, `description`,
  * optional `whenToUse`, `tools`, `model`, `disabled`).
  *
- * Only the skills panel serves the cross-tool `<name>/SKILL.md` directory
- * spelling beside its own flat entries; commands and personas stay flat.
+ * Every panel reads the flat `<name>.md` children of its directory. The
+ * commands and agent-persona panels also read every `.md` document at any
+ * depth, addressing a nested entry by its path relative to the panel
+ * directory (`git/commit`, `review/code`), so subdirectories another Agent
+ * tool writes are picked up. The skills panel keeps the cross-tool
+ * `<name>/SKILL.md` directory spelling and reads it from the top level only,
+ * matching the harness's own reader of `~/.agents/skills`.
  *
  * An entry's name is the one its document declares — the same name the
- * harness reader derives from that file — and the panel addresses, edits, and
- * deletes the entry by that name. A document that reader would reject is
- * listed disabled with the reason instead of joining the catalog, and a skill
- * is switched off by writing that reader's own invocation controls, so the off
- * state lives in the file rather than in this provider.
+ * harness reader derives from that file — else its document name, and the
+ * panel addresses, edits, and deletes the entry by that name. A document that
+ * reader would reject is listed disabled with the reason instead of joining
+ * the catalog, and a skill is switched off by writing that reader's own
+ * invocation controls, so the off state lives in the file rather than in this
+ * provider.
  * @module runtime/user-panels
  */
 import { dirname } from 'node:path';
 import { skillEntryRejection } from '../catalog/skills-parse.js';
-import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, userEntryDir, writeEntryDocument, writeEntryFile } from './user-store.js';
+import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, USER_ENTRY_PATH, userEntryDir, writeEntryDocument, writeEntryFile } from './user-store.js';
 /** The skill-source label user-panel entries carry into the skill registry. */
 export const USER_PANEL_SKILL_SOURCE = 'user-panel';
 /**
@@ -48,6 +54,8 @@ export class UserPanelStore {
     kind;
     shapes;
     extraNameCheck;
+    namePattern;
+    nested;
     validate;
     honorInvocationControls;
     constructor(agentsRoot, kind, options = {}) {
@@ -55,6 +63,8 @@ export class UserPanelStore {
         this.kind = kind;
         this.shapes = options.shapes ?? ['file'];
         this.extraNameCheck = options.extraNameCheck ?? (() => true);
+        this.nested = options.nested === true;
+        this.namePattern = this.nested ? USER_ENTRY_PATH : USER_ENTRY_NAME;
         this.validate = options.validate;
         this.honorInvocationControls = options.honorInvocationControls === true;
     }
@@ -65,20 +75,21 @@ export class UserPanelStore {
     get dir() {
         return this.dirPath();
     }
+    /** The path grammar plus the panel's per-segment extra grammar. */
     validName(name) {
-        return USER_ENTRY_NAME.test(name) && this.extraNameCheck(name);
+        return this.namePattern.test(name) && name.split('/').every(segment => this.extraNameCheck(segment));
     }
     /**
      * Resolve the document one entry name addresses. The name a panel entry
-     * carries is the one its document declares, which is only the file name by
-     * convention, so a name that matches no path is matched against the
+     * carries is the one its document declares, which is only the document path
+     * by convention, so a name that matches no path is matched against the
      * declared names of the served documents.
      */
     async document(name) {
-        const direct = await resolveEntryDocument(this.dir, name, this.shapes);
+        const direct = await resolveEntryDocument(this.dir, name, this.shapes, false, this.nested);
         if (direct !== undefined)
             return direct;
-        for (const candidate of await listEntryDocuments(this.dir, false, this.shapes)) {
+        for (const candidate of await listEntryDocuments(this.dir, false, this.shapes, this.nested)) {
             const file = await readEntryDocument(candidate);
             if (file?.name === name)
                 return candidate;
@@ -87,7 +98,7 @@ export class UserPanelStore {
     }
     /** Every entry, sorted by name; strict snapshots propagate temporary I/O failures. */
     async list(strict = false) {
-        const files = await listEntryFiles(this.dir, strict, this.shapes);
+        const files = await listEntryFiles(this.dir, strict, this.shapes, this.nested);
         return files.map(file => this.serialize(file));
     }
     /** One entry's full record, including the raw file text. */
@@ -133,11 +144,11 @@ export class UserPanelStore {
             origin: 'user'
         };
     }
-    /** Create an entry; refuses an occupied name. New entries use the flat spelling. */
+    /** Create an entry; refuses an occupied name. New entries use the flat `<name>.md` spelling, creating any parent directories. */
     async create(name, text) {
         if (!this.validName(name))
             throw new Error(`invalid name "${name}" — use lowercase letters, digits, and dashes, starting with a letter or digit`);
-        if (await entryExists(this.dir, name, this.shapes))
+        if (await entryExists(this.dir, name, this.shapes, this.nested))
             throw new Error(`an entry named "${name}" already exists`);
         await writeEntryFile(this.dir, name, text);
         const created = await this.get(name);
@@ -156,7 +167,7 @@ export class UserPanelStore {
     }
     /** Delete one entry; a missing file is a no-op (idempotent delete). */
     async remove(name) {
-        if (!USER_ENTRY_NAME.test(name))
+        if (!this.namePattern.test(name))
             throw new Error(`invalid entry name "${name}"`);
         const document = await this.document(name);
         if (document === undefined)
@@ -173,16 +184,17 @@ export function createUserPanelStores(agentsRoot) {
             validate: file => skillEntryRejection(file.text),
             honorInvocationControls: true
         }),
-        commands: new UserPanelStore(agentsRoot, 'commands'),
-        agents: new UserPanelStore(agentsRoot, 'agents', { extraNameCheck: isUserSkillEntryName })
+        commands: new UserPanelStore(agentsRoot, 'commands', { nested: true }),
+        agents: new UserPanelStore(agentsRoot, 'agents', { extraNameCheck: isUserSkillEntryName, nested: true })
     };
 }
 /**
- * The skills/agents panels accept only harness skill-grammar names
+ * The skills/agents panels accept only harness skill-grammar path segments
  * (`[a-z0-9-]`, no underscores): a candidate name reaching the skill
  * registry's `get()` with an invalid name is dropped there, and several
- * consumers validate strictly, so `_`-named entries would be dead weight.
- * Commands keep the looser command grammar (`_` allowed).
+ * consumers validate strictly, so `_`-named entries would be dead weight. A
+ * nested persona applies this to each segment. Commands keep the looser
+ * command grammar (`_` allowed).
  */
 export function isUserSkillEntryName(name) {
     return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);

package/lib/runtime/user-store.js

@@ -5,9 +5,12 @@
  * frontmatter rules the catalog uses, so user entries look exactly like suite
  * entries to the runtime mounts.
  *
- * An entry is one document. Skills also accept the cross-tool directory
- * spelling (`<name>/SKILL.md`) that other Agent tools and the harness's own
- * reader of `~/.agents/skills` author; commands and personas are flat only.
+ * An entry is one document. A flat panel reads the immediate `<name>.md`
+ * children of its directory; a nested panel (commands and agent personas)
+ * reads every `.md` document at any depth and names each by its path relative
+ * to that directory. Skills also accept the cross-tool directory spelling
+ * (`<name>/SKILL.md`) that other Agent tools and the harness's own reader of
+ * `~/.agents/skills` author, and read it from the top level only.
  * @module runtime/user-store
  */
 import { readdir, readFile, rmdir, rm, stat } from 'node:fs/promises';
@@ -19,8 +22,15 @@ import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse
 export function userEntryDir(agentsRoot, kind) {
     return join(agentsRoot, kind);
 }
-/** `[a-z][a-z0-9_-]*` — the grammar every panel entry name must satisfy. */
+/** `[a-z][a-z0-9_-]*` — one segment of a panel entry name. */
 export const USER_ENTRY_NAME = /^[a-z][a-z0-9_-]*$/;
+/**
+ * The path grammar a nested panel entry name satisfies: one or more
+ * {@link USER_ENTRY_NAME} segments joined by `/`. It rejects `..`, leading or
+ * trailing separators, empty segments, backslashes, and uppercase, so the name
+ * stays a path relative to the panel directory.
+ */
+export const USER_ENTRY_PATH = /^[a-z][a-z0-9_-]*(?:\/[a-z][a-z0-9_-]*)*$/;
 /** The file name of a directory-shaped skill's document. */
 export const SKILL_ENTRY_FILE = 'SKILL.md';
 /**
@@ -47,10 +57,12 @@ async function isFile(file, strict) {
 }
 /**
  * Resolve one entry name to its document, taking the first shape the path
- * exists in. Names outside the entry grammar never touch the filesystem.
+ * exists in. A nested panel accepts a path name (`git/commit`); a flat panel
+ * accepts a single segment. Names outside the panel's grammar never touch the
+ * filesystem.
  */
-export async function resolveEntryDocument(dir, name, shapes, strict = false) {
-    if (!USER_ENTRY_NAME.test(name))
+export async function resolveEntryDocument(dir, name, shapes, strict = false, nested = false) {
+    if (!(nested ? USER_ENTRY_PATH : USER_ENTRY_NAME).test(name))
         return undefined;
     for (const shape of shapes) {
         const file = entryDocumentPath(dir, name, shape);
@@ -59,8 +71,18 @@ export async function resolveEntryDocument(dir, name, shapes, strict = false) {
     }
     return undefined;
 }
-/** Every entry document the served shapes expose, deduplicated by name at the first shape that has it. */
-export async function listEntryDocuments(dir, strict = false, shapes = ['file']) {
+/**
+ * Every entry document the served shapes expose. A flat panel reads immediate
+ * children only; a nested panel walks every subdirectory to any depth and
+ * names each entry by its path relative to `dir`. Entries are deduplicated by
+ * name at the first shape that has it.
+ */
+export async function listEntryDocuments(dir, strict = false, shapes = ['file'], nested = false) {
+    const found = new Map();
+    if (nested) {
+        await collectNestedEntryDocuments(dir, '', shapes, strict, found);
+        return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
     let entries;
     try {
         entries = await readdir(dir);
@@ -70,7 +92,6 @@ export async function listEntryDocuments(dir, strict = false, shapes = ['file'])
             throw error;
         return [];
     }
-    const found = new Map();
     for (const entry of entries.sort()) {
         const name = entry.endsWith('.md') ? entry.slice(0, -3) : shapes.includes('skill-directory') ? entry : undefined;
         if (name === undefined || !USER_ENTRY_NAME.test(name))
@@ -85,6 +106,45 @@ export async function listEntryDocuments(dir, strict = false, shapes = ['file'])
     }
     return [...found.values()];
 }
+/**
+ * Recursively collect the entry documents under one directory. Dot-directories,
+ * `node_modules`, and symlinks are skipped, so the walk cannot follow a link
+ * out of the panel directory; every segment must satisfy the entry grammar, so
+ * a discovered name stays a relative path. `prefix` is that path so far, with
+ * `/` separators and no trailing slash.
+ */
+async function collectNestedEntryDocuments(dir, prefix, shapes, strict, found) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink() || entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        if (entry.isDirectory()) {
+            if (!USER_ENTRY_NAME.test(entry.name))
+                continue;
+            const name = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+            if (shapes.includes('skill-directory') && (await isFile(join(dir, entry.name, SKILL_ENTRY_FILE), strict))) {
+                found.set(name, { name, file: join(dir, entry.name, SKILL_ENTRY_FILE), directory: join(dir, entry.name), shape: 'skill-directory' });
+            }
+            await collectNestedEntryDocuments(join(dir, entry.name), name, shapes, strict, found);
+            continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const segment = entry.name.slice(0, -3);
+        if (!USER_ENTRY_NAME.test(segment))
+            continue;
+        const name = prefix === '' ? segment : `${prefix}/${segment}`;
+        found.set(name, { name, file: join(dir, entry.name), directory: dir, shape: 'file' });
+    }
+}
 /** Parse full YAML metadata without flattening arrays, mappings, or multiline strings. */
 export function parseFrontmatterRecord(text) {
     const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1];
@@ -140,8 +200,8 @@ export async function readEntryDocument(document, strict = false) {
     };
 }
 /** List entries across the served shapes; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
-export async function listEntryFiles(dir, strict = false, shapes = ['file']) {
-    const documents = await listEntryDocuments(dir, strict, shapes);
+export async function listEntryFiles(dir, strict = false, shapes = ['file'], nested = false) {
+    const documents = await listEntryDocuments(dir, strict, shapes, nested);
     const found = [];
     for (const document of documents) {
         const parsed = await readEntryDocument(document, strict);
@@ -163,13 +223,15 @@ export async function writeEntryDocument(document, text) {
     await writeFileAtomic(document.file, text, { mode: 0o644, dirMode: 0o700 });
 }
 /**
- * Enforce the entry-name grammar at every filesystem choke point. The name
- * is interpolated into `join(dir, name + '.md')`, so an unchecked name with
- * separators or `..` could address any `.md` file (or directory) on disk —
- * read, write, and delete all go through this guard.
+ * Enforce the entry-name path grammar at every filesystem choke point. The
+ * name is interpolated into `join(dir, name + '.md')`, so an unchecked name
+ * with separators or `..` could address any `.md` file (or directory) on disk
+ * — read, write, and delete all go through this guard. Whether the panel
+ * accepts a nested path or a single segment is decided where a caller-supplied
+ * name enters the store (`resolveEntryDocument` and the store's own checks).
  */
 function assertEntryName(name) {
-    if (!USER_ENTRY_NAME.test(name))
+    if (!USER_ENTRY_PATH.test(name))
         throw new Error(`invalid entry name "${name}" — use lowercase letters, digits, dashes, or underscores, starting with a letter`);
 }
 /**
@@ -186,8 +248,8 @@ export async function deleteEntryDocument(document) {
         await rmdir(dirname(document.file)).catch(() => undefined);
 }
 /** Whether an entry document with that name exists in any served shape. */
-export async function entryExists(dir, name, shapes = ['file']) {
-    return (await resolveEntryDocument(dir, name, shapes)) !== undefined;
+export async function entryExists(dir, name, shapes = ['file'], nested = false) {
+    return (await resolveEntryDocument(dir, name, shapes, false, nested)) !== undefined;
 }
 /** Serialize a frontmatter block from a shallow record (deterministic key order). */
 export function serializeFrontmatter(meta) {

package/lib/types/catalog/component-files.d.ts

@@ -18,4 +18,5 @@ export declare function firstComponentFile(root: string, candidates: readonly st
 /** Legacy/native suites without catalog resource lists keep their conventional directory behavior. */
 export declare function defaultMarkdownResources(root: string, component: 'agents' | 'commands'): Promise<SuiteMarkdownResource[]>;
 export declare function resourceText(resource: SuiteMarkdownResource): Promise<string>;
+/** Registration name of a command resource; one rule governs suite, project-native, and user-panel commands. */
 export declare function resourceCommandName(name: string): string;

package/lib/types/catalog/project-hooks.d.ts

@@ -1,10 +1,23 @@
 /** Normalize native Claude-shaped command hooks for the existing host execution bridge. */
 import type { ProjectHooks } from '../model/types.js';
 import type { ProjectHookFormat } from '../model/layouts.js';
+/**
+ * Present one read document as the settings shape the shared validator reads:
+ * a standalone hook file may carry the bare event table instead of a `hooks`
+ * key. A recognized top-level event name is the marker — a document with no
+ * event name at the top stays verbatim, so an ordinary settings file missing
+ * `hooks` is still not accepted as a bare event table. Exported because the
+ * user Agent layout root reads the same standalone file shapes.
+ */
+export declare function standaloneHookDocument(settings: Record<string, unknown>, format?: ProjectHookFormat): Record<string, unknown>;
 /** Merge settings layers additively, deduplicating identical event/matcher/command triples. */
 export declare function discoverProjectHooks(projectRoot: string, files: readonly string[], errors: string[], format?: ProjectHookFormat): Promise<ProjectHooks | undefined>;
-/** Pure validation shared by native settings and plugin file/inline declarations. */
-export declare function normalizeHookDocuments(projectRoot: string, documents: Array<{
+/**
+ * Pure validation shared by native settings and plugin file/inline
+ * declarations. `projectRoot` is absent for hooks declared in the user Agent
+ * layout root, which belong to no project.
+ */
+export declare function normalizeHookDocuments(projectRoot: string | undefined, documents: Array<{
     file: string;
     settings: Record<string, unknown>;
 }>, errors: string[], format?: ProjectHookFormat): ProjectHooks | undefined;

package/lib/types/catalog/surfaces.d.ts

@@ -1,10 +1,12 @@
 import type { LspSuiteConfig, McpSuiteConfig, SuiteManifest, SuiteSkill, SuiteSurfaceCounts } from '../model/types.js';
 /**
  * Discover SKILL.md files under the suite's skills directory, up to 3 levels
- * deep. Portable v1 suites (§7.1) instead discover exactly one level of
- * `skills/` subdirectories each carrying a `SKILL.md` — the spec forbids
- * recursive deeper search and root-level or flat skill files are outside the
- * portable discovery shape.
+ * deep. A path that carries `SKILL.md` is one skill directory — a manifest may
+ * list those individually — and only that document is read from it. Portable
+ * v1 suites (§7.1) instead discover exactly one level of `skills/`
+ * subdirectories each carrying a `SKILL.md` — the spec forbids recursive
+ * deeper search and root-level or flat skill files are outside the portable
+ * discovery shape.
  */
 export declare function discoverSkills(root: string, errors: string[], declared?: unknown, portable?: boolean): Promise<SuiteSkill[]>;
 /**

package/lib/types/contracts/market.d.ts

@@ -343,7 +343,11 @@ export interface SkillContent {
 }
 /** A user panel entry (skills / commands / agent personas) over HTTP. */
 export interface UserPanelEntryWire {
-    /** Entry name: the name its document declares, else the file's base name. */
+    /**
+     * Entry name: the name its document declares, else its document name — the
+     * file's base name, or, on a panel that reads subdirectories, the document's
+     * path relative to the panel directory (`git/commit`).
+     */
     name: string;
     description: string;
     disabled: boolean;

package/lib/types/index.d.ts

@@ -13,11 +13,14 @@
  * self-contained: suites' MCP servers mount through the market's own bridge
  * plugin on the host `tools` registry.
  */
-import type { Context } from '@deepseek-ai/cordis';
+import { type Context, type Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { DownloadRegionSetting } from './contracts/settings.js';
 import type { SourceRef } from './model/types.js';
 export declare const name = "dsh-agent-plugins-market";
 export declare const inject: string[];
 /** Host configuration. */
+/** Host configuration; the five market settings arrive as volatile references the host updates in place. */
 export interface Config {
     /** User-dimension suite root; defaults to `~/.dsh/agent-plugins` (`$DSH_HOME/agent-plugins`). */
     userRoot?: string;
@@ -40,5 +43,88 @@ export interface Config {
         fallbackTarball?: boolean;
         allowHttpArchives?: boolean;
     };
+    /** MCP mount backend switch; updated live through the host settings service. */
+    mcpEnhanced: Volatile<boolean | undefined>;
+    /** Project-layout discovery switch; updated live through the host settings service. */
+    scanProjectLayouts: Volatile<boolean | undefined>;
+    /** Download region choice; updated live through the host settings service. */
+    downloadRegion: Volatile<DownloadRegionSetting | undefined>;
+    /** Experience-feedback tool switch; updated live through the host settings service. */
+    feedbackEnabled: Volatile<boolean | undefined>;
+    /** Background source-update switch; updated live through the host settings service. */
+    autoUpdateSources: Volatile<boolean | undefined>;
 }
+/**
+ * Schemastery projection the host loader reads: the five volatile fields become
+ * the `dsh-agent-plugins-market` settings namespace (the Plugins panel's
+ * configuration page reads it), while the startup fields stay plain.
+ */
+/** The schema's input face: every field optional, exactly what a profile patch may carry. */
+export interface ConfigInput {
+    userRoot?: string | null;
+    dataRoot?: string | null;
+    sources?: unknown;
+    git?: {
+        proxy?: string | null;
+        insteadOf?: Record<string, unknown>;
+        timeoutMs?: number | null;
+        cloneRetry?: boolean | null;
+        fallbackTarball?: boolean | null;
+        allowHttpArchives?: boolean | null;
+    };
+    mcpEnhanced?: boolean | null;
+    scanProjectLayouts?: boolean | null;
+    downloadRegion?: 'auto' | 'global' | 'china' | null;
+    feedbackEnabled?: boolean | null;
+    autoUpdateSources?: boolean | null;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    userRoot: z<string | undefined, string | undefined, "plain">;
+    dataRoot: z<string | undefined, string | undefined, "plain">;
+    sources: z<any, any, "plain">;
+    git: z<Schemastery.ObjectS<NoInfer<{
+        proxy: z<string, string, "plain">;
+        insteadOf: z<import("@deepseek-ai/cosmokit").Dict<string, any>, import("@deepseek-ai/cosmokit").Dict<string, any>, "plain">;
+        timeoutMs: z<number, number, "plain">;
+        cloneRetry: z<boolean, boolean, "plain">;
+        fallbackTarball: z<boolean, boolean, "plain">;
+        allowHttpArchives: z<boolean, boolean, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        proxy: z<string, string, "plain">;
+        insteadOf: z<import("@deepseek-ai/cosmokit").Dict<string, any>, import("@deepseek-ai/cosmokit").Dict<string, any>, "plain">;
+        timeoutMs: z<number, number, "plain">;
+        cloneRetry: z<boolean, boolean, "plain">;
+        fallbackTarball: z<boolean, boolean, "plain">;
+        allowHttpArchives: z<boolean, boolean, "plain">;
+    }>>, "plain">;
+    mcpEnhanced: z<boolean, boolean, "volatile-defined">;
+    scanProjectLayouts: z<boolean, boolean, "volatile-defined">;
+    downloadRegion: z<"auto" | "global" | "china", "auto" | "global" | "china", "volatile-defined">;
+    feedbackEnabled: z<boolean, boolean, "volatile-defined">;
+    autoUpdateSources: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    userRoot: z<string | undefined, string | undefined, "plain">;
+    dataRoot: z<string | undefined, string | undefined, "plain">;
+    sources: z<any, any, "plain">;
+    git: z<Schemastery.ObjectS<NoInfer<{
+        proxy: z<string, string, "plain">;
+        insteadOf: z<import("@deepseek-ai/cosmokit").Dict<string, any>, import("@deepseek-ai/cosmokit").Dict<string, any>, "plain">;
+        timeoutMs: z<number, number, "plain">;
+        cloneRetry: z<boolean, boolean, "plain">;
+        fallbackTarball: z<boolean, boolean, "plain">;
+        allowHttpArchives: z<boolean, boolean, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        proxy: z<string, string, "plain">;
+        insteadOf: z<import("@deepseek-ai/cosmokit").Dict<string, any>, import("@deepseek-ai/cosmokit").Dict<string, any>, "plain">;
+        timeoutMs: z<number, number, "plain">;
+        cloneRetry: z<boolean, boolean, "plain">;
+        fallbackTarball: z<boolean, boolean, "plain">;
+        allowHttpArchives: z<boolean, boolean, "plain">;
+    }>>, "plain">;
+    mcpEnhanced: z<boolean, boolean, "volatile-defined">;
+    scanProjectLayouts: z<boolean, boolean, "volatile-defined">;
+    downloadRegion: z<"auto" | "global" | "china", "auto" | "global" | "china", "volatile-defined">;
+    feedbackEnabled: z<boolean, boolean, "volatile-defined">;
+    autoUpdateSources: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
 export declare function apply(ctx: Context, config?: Config): Promise<void>;

package/lib/types/model/command-names.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The call name a command resource registers under.
+ *
+ * A command resource may live at any depth under its `commands/` directory,
+ * but the host's slash-command grammar accepts single-segment names only, so
+ * registration flattens the path separators: `git/commit` registers as
+ * `git-commit`. The user panel renders the same call name, so a card never
+ * advertises a slash name the host cannot accept.
+ * @module model/command-names
+ */
+/** Flatten a resource path into the single-segment name a slash command registers under. */
+export declare function commandCallName(name: string): string;

package/lib/types/model/layouts.d.ts

@@ -86,6 +86,7 @@ export declare const PROJECT_LAYOUTS: readonly [{
     readonly dirName: ".agents";
     readonly label: "agents";
     readonly subdirs: readonly ["skills", "agents", "commands"];
+    readonly mcpFiles: readonly [".agents/mcp.json"];
     readonly hookFiles: readonly [".agents/hooks/hooks.json", ".agents/hooks.json"];
 }, {
     readonly dirName: ".codex";

package/lib/types/model/types.d.ts

@@ -259,7 +259,8 @@ export interface Suite extends DiscoveredSuite {
     activeSurfaces: Record<SuiteSurfaceKey, boolean>;
 }
 export interface ProjectHooks {
-    projectRoot: string;
+    /** Absent when the hooks belong to the user Agent layout root: the bridge then defaults `${CLAUDE_PROJECT_DIR}` to the calling session's workspace. */
+    projectRoot?: string;
     events: Record<string, Array<{
         matcher?: string;
         hooks: Array<{