dsh-agent-plugins-market 0.4.3

package/lib/paths.js

@@ -0,0 +1,85 @@
+/**
+ * Root path resolution for the two install dimensions.
+ *
+ * User dimension: `~/.dsh/agent-plugins/` (or `$DSH_HOME/agent-plugins`).
+ * Project dimension: `<projectRoot>/.dsh/agent-plugins/`, where the project
+ * root is the nearest ancestor containing `.git`.
+ */
+import { existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** Source checkouts live under `<dimensionRoot>/.sources/<sourceId>/`. */
+export const SOURCES_DIR_NAME = '.sources';
+/** Per-suite mutable data directory (the `${PLUGIN_DATA}` placeholder). */
+export const DATA_DIR_NAME = 'data';
+export const STATE_FILE_NAME = 'state.json';
+/** Expand a leading `~/` (or `~\` on Windows) to the home directory; other values pass through. */
+export function expandHome(path) {
+    if (path === '~' || path.startsWith('~/') || path.startsWith('~\\'))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+/** Resolve the harness home (`$DSH_HOME` or `~/.dsh`). */
+export function resolveDshHome() {
+    return process.env.DSH_HOME === undefined ? join(homedir(), '.dsh') : resolve(process.env.DSH_HOME);
+}
+/** Resolve the user-dimension suite root. */
+export function resolveUserRoot(configUserRoot) {
+    return resolve(expandHome(configUserRoot ?? join(resolveDshHome(), 'agent-plugins')));
+}
+/** Resolve the suite data root hosting `${PLUGIN_DATA}` directories. */
+export function resolveDataRoot(configDataRoot) {
+    return resolve(expandHome(configDataRoot ?? join(resolveDshHome(), 'agent-plugins-data')));
+}
+/** Resolve a project root from a workspace cwd: nearest ancestor with `.git`. */
+export async function findProjectRoot(cwd) {
+    let current = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return resolve(cwd);
+        current = parent;
+    }
+}
+/** Resolve the project-dimension suite root for a workspace cwd. */
+export async function resolveProjectRoot(cwd) {
+    return join(await findProjectRoot(cwd), '.dsh', 'agent-plugins');
+}
+/** Source checkout directory for one source id. */
+export function sourcesDir(dimensionRoot) {
+    return join(dimensionRoot, SOURCES_DIR_NAME);
+}
+/** Source checkout directory for one source id. */
+export function sourceCheckoutDir(dimensionRoot, sourceId) {
+    return join(sourcesDir(dimensionRoot), sourceId);
+}
+/** Per-suite data directory for `${PLUGIN_DATA}`. */
+export function suiteDataDir(dataRoot, suiteId) {
+    return join(dataRoot, DATA_DIR_NAME, suiteId);
+}
+/** Async existence probe that follows symlinks for a final component. */
+export async function isDirectory(path) {
+    try {
+        const info = await stat(path);
+        return info.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Sanitize a plugin or server id into `[a-z0-9-]` (lowercased). */
+export function sanitizeId(raw) {
+    const cleaned = raw.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '').replace(/-{2,}/g, '-');
+    return cleaned === '' ? 'unnamed' : cleaned;
+}
+/** Derive a source id from a repository URL or local path: last path segment, `.git` stripped. */
+export function deriveSourceId(url) {
+    const trimmed = url.trim().replace(/\/+$/, '');
+    let base = trimmed.split(/[/\\]/).at(-1) ?? '';
+    if (base.endsWith('.git'))
+        base = base.slice(0, -4);
+    return sanitizeId(base);
+}

package/lib/routes.js

@@ -0,0 +1,208 @@
+/**
+ * HTTP routes bridging the market page to the SuiteManager.
+ *
+ * This layer only parses requests, delegates to the manager, and serializes
+ * responses. Mutating routes accept same-origin POSTs exclusively: a
+ * cross-site form or fetch cannot trigger a clone, an uninstall, or an
+ * enable/disable against a local profile.
+ */
+import { isAbsolute } from 'node:path';
+import { expandHome } from './paths.js';
+const API_PREFIX = '/api/agent-plugins/';
+const MAX_BODY_BYTES = 64 * 1024;
+/** Mount every route; returns the disposer releasing them all. */
+export function mountSuiteRoutes(hostCtx, manager) {
+    const host = hostCtx;
+    const disposers = [];
+    const get = (path, handler) => {
+        disposers.push(host.webServer.register({ kind: 'exact', path, handler }));
+    };
+    const post = (path, handler) => {
+        disposers.push(host.webServer.register({
+            kind: 'exact',
+            path,
+            handler: (request, response) => {
+                if (!sameOrigin(request)) {
+                    sendJson(response, 403, { ok: false, error: 'cross-origin request rejected' });
+                    return;
+                }
+                void (async () => {
+                    const body = await readJsonBody(request);
+                    if (body === undefined) {
+                        sendJson(response, 400, { ok: false, error: 'invalid JSON body' });
+                        return;
+                    }
+                    try {
+                        const value = await handler(body);
+                        sendJson(response, 200, { ok: true, ...value });
+                    }
+                    catch (error) {
+                        sendJson(response, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                    }
+                })();
+            },
+        }));
+    };
+    get(`${API_PREFIX}overview`, async (_request, response) => {
+        sendJson(response, 200, await manager.overview());
+    });
+    get(`${API_PREFIX}config`, async (_request, response) => {
+        sendJson(response, 200, { sources: manager.sources });
+    });
+    get(`${API_PREFIX}suite`, async (request, response) => {
+        const query = queryOf(request);
+        const sourceId = query.get('sourceId');
+        const suiteId = query.get('suiteId');
+        if (sourceId === null || suiteId === null) {
+            sendJson(response, 400, { ok: false, error: 'missing sourceId or suiteId' });
+            return;
+        }
+        try {
+            sendJson(response, 200, await manager.suiteDetail(sourceId, suiteId));
+        }
+        catch (error) {
+            sendJson(response, 404, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    get(`${API_PREFIX}skill`, async (request, response) => {
+        const query = queryOf(request);
+        const sourceId = query.get('sourceId');
+        const suiteId = query.get('suiteId');
+        const skill = query.get('skill');
+        if (sourceId === null || suiteId === null || skill === null) {
+            sendJson(response, 400, { ok: false, error: 'missing sourceId, suiteId, or skill' });
+            return;
+        }
+        try {
+            sendJson(response, 200, await manager.skillContent(sourceId, suiteId, skill));
+        }
+        catch (error) {
+            sendJson(response, 404, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    post(`${API_PREFIX}sources/add`, async (body) => {
+        const url = String(body['url'] ?? '').trim();
+        if (url === '')
+            throw new Error('missing source url');
+        const local = body['local'] === true;
+        if (local) {
+            const expanded = expandHome(url);
+            if (!url.startsWith('~/') && url !== '~' && !isAbsolute(expanded))
+                throw new Error('local source url must be an absolute path or start with ~/');
+        }
+        const branch = body['branch'];
+        const source = await manager.addSource({
+            url: local ? expandHome(url) : url,
+            ...typeof branch === 'string' && branch.trim() !== '' ? { branch: branch.trim() } : {},
+            ...local ? { local: true } : {},
+        });
+        return { source };
+    });
+    post(`${API_PREFIX}sources/update`, async (body) => {
+        const id = body['id'];
+        if (typeof id !== 'string' || id === '')
+            throw new Error('missing source id');
+        const patch = {};
+        if (body['url'] !== undefined) {
+            const url = String(body['url']).trim();
+            if (url === '')
+                throw new Error('missing source url');
+            patch.url = url;
+        }
+        if (body['branch'] !== undefined)
+            patch.branch = String(body['branch']).trim();
+        if (body['local'] !== undefined)
+            patch.local = body['local'] === true;
+        await manager.updateSource(id, patch);
+        return {};
+    });
+    post(`${API_PREFIX}sources/remove`, async (body) => {
+        const id = body['id'];
+        if (typeof id !== 'string' || id === '')
+            throw new Error('missing source id');
+        await manager.removeSource(id);
+        return {};
+    });
+    post(`${API_PREFIX}sources/refresh`, async (body) => {
+        const id = body['id'];
+        await manager.refreshSource(typeof id === 'string' && id !== '' ? id : undefined);
+        return {};
+    });
+    post(`${API_PREFIX}install`, async (body) => {
+        const { sourceId, suiteId } = parseTarget(body);
+        await manager.install(sourceId, suiteId);
+        return {};
+    });
+    post(`${API_PREFIX}uninstall`, async (body) => {
+        const { sourceId, suiteId } = parseTarget(body);
+        await manager.uninstall(sourceId, suiteId);
+        return {};
+    });
+    post(`${API_PREFIX}set-enabled`, async (body) => {
+        const { sourceId, suiteId } = parseTarget(body);
+        const enabled = body['enabled'];
+        if (typeof enabled !== 'boolean')
+            throw new Error('missing boolean enabled');
+        await manager.setEnabled(sourceId, suiteId, enabled);
+        return {};
+    });
+    return () => {
+        for (const dispose of disposers)
+            dispose();
+    };
+}
+function parseTarget(body) {
+    const sourceId = body['sourceId'];
+    const suiteId = body['suiteId'];
+    if (typeof sourceId !== 'string' || sourceId === '')
+        throw new Error('missing sourceId');
+    if (typeof suiteId !== 'string' || suiteId === '')
+        throw new Error('missing suiteId');
+    return { sourceId, suiteId };
+}
+function sameOrigin(request) {
+    const origin = request.headers['origin'];
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === request.headers['host'];
+    }
+    catch {
+        return false;
+    }
+}
+function readJsonBody(request) {
+    return new Promise((resolve) => {
+        let size = 0;
+        const chunks = [];
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                resolve(undefined);
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('end', () => {
+            if (size > MAX_BODY_BYTES)
+                return;
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+        request.on('error', () => resolve(undefined));
+    });
+}
+/** Parse the query string of one request into a URLSearchParams. */
+function queryOf(request) {
+    return new URL(request.url ?? '/', 'http://dsh.local').searchParams;
+}
+function sendJson(response, status, payload) {
+    const body = JSON.stringify(payload);
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) });
+    response.end(body);
+}

package/lib/skills-parse.js

@@ -0,0 +1,114 @@
+/**
+ * SKILL.md frontmatter parsing shared by suite discovery (summaries) and the
+ * skill provider (full definitions).
+ *
+ * Parses the open YAML object dsh-skill documents: required `name` and
+ * `description`, optional `whenToUse`, and the two invocation controls
+ * (`disable-model-invocation`, `user-invocable`) with the same boolean forms
+ * and fail-closed behavior as the shipped filesystem provider.
+ */
+import { parse as parseYaml } from 'yaml';
+/** Kebab-case skill names only, matching the shipped provider's rule. */
+export function isSkillName(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+/**
+ * Normalize a display-style skill name into kebab-case (e.g. "Presentations"
+ * → "presentations"), or `undefined` when nothing usable remains.
+ */
+export function normalizeSkillName(name) {
+    const normalized = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return normalized === '' ? undefined : normalized;
+}
+function parseBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        switch (value.toLowerCase()) {
+            case 'true':
+            case 'yes':
+            case 'on':
+            case '1':
+                return true;
+            case 'false':
+            case 'no':
+            case 'off':
+            case '0':
+                return false;
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse skill frontmatter with the shipped provider's fail-closed semantics.
+ * @returns the parsed frontmatter, or a rejection string explaining why the
+ *   skill must be dropped from discovery.
+ */
+export function parseSkillFrontmatter(text, expectedName) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (match === null)
+        return 'missing YAML frontmatter';
+    let raw;
+    try {
+        raw = parseYaml(match[1]);
+    }
+    catch {
+        // Claude Code-authored frontmatter sometimes carries unquoted `: `
+        // sequences in prose fields, which strict YAML rejects. A lenient
+        // line-based fallback recovers the standard fields first-occurrence
+        // wins; values that still fail the field checks below drop the skill.
+        raw = lenientFrontmatter(match[1]);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return 'frontmatter is not an object';
+    const record = raw;
+    const rawName = record['name'];
+    const description = record['description'];
+    // Codex plugins ship display names in `name` (e.g. "Presentations"); the
+    // skill identity is its kebab form, so normalize instead of dropping.
+    const name = typeof rawName === 'string' && !isSkillName(rawName) ? normalizeSkillName(rawName) : rawName;
+    if (name === undefined || typeof name !== 'string')
+        return 'frontmatter name is missing or not kebab-case';
+    if (expectedName !== undefined && name !== expectedName)
+        return `frontmatter name "${rawName}" does not match skill directory "${expectedName}"`;
+    if (typeof description !== 'string' || description.trim() === '')
+        return 'frontmatter description is missing or empty';
+    const disableModel = parseBoolean(record['disable-model-invocation']);
+    if (disableModel === undefined && record['disable-model-invocation'] !== undefined) {
+        return 'invalid disable-model-invocation value';
+    }
+    const userInvocable = parseBoolean(record['user-invocable']);
+    if (userInvocable === undefined && record['user-invocable'] !== undefined) {
+        return 'invalid user-invocable value';
+    }
+    const whenToUse = typeof record['whenToUse'] === 'string' ? record['whenToUse'] : undefined;
+    return {
+        name,
+        description: description.trim(),
+        ...whenToUse === undefined ? {} : { whenToUse },
+        invocation: {
+            modelInvocable: disableModel !== true,
+            userInvocable: userInvocable !== false,
+        },
+    };
+}
+/** Lenient frontmatter recovery for prose fields with embedded `: `. */
+function lenientFrontmatter(body) {
+    const record = {};
+    for (const line of body.split(/\r?\n/)) {
+        const match = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        const key = match[1];
+        if (record[key] === undefined)
+            record[key] = match[2].trim();
+    }
+    return record;
+}
+/** Strip the frontmatter block, returning the instruction body. */
+export function stripFrontmatter(text) {
+    const match = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.exec(text);
+    return match === null ? text : text.slice(match[0].length);
+}

package/lib/skills-provider.js

@@ -0,0 +1,170 @@
+/**
+ * Skill provider feeding installed suites into `ctx.skills`.
+ *
+ * One provider serves both dimensions. Ranks sit between the shipped
+ * filesystem roots so each dimension's own skills still win:
+ * project suites (250) lose to the project's `.dsh/skills` (100) and
+ * `.agents/skills` (200) but beat custom (300); user suites (450) lose to
+ * the user's own `~/.dsh/skills` (400) and beat `~/.agents/skills` (500).
+ *
+ * Bodies are rewritten on load: `${CLAUDE_PLUGIN_ROOT}` (which Claude Code
+ * authors write into skill prose) is substituted with the suite root, and the
+ * resource base points at the skill directory, so CC-authored skills work
+ * verbatim under the harness.
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadState } from './state.js';
+import { resolveProjectRoot, STATE_FILE_NAME } from './paths.js';
+import { discoverSourceList } from './discovery.js';
+import { parseSkillFrontmatter, stripFrontmatter } from './skills-parse.js';
+export const SUITE_PROJECT_SOURCE = 'agent-plugin-project';
+export const SUITE_USER_SOURCE = 'agent-plugin-user';
+const PROJECT_RANK = 250;
+const USER_RANK = 450;
+export class SuiteSkillProvider {
+    manager;
+    name = 'agent-plugin';
+    constructor(manager) {
+        this.manager = manager;
+    }
+    async list(options) {
+        const located = await this.locate(options.cwd);
+        located.sort((a, b) => a.rank - b.rank || a.suite.id.localeCompare(b.suite.id) || a.skill.name.localeCompare(b.skill.name));
+        return located.map(entry => this.candidateFor(entry));
+    }
+    /** Parse `agents/*.md` of one suite into agent-definition candidates. */
+    async agentsOf(suite) {
+        const dir = join(suite.root, 'agents');
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return [];
+        }
+        const located = [];
+        for (const entry of entries) {
+            if (!entry.endsWith('.md'))
+                continue;
+            const file = join(dir, entry);
+            try {
+                const info = await stat(file);
+                if (!info.isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const agentName = entry.slice(0, -3);
+            let text;
+            try {
+                text = await readFile(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseSkillFrontmatter(text, agentName);
+            const description = typeof parsed === 'string' ? suite.manifest.description ?? agentName : parsed.description;
+            const skill = {
+                name: `agent-${agentName}`,
+                directory: dir,
+                file,
+                description,
+                ...(typeof parsed !== 'string' && parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+                invocation: typeof parsed === 'string' ? { modelInvocable: true, userInvocable: false } : parsed.invocation,
+            };
+            located.push({ rank: suite.dimension === 'project' ? PROJECT_RANK : USER_RANK, source: suite.dimension === 'project' ? SUITE_PROJECT_SOURCE : SUITE_USER_SOURCE, suite, skill });
+        }
+        return located;
+    }
+    async get(candidate, options) {
+        const locator = candidate.locator;
+        let text;
+        try {
+            text = await readFile(locator.file, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+        if (locator.kind === 'agent') {
+            const suiteName = locator.suiteRoot.split(/[\\/]/).at(-1) ?? 'suite';
+            const content = [
+                `## 子代理定义（来自 Agent Plugins ${suiteName}，Claude Code agents 格式）`,
+                '',
+                '当任务匹配下方描述时，通过 subagent 工具创建子代理并将「定义正文」原样作为指令执行。',
+                '',
+                '```markdown',
+                text,
+                '```',
+            ].join('\n');
+            return {
+                name: candidate.name,
+                description: candidate.description,
+                invocation: candidate.invocation,
+                source: candidate.source,
+                provider: this.name,
+                resourceBase: { kind: 'directory', path: locator.directory },
+                path: locator.file,
+                content,
+            };
+        }
+        const parsed = parseSkillFrontmatter(text, candidate.name);
+        if (typeof parsed === 'string')
+            return undefined;
+        const content = stripFrontmatter(text).replaceAll('${CLAUDE_PLUGIN_ROOT}', locator.suiteRoot);
+        return {
+            name: parsed.name,
+            description: candidate.description,
+            ...parsed.whenToUse === undefined ? {} : { whenToUse: parsed.whenToUse },
+            invocation: parsed.invocation,
+            source: candidate.source,
+            provider: this.name,
+            resourceBase: { kind: 'directory', path: locator.directory },
+            path: locator.file,
+            content,
+        };
+    }
+    candidateFor(entry) {
+        return {
+            name: entry.skill.name,
+            description: `[${entry.suite.manifest.name}] ${entry.skill.description}`,
+            ...entry.skill.whenToUse === undefined ? {} : { whenToUse: entry.skill.whenToUse },
+            invocation: entry.skill.invocation,
+            source: entry.source,
+            provider: this.name,
+            rank: entry.rank,
+            locator: { file: entry.skill.file, directory: entry.skill.directory, suiteRoot: entry.suite.root, kind: entry.skill.name.startsWith('agent-') ? 'agent' : 'skill' },
+            path: entry.skill.file,
+            resourceBase: { kind: 'directory', path: entry.skill.directory },
+        };
+    }
+    async locate(cwd) {
+        const located = [];
+        const userSuites = await this.manager.enabledUserSuites();
+        for (const suite of userSuites) {
+            for (const skill of suite.skills) {
+                located.push({ rank: USER_RANK, source: SUITE_USER_SOURCE, suite, skill });
+            }
+            located.push(...await this.agentsOf(suite));
+        }
+        if (cwd !== undefined) {
+            located.push(...await this.locateProject(cwd));
+        }
+        return located;
+    }
+    async locateProject(cwd) {
+        const projectRoot = await resolveProjectRoot(cwd);
+        const state = await loadState(join(projectRoot, STATE_FILE_NAME));
+        const located = [];
+        const suites = await discoverSourceList(state.sources, 'project', projectRoot);
+        for (const suite of suites) {
+            if (state.installed[`${suite.sourceId}/${suite.id}`]?.enabled !== true)
+                continue;
+            for (const skill of suite.skills) {
+                located.push({ rank: PROJECT_RANK, source: SUITE_PROJECT_SOURCE, suite, skill });
+            }
+        }
+        return located;
+    }
+}

package/lib/state.js

@@ -0,0 +1,64 @@
+/**
+ * Persisted suite state: configured sources and per-suite install entries.
+ *
+ * State is a plain JSON file at `<dimensionRoot>/state.json`. The host is the
+ * only writer (through manager actions and the HTTP routes); the manager
+ * re-reads the file whenever a mutation races, keeping the on-disk copy
+ * authoritative like the market profile state this pattern follows.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const EMPTY_STATE = { version: 1, sources: [], installed: {} };
+/** Parse persisted state; unreadable or wrong-version files yield a contained empty state. */
+export async function loadState(statePath) {
+    try {
+        const text = await readFile(statePath, 'utf8');
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null)
+            return EMPTY_STATE;
+        const record = parsed;
+        if (record['version'] !== 1)
+            return EMPTY_STATE;
+        return normalizeState(record);
+    }
+    catch {
+        return EMPTY_STATE;
+    }
+}
+function normalizeState(record) {
+    const sources = Array.isArray(record['sources'])
+        ? record['sources'].flatMap((entry) => {
+            if (typeof entry !== 'object' || entry === null)
+                return [];
+            const source = entry;
+            const id = typeof source['id'] === 'string' ? source['id'] : '';
+            const url = typeof source['url'] === 'string' ? source['url'] : '';
+            if (id === '' || url === '')
+                return [];
+            const branch = typeof source['branch'] === 'string' ? source['branch'] : undefined;
+            const local = source['local'] === true;
+            return [{ id, url, ...branch === undefined ? {} : { branch }, ...local ? { local: true } : {} }];
+        })
+        : [];
+    const installed = {};
+    if (typeof record['installed'] === 'object' && record['installed'] !== null) {
+        for (const [key, value] of Object.entries(record['installed'])) {
+            if (typeof value !== 'object' || value === null)
+                continue;
+            const entry = value;
+            installed[key] = {
+                enabled: entry['enabled'] === true,
+                lockCommit: typeof entry['lockCommit'] === 'string' ? entry['lockCommit'] : undefined,
+                installedAt: typeof entry['installedAt'] === 'string' ? entry['installedAt'] : new Date(0).toISOString(),
+            };
+        }
+    }
+    return { version: 1, sources, installed };
+}
+/** Persist state atomically through a sibling-temp rename. */
+export async function saveState(statePath, state) {
+    await mkdir(dirname(statePath), { recursive: true });
+    const temp = `${statePath}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    await rename(temp, statePath);
+}

package/lib/types/commands-mounts.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Suite } from './types.js';
+export interface CommandMountDiagnostic {
+    suiteId: string;
+    command: string;
+    reason: string;
+}
+interface CommandSpec {
+    name: string;
+    description: string;
+    body: string;
+    hint?: string;
+}
+export declare class CommandMountRegistry {
+    private readonly ctx;
+    private readonly live;
+    constructor(ctx: Context);
+    /** Register/unregister suite commands and agent-commands to match the enabled suites exactly. */
+    reconcile(enabledSuites: Suite[]): Promise<CommandMountDiagnostic[]>;
+    /** Dispose every registered command; used at plugin teardown. */
+    disposeAll(): void;
+}
+/** Parse `commands/*.md` of one suite root (Claude Code format). */
+export declare function readCommands(root: string): Promise<CommandSpec[]>;
+/** Parse `agents/*.md` of one suite root into `agent-<name>` commands so
+ *  subagents are selectable from the slash-command menu, grouped by the
+ *  `agent-` prefix (the harness command UI has no group headers). */
+export declare function readAgents(root: string): Promise<CommandSpec[]>;
+export {};

package/lib/types/context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime suite context: the `agent_plugins` query tool.
+ *
+ * Skills are injected by the native skill catalog (`dsh-tool-skill` renders
+ * `ctx.skills` providers into the model's `<available_skills>` catalog), so
+ * this module does not inject a duplicate session-start message. The tool
+ * exists for facts the catalog does not carry: enabled plugins per
+ * dimension, skill names per plugin, and MCP server prefixes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SuiteManager } from './manager.js';
+/** Mount the agent_plugins query tool. */
+export declare function mountSuiteContext(ctx: Context, manager: SuiteManager): () => void;