dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/runtime/skills-provider.js

@@ -79,7 +79,9 @@ export class SuiteSkillProvider {
     candidateFor(entry) {
         return {
             name: entry.skill.name,
-            description: `[${entry.suite.manifest.name}] ${entry.skill.description}`,
+            // The author's description verbatim — the harness renders it into the
+            // model's skill catalog, where a suite-name prefix is our packaging.
+            description: entry.skill.description,
             ...(entry.skill.whenToUse === undefined ? {} : { whenToUse: entry.skill.whenToUse }),
             invocation: entry.skill.invocation,
             source: entry.source,
@@ -100,7 +102,7 @@ export class SuiteSkillProvider {
         const located = [];
         const userSuites = await this.manager.enabledUserSuites();
         for (const suite of userSuites) {
-            for (const skill of suite.activeSurfaces?.skills === false ? [] : suite.skills) {
+            for (const skill of suite.activeSurfaces.skills === false ? [] : suite.skills) {
                 try {
                     if (parseFrontmatterRecord(await readFile(skill.file, 'utf8')).disabled === true)
                         continue;
@@ -120,7 +122,7 @@ export class SuiteSkillProvider {
         const snapshot = await this.manager.readProjectCatalog(cwd);
         const located = [];
         for (const suite of snapshot.enabledSuites) {
-            for (const skill of suite.activeSurfaces?.skills === false ? [] : suite.skills) {
+            for (const skill of suite.activeSurfaces.skills === false ? [] : suite.skills) {
                 try {
                     if (parseFrontmatterRecord(await readFile(skill.file, 'utf8')).disabled === true)
                         continue;

package/lib/runtime/source-auto-update.js

@@ -0,0 +1,70 @@
+/**
+ * Optional background refresh of every configured market source.
+ *
+ * The `autoUpdateSources` setting (default off) turns this on from the
+ * plugin-config card. While enabled the updater runs one refresh pass every
+ * {@link AUTO_UPDATE_INTERVAL_MS} and then waits again; the first pass runs a
+ * full interval after the switch flips, so enabling the feature never starts
+ * network traffic as a surprise. A pass that is still running when the next
+ * tick arrives is skipped rather than queued, and the timer is unref'd so it
+ * never keeps the DSH process alive on its own.
+ * @module runtime/source-auto-update
+ */
+/** How often the background updater refreshes every source. */
+export const AUTO_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export class SourceAutoUpdater {
+    ctx;
+    refresh;
+    intervalMs;
+    timer;
+    inFlight = false;
+    constructor(ctx, refresh, intervalMs = AUTO_UPDATE_INTERVAL_MS) {
+        this.ctx = ctx;
+        this.refresh = refresh;
+        this.intervalMs = intervalMs;
+    }
+    /** Whether a refresh timer is currently armed. */
+    get enabled() {
+        return this.timer !== undefined;
+    }
+    /** Arm or disarm the interval; repeated calls with the same state do nothing. */
+    setEnabled(enabled) {
+        if (enabled === this.enabled)
+            return;
+        if (!enabled) {
+            this.clearTimer();
+            this.ctx.logger?.info?.('[dsh-agent-plugins-market] background source updates off');
+            return;
+        }
+        this.timer = setInterval(() => void this.run(), this.intervalMs);
+        this.timer.unref?.();
+        this.ctx.logger?.info?.(`[dsh-agent-plugins-market] background source updates on: every ${Math.round(this.intervalMs / 60_000)} minutes`);
+    }
+    /** Disarm the interval; an in-flight pass finishes on its own. */
+    dispose() {
+        this.clearTimer();
+    }
+    clearTimer() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    async run() {
+        if (this.inFlight) {
+            this.ctx.logger?.warn?.('[dsh-agent-plugins-market] background source update skipped: the previous pass is still running');
+            return;
+        }
+        this.inFlight = true;
+        try {
+            await this.refresh();
+            this.ctx.logger?.info?.('[dsh-agent-plugins-market] background source update finished');
+        }
+        catch (error) {
+            this.ctx.logger?.warn?.(`[dsh-agent-plugins-market] background source update failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+}

package/lib/{model/state.js → runtime/state-store.js}

@@ -2,13 +2,14 @@
  * 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.
+ * only writer (through catalog actions and the HTTP routes), and it re-reads
+ * the file whenever a mutation races, keeping the on-disk copy authoritative
+ * like the market profile state this pattern follows. The record shapes live
+ * in `src/model/types.ts`; only the reading and writing live here.
  */
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { SUITE_SURFACE_KEYS } from './types.js';
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { SUITE_SURFACE_KEYS } from '../model/types.js';
 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) {
@@ -86,10 +87,7 @@ function parseSurfaceOverrides(raw) {
     }
     return hasAny ? { surfaces: overrides } : {};
 }
-/** Persist state atomically through a sibling-temp rename. */
+/** Persist state atomically through the harness's atomic-write helper. */
 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);
+    await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
 }

package/lib/runtime/storage-migration.js

@@ -1,8 +1,9 @@
 /** Consolidate plugin-owned storage before stores, routes, or providers are exposed. */
 import { constants } from 'node:fs';
-import { copyFile, lstat, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { expandHome, resolveDataRoot, resolveDshHome, resolveUserRoot } from '../catalog/paths.js';
+import { copyFile, lstat, mkdir, readdir, readFile, rmdir, unlink } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { expandHome, isWithin, resolveAgentsRoot, resolveDataRoot, resolveDshHome, resolveUserRoot } from '../catalog/paths.js';
 async function info(path) {
     try {
         return await lstat(path);
@@ -54,20 +55,24 @@ export async function mergeStorageTree(from, to, result) {
     }
     await unlink(from);
 }
-function contains(parent, child) {
-    const path = relative(parent, child);
-    return path === '' || (!path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && path !== '..' && !isAbsolute(path));
-}
+/** The three hand-authored resource kinds the market panel owns. */
+const PANEL_KINDS = ['skills', 'commands', 'agents'];
 /**
- * Migrate former root overrides and data/user panels into the canonical root.
- * Unknown files in override directories remain untouched. Conflicts remain at
- * the old path and are returned to block activation; reruns are safe.
+ * Migrate former root overrides, data-root panels, and hand-authored
+ * resources into their canonical homes: plugin state under the user/data
+ * roots, and user content under the shared Agent layout root. Unknown files in
+ * override directories remain untouched. Conflicts remain at the old path and
+ * are returned to block activation; reruns are safe.
  */
 export async function migratePluginStorage(config = {}) {
     const userRoot = resolveUserRoot();
     const dataRoot = resolveDataRoot();
+    const agentsRoot = resolveAgentsRoot();
     const result = { conflicts: [] };
-    for (const path of [resolveDshHome(), userRoot, dataRoot, join(userRoot, 'user'), join(userRoot, '.sources')]) {
+    if (isWithin(userRoot, agentsRoot) || isWithin(agentsRoot, userRoot) || isWithin(dataRoot, agentsRoot) || isWithin(agentsRoot, dataRoot)) {
+        throw new Error('The Agent layout root overlaps canonical plugin storage');
+    }
+    for (const path of [resolveDshHome(), userRoot, dataRoot, agentsRoot, join(userRoot, 'user'), join(userRoot, '.sources')]) {
         if ((await info(path))?.isSymbolicLink() === true)
             throw new Error(`Plugin storage cannot use a symbolic-link directory: ${path}`);
     }
@@ -78,7 +83,7 @@ export async function migratePluginStorage(config = {}) {
             throw new Error(`Plugin storage migration cannot traverse a symbolic-link root: ${path}`);
     }
     if (legacyUserRoot !== userRoot) {
-        if (contains(legacyUserRoot, userRoot) || contains(userRoot, legacyUserRoot))
+        if (isWithin(legacyUserRoot, userRoot) || isWithin(userRoot, legacyUserRoot))
             throw new Error('Legacy userRoot overlaps canonical plugin storage');
         const legacySources = join(legacyUserRoot, '.sources');
         const sourceInfo = await info(legacySources);
@@ -123,13 +128,27 @@ export async function migratePluginStorage(config = {}) {
     for (const legacy of new Set([legacyDataRoot, join(resolveDshHome(), 'agent-plugins-data')])) {
         if (legacy === dataRoot)
             continue;
-        if (contains(legacy, dataRoot) || contains(dataRoot, legacy))
+        if (isWithin(legacy, dataRoot) || isWithin(dataRoot, legacy))
             throw new Error('Legacy dataRoot overlaps canonical plugin data storage');
         for (const entry of ['data', 'overrides', 'user', 'settings.json', 'lsp-servers.json', 'feedback']) {
             await mergeStorageTree(join(legacy, entry), join(dataRoot, entry), result);
         }
     }
-    await mergeStorageTree(join(dataRoot, 'user'), join(userRoot, 'user'), result);
+    // Hand-authored resources moved out of plugin storage into the shared Agent
+    // layout root; every former `<root>/user/<kind>` layout maps onto `<kind>`.
+    // Each source is moved straight to its final location so a conflict is
+    // reported at the file the user actually has, not at a hop along the way.
+    for (const kind of PANEL_KINDS) {
+        await mergeStorageTree(join(dataRoot, 'user', kind), join(agentsRoot, kind), result);
+        await mergeStorageTree(join(userRoot, 'user', kind), join(agentsRoot, kind), result);
+    }
+    // Drop the emptied former panel directories; rmdir refuses a non-empty one,
+    // so files retained by a conflict (or an unrecognized kind) keep their home.
+    await rmdir(join(dataRoot, 'user')).catch(() => { });
+    await rmdir(join(userRoot, 'user')).catch(() => { });
+    // Hand-written service declarations moved from data files to Agent-layout files.
+    await mergeStorageTree(join(dataRoot, 'mcp-servers.json'), join(agentsRoot, 'mcp.json'), result);
+    await mergeStorageTree(join(dataRoot, 'lsp-servers.json'), join(agentsRoot, 'lsp.json'), result);
     return result;
 }
 /** Retain all state fields while rebasing adopted checkouts moved with a root. */
@@ -145,15 +164,13 @@ async function relocateManagedSourceUrls(userRoot, legacyUserRoot) {
         if (typeof source !== 'object' || source === null || !('local' in source) || source.local !== true || !('url' in source) || typeof source.url !== 'string')
             continue;
         const oldCheckout = join(legacyUserRoot, '.sources');
-        if (!contains(oldCheckout, resolve(expandHome(source.url))))
+        if (!isWithin(oldCheckout, resolve(expandHome(source.url))))
             continue;
         source.url = join(userRoot, '.sources', relative(oldCheckout, resolve(expandHome(source.url))));
         changed = true;
     }
     if (changed) {
-        const temp = `${path}.migration-${process.pid}.tmp`;
-        await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { flag: 'wx' });
-        await rename(temp, path);
+        await writeFileAtomic(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
     }
 }
 async function collectUnsupportedEntries(path, conflicts) {

package/lib/runtime/subagent-catalog.js

@@ -51,8 +51,8 @@ function escapeText(value) {
 }
 function renderCatalog(entries, update, t) {
     const lines = entries.map(entry => {
-        const route = [entry.provider, entry.model].filter(value => value !== undefined).join('/') || t('subagentCatalogInherit');
-        return `<subagent id="${escapeText(entry.name)}" name="${escapeText(entry.title)}" model="${escapeText(route)}" reasoning_effort="${escapeText(entry.reasoningEffort ?? t('subagentCatalogDefaultEffort'))}">${escapeText(entry.description)}</subagent>`;
+        const config = [entry.provider, entry.model, entry.reasoningEffort].filter(value => value !== undefined).map(escapeText);
+        return `- ${escapeText(entry.name)}: ${escapeText(entry.description)}${config.length === 0 ? '' : ` (${config.join(' / ')})`}`;
     });
     return createUserMessage({
         content: [
@@ -74,7 +74,7 @@ function renderCatalog(entries, update, t) {
 }
 function digestEntries(entries) {
     return createHash('sha256')
-        .update(entries.map(entry => JSON.stringify([entry.name, entry.title, entry.description, entry.provider, entry.model, entry.reasoningEffort])).join('\n'))
+        .update(entries.map(entry => JSON.stringify([entry.name, entry.roleId, entry.title, entry.description, entry.provider, entry.model, entry.reasoningEffort])).join('\n'))
         .digest('hex');
 }
 /** Resumed and forked seeds may carry unvalidated source fields; ignore unreadable catalogs. */
@@ -88,10 +88,11 @@ function readEntries(source) {
         const entry = raw;
         if (typeof entry.name !== 'string' || entry.name === '' || typeof entry.title !== 'string' || typeof entry.description !== 'string')
             return undefined;
-        if (['provider', 'model', 'reasoningEffort'].some(key => entry[key] !== undefined && (typeof entry[key] !== 'string' || entry[key] === '')))
+        if (['roleId', 'provider', 'model', 'reasoningEffort'].some(key => entry[key] !== undefined && (typeof entry[key] !== 'string' || entry[key] === '')))
             return undefined;
         entries.push({
             name: entry.name,
+            ...(entry.roleId === undefined ? {} : { roleId: entry.roleId }),
             title: entry.title,
             description: entry.description,
             ...(entry.provider === undefined ? {} : { provider: entry.provider }),

package/lib/runtime/user-commands.js

@@ -62,9 +62,9 @@ export class UserCommandMountRegistry {
                     ...(spec.hint === undefined ? {} : { input: { hint: spec.hint } }),
                     handler: invocation => {
                         const agent = invocation.agent;
-                        const text = [this.t('userCommandForwardTitle', { command: spec.name }), '', spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim())].join('\n');
+                        const text = spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim());
                         agent.followup({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' } });
-                        return { kind: 'success', text: this.t('userCommandAcknowledged', { command: spec.name }) };
+                        return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                     }
                 });
                 this.live.set(key, disposer);

package/lib/runtime/user-panels.js

@@ -1,8 +1,9 @@
 /**
  * User panel storage: the persistence layer behind the skills / commands /
  * agent-personas panels. Each surface owns one directory of Markdown files
- * under `<userRoot>/user/<kind>/`, so user-authored entries survive restarts,
- * are trivially hand-editable, and stay outside suite checkouts.
+ * under the shared Agent layout root (`~/.agents/<kind>/`), so user-authored
+ * entries survive restarts, are trivially hand-editable, and stay outside
+ * suite checkouts.
  *
  * Skills entries follow the SKILL.md frontmatter grammar (`name`,
  * `description`, optional `whenToUse`, invocation controls) plus a
@@ -16,27 +17,35 @@ import { join } from 'node:path';
 import { deleteEntryFile, entryExists, listEntryFiles, readEntryFile, USER_ENTRY_NAME, userEntryDir, 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';
-/** Ranks sit behind every shipped root so real files always win a name clash. */
-const USER_PANEL_RANK = 600;
+/**
+ * Panel skills outrank both the harness's reader of this directory and the
+ * suite skills an install adds.
+ *
+ * `dsh-skill-filesystem` maps `~/.agents/skills` as its `user-agents` root at
+ * rank 500, and a lower rank wins a duplicated skill name. Sitting behind it
+ * handed every entry to that reader, which knows neither this panel's
+ * `disabled` frontmatter nor its localized description, so a skill the user
+ * disabled stayed loaded. At 440 the panel keeps its own controls; project
+ * roots (100-300) and the user's `~/.dsh` skills (400) still outrank it, while
+ * a skill the user wrote by hand now beats one an installed suite ships under
+ * the same name (the suite user rank is 450).
+ */
+const USER_PANEL_RANK = 440;
 /** Throwing CRUD over one panel directory, shared by the three panels. */
 export class UserPanelStore {
-    dataRoot;
+    agentsRoot;
     kind;
     extraNameCheck;
-    constructor(dataRoot, kind, 
+    constructor(agentsRoot, kind, 
     /** Extra name grammar for this panel (runs after USER_ENTRY_NAME). */
     extraNameCheck = () => true) {
-        this.dataRoot = dataRoot;
+        this.agentsRoot = agentsRoot;
         this.kind = kind;
         this.extraNameCheck = extraNameCheck;
     }
-    /** The panel's directory under the data root. */
+    /** The panel's directory under the Agent layout root. */
     dirPath() {
-        return userEntryDir(this.dataRoot, this.kind);
-    }
-    /** The plugin data root the panel lives under. */
-    root() {
-        return this.dataRoot;
+        return userEntryDir(this.agentsRoot, this.kind);
     }
     get dir() {
         return this.dirPath();
@@ -102,11 +111,11 @@ export class UserPanelStore {
     }
 }
 /** Locate the three stores; constructed once per plugin activation. */
-export function createUserPanelStores(dataRoot) {
+export function createUserPanelStores(agentsRoot) {
     return {
-        skills: new UserPanelStore(dataRoot, 'skills', isUserSkillEntryName),
-        commands: new UserPanelStore(dataRoot, 'commands'),
-        agents: new UserPanelStore(dataRoot, 'agents', isUserSkillEntryName)
+        skills: new UserPanelStore(agentsRoot, 'skills', isUserSkillEntryName),
+        commands: new UserPanelStore(agentsRoot, 'commands'),
+        agents: new UserPanelStore(agentsRoot, 'agents', isUserSkillEntryName)
     };
 }
 /**
@@ -125,11 +134,9 @@ export function isUserSkillEntryName(name) {
  */
 export class UserPanelSkillProvider {
     skills;
-    t;
     name = 'user-panel';
-    constructor(skills, t) {
+    constructor(skills) {
         this.skills = skills;
-        this.t = t;
     }
     async list(_options) {
         const candidates = [];
@@ -139,7 +146,10 @@ export class UserPanelSkillProvider {
                 continue;
             candidates.push({
                 name: entry.name,
-                description: this.t('userSkillDescription', { description: entry.description === '' ? entry.name : entry.description }),
+                // The entry's own description verbatim; a user-entry label is our
+                // packaging, and this description reaches the same model-facing
+                // catalog a suite skill does.
+                description: entry.description === '' ? entry.name : entry.description,
                 ...(typeof entry.metadata['whenToUse'] === 'string' && entry.metadata['whenToUse'] !== '' ? { whenToUse: entry.metadata['whenToUse'] } : {}),
                 invocation: {
                     modelInvocable: entry.metadata['disable-model-invocation'] !== true,

package/lib/runtime/user-store.js

@@ -6,29 +6,29 @@
  * the runtime mounts.
  * @module runtime/user-store
  */
-import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { parseDocument, stringify } from 'yaml';
 import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
-/** Where user panel entries persist: `<userRoot>/user/<kind>/`. */
-export function userEntryDir(dataRoot, kind) {
-    return join(dataRoot, 'user', kind);
+/** Where user panel entries persist: `<agentsRoot>/<kind>/`. */
+export function userEntryDir(agentsRoot, kind) {
+    return join(agentsRoot, kind);
 }
 /** `[a-z][a-z0-9_-]*` — the grammar every panel entry name must satisfy. */
 export const USER_ENTRY_NAME = /^[a-z][a-z0-9_-]*$/;
-/** The enablement frontmatter key shared by skills and commands. */
-export const DISABLED_KEY = 'disabled';
 /** Parse full YAML metadata without flattening arrays, mappings, or multiline strings. */
 export function parseFrontmatterRecord(text) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
-    if (match === null) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1];
+    if (frontmatter === undefined) {
         if (/^---(?:\r?\n|$)/.test(text))
             throw new Error('Invalid frontmatter: missing closing delimiter');
         return {};
     }
-    const doc = parseDocument(match[1]);
-    if (doc.errors.length > 0)
-        throw new Error(`Invalid frontmatter: ${doc.errors[0].message}`);
+    const doc = parseDocument(frontmatter);
+    const error = doc.errors[0];
+    if (error !== undefined)
+        throw new Error(`Invalid frontmatter: ${error.message}`);
     const value = doc.toJS({ maxAliasCount: 100 });
     if (value === null)
         return {};
@@ -104,8 +104,7 @@ export async function listEntryFiles(dir, strict = false) {
 export async function writeEntryFile(dir, name, text) {
     assertEntryName(name);
     parseFrontmatterRecord(text);
-    await mkdir(dir, { recursive: true });
-    await writeFile(join(dir, `${name}.md`), text, 'utf8');
+    await writeFileAtomic(join(dir, `${name}.md`), text, { mode: 0o644, dirMode: 0o700 });
 }
 /**
  * Enforce the entry-name grammar at every filesystem choke point. The name

package/lib/types/application/catalog-context.d.ts

@@ -0,0 +1,118 @@
+import type { GitOptions } from '../catalog/git.js';
+import { type DiscoveredSuite, type InstalledEntry, type Suite, type SuiteDimension, type SuiteState } from '../model/types.js';
+import type { CatalogPortsOverride } from './ports.js';
+import { SnapshotCache, type SnapshotHost } from './snapshot-cache.js';
+/**
+ * Git network tuning, plumbed from the host config to every remote-touching
+ * invocation (proxy, `insteadOf` mirrors, timeout, retry). `fallbackTarball`
+ * additionally lets a failed GitHub clone fall back to a codeload tarball
+ * download through the archive pipeline.
+ */
+export interface CatalogGitOptions extends GitOptions {
+    /** Retry a failed GitHub clone as a codeload tarball download; default false. */
+    fallbackTarball?: boolean;
+    /** Allow plain-http archive downloads (intranet mirrors); default false. */
+    allowHttpArchives?: boolean;
+}
+/** Dependencies and host callback used by the catalog application module. */
+export interface CatalogOptions {
+    userRoot: string;
+    dataRoot: string;
+    /** Shared Agent layout root holding the user's hand-authored resources and service declarations. */
+    agentsRoot: string;
+    onChanged: () => void | Promise<void>;
+    /** Git/archive acquisition tuning. */
+    git?: CatalogGitOptions;
+    /** Host seams; unwired members fall back to the defaults in `ports.ts`. */
+    ports?: CatalogPortsOverride;
+    /**
+     * Freshness window for cached project-dimension snapshots. The project
+     * catalog sits on the skill-list hot path (every provider `list()` call),
+     * and its inputs — the project's own files — change only through editor
+     * saves; a short window keeps listing cheap without going stale. Defaults
+     * to 5 seconds; 0 disables caching.
+     */
+    projectSnapshotTtlMs?: number;
+    /**
+     * Freshness window for the cached user-dimension snapshot (defaults to the
+     * scan-cache TTL). It bounds how long out-of-band edits to local sources
+     * stay invisible; 0 disables snapshot caching. Tests pass a small value so
+     * staleness regressions need no real sleeps.
+     */
+    userSnapshotTtlMs?: number;
+}
+/** Key of one install entry in the persisted `installed` record. */
+export declare function installKey(sourceId: string, suiteId: string): string;
+/**
+ * How long an explicit caller waits for the derived refresh before answering
+ * anyway. The refresh keeps running; only the wait ends.
+ */
+export declare const DERIVED_REFRESH_WAIT_MS = 10000;
+export declare class CatalogContext implements SnapshotHost {
+    private currentState;
+    private mutationQueue;
+    private currentRevision;
+    private currentScanGeneration;
+    private scanProjectLayoutsEnabled;
+    /** The derived refresh in flight, shared by every change that lands while it runs. */
+    private refreshPass;
+    /** Whether a change landed after the running pass started; it earns one more pass. */
+    private refreshQueued;
+    readonly statePath: string;
+    readonly userRoot: string;
+    readonly dataRoot: string;
+    readonly agentsRoot: string;
+    readonly git: CatalogGitOptions;
+    /** Discovery scans and dimension snapshots derived from {@link state}. */
+    readonly snapshots: SnapshotCache;
+    private readonly onChanged;
+    constructor(options: CatalogOptions);
+    get state(): SuiteState;
+    /** Bumped by every mutation: a snapshot built at an older revision is never published. */
+    get revision(): number;
+    /** Bumped by every content-changing mutation: a scan started earlier never repopulates its cache. */
+    get scanGeneration(): number;
+    /** Whether native project layouts (`.claude/`, `.agents/`) take part in discovery. */
+    get scanProjectLayouts(): boolean;
+    /** One install entry, or undefined when the suite is not installed. */
+    installed(sourceId: string, suiteId: string): InstalledEntry | undefined;
+    /** Load persisted user state once at plugin activation. */
+    load(): Promise<void>;
+    /** Replace the persisted state and write it out. */
+    commit(next: SuiteState): Promise<void>;
+    /** Apply the host's project-layout switch and invalidate every project snapshot. */
+    setScanProjectLayouts(enabled: boolean): Promise<void>;
+    /**
+     * Apply the install state to freshly discovered suites: enablement, the
+     * effective surface toggles, and the lock/install timestamps the market
+     * cards report.
+     */
+    project(discovered: readonly DiscoveredSuite[], state: SuiteState, dimension: SuiteDimension): Suite[];
+    /**
+     * Invalidate snapshots and schedule the change pipeline. `keepScanCache`
+     * marks state-only mutations (install, enable, surface toggles, MCP
+     * overrides) whose inputs leave every checkout untouched, so the next
+     * snapshot re-derives from cached discovery instead of rescanning the
+     * filesystem.
+     *
+     * The invalidation is synchronous and the refresh is coalesced in the
+     * background: resolving here means the state is durable, never that every
+     * mount has finished. Callers that must observe the refreshed surfaces await
+     * {@link refreshSettled}, whose wait is bounded so one stuck mount cannot
+     * hold a request — or the next mutation behind it — open.
+     */
+    notifyChanged(keepScanCache?: boolean): Promise<void>;
+    /**
+     * Resolve once the queued derived refresh finishes, `false` when the deadline
+     * elapses first. The refresh itself is never cancelled.
+     */
+    refreshSettled(deadlineMs?: number): Promise<boolean>;
+    /** Queue one derived refresh; a pass already in flight absorbs it. */
+    private scheduleRefresh;
+    /** Drop every cached dimension snapshot; `increment` advances the revision. */
+    invalidateSnapshot(increment: boolean): void;
+    /** Drop cached discovery and advance the generation a scan is validated against. */
+    invalidateScans(): void;
+    /** Serialize one mutation behind every mutation queued before it. */
+    enqueue<T>(operation: () => Promise<T>): Promise<T>;
+}