dsh-agent-plugins-market 0.6.2 → 0.7.1

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

@@ -0,0 +1,124 @@
+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;
+    /**
+     * The project-layout switch in effect. The host settings document owns the
+     * value and pushes it here on registration and on every change; the initial
+     * value is the contract's declared default, which is what the catalog would
+     * read from the document before the settings service resolves.
+     */
+    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>;
+}

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

@@ -1,251 +1,66 @@
-import { type GitOptions } from '../catalog/git.js';
-import { type McpToolSnapshot } from '../runtime/mcp-status.js';
+import type { LspLegacySeamMigration, LspStatusPayload } from '../contracts/lsp-status.js';
+import type { OverviewPayload, ServerConfigPayload, SkillContent, SourceProgress, SuiteDetail } from '../contracts/market.js';
+import type { McpStatusPayload } from '../contracts/mcp-status.js';
+import type { SourceRef, Suite, SuiteSurfaceKey } from '../model/types.js';
+import type { McpBackend } from '../runtime/mcp-backend.js';
 import type { McpMountDiagnostic } from '../runtime/mcp-mounts.js';
-import { type LspMountStatusSource } from '../runtime/lsp-status.js';
 import { type McpServerOverride, type McpSuiteOverrides } from '../runtime/mcp-overrides.js';
-import { type HostMcpClientProbe, type McpBackend } from '../runtime/mcp-backend.js';
-import { type DownloadRegionSetting, type EffectiveRegion } from '../runtime/regions.js';
-import type { McpStatusPayload } from '../contracts/mcp-status.js';
-import type { LspStatusPayload } from '../contracts/lsp-status.js';
-import type { OverviewPayload, ServerConfigPayload, SkillContent, SuiteDetail } from '../contracts/market.js';
-import { type SourceKind, type SourceRef, type Suite, type SuiteDimension, type SuiteSurfaceKey } from '../model/types.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;
-    onChanged: () => void | Promise<void>;
-    /** Git/archive acquisition tuning. */
-    git?: CatalogGitOptions;
-    /**
-     * 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;
-}
-/** A coherent discovered-and-installed view for one catalog dimension. */
-export interface CatalogSnapshot {
-    revision: number;
-    sources: SourceRef[];
-    suites: Suite[];
-    enabledSuites: Suite[];
-    /** Per-source scan diagnostics (sourceId → notes), absent when clean. */
-    scanNotes?: Record<string, string[]>;
-}
-export declare class Catalog {
-    private readonly options;
-    private state;
-    private mutationQueue;
-    private readonly statePath;
-    private readonly headCache;
-    private readonly listeners;
-    private revision;
-    private userSnapshot;
-    private userSnapshotExpiresAt;
-    private userSnapshotPromise;
-    /**
-     * Discovery scan cache: per-sources-fingerprint scan results with a TTL.
-     * Install / enable / surface toggles re-derive the snapshot from cached
-     * discovery (cheap mapping) instead of re-walking every checkout — a full
-     * rescan of a 2,500-suite catalog costs ~1s and UI mutations happen in
-     * bursts. Content-changing mutations (add / update / remove / adopt /
-     * refresh / acquire) clear every cached discovery generation; the TTL
-     * bounds staleness for in-place working-tree
-     * edits of local sources.
-     */
-    private readonly scanCache;
-    private scanGeneration;
-    private readonly scanPromises;
-    private static readonly SCAN_CACHE_TTL_MS;
-    private static readonly SCAN_CACHE_MAX_ENTRIES;
-    /**
-     * User-dimension snapshot TTL: bounded staleness for edits made outside the
-     * plugin (a new skill dropped into a local source's working tree, a hand
-     * edit in a project layout) becomes visible on the next read past the TTL
-     * instead of living until the next mutation. Configurable; a 0 value
-     * disables snapshot caching entirely.
-     */
-    private readonly userSnapshotTtlMs;
-    /** Project-dimension snapshots keyed by project root, with TTL freshness. */
-    private readonly projectSnapshots;
-    private readonly projectSnapshotPromises;
-    private readonly projectSnapshotTtlMs;
+import { type CatalogGitOptions, type CatalogOptions } from './catalog-context.js';
+import { type LspServerTable, type McpBackendInfo, type SourceInput, type SourcePatch } from './ports.js';
+import { type CatalogSnapshot } from './snapshot-cache.js';
+import { codeloadTarballUrl } from './source-store.js';
+import type { MarketService } from './queries.js';
+export declare class Catalog implements MarketService {
+    private readonly context;
+    private readonly ports;
+    private readonly snapshots;
+    private readonly sourceStore;
+    private readonly installs;
+    private readonly mcp;
+    private readonly lsp;
+    constructor(options: CatalogOptions);
     /** Latest MCP mount diagnostics (suiteId -> reasons), fed by host reconcile. */
-    mcpDiagnostics: McpMountDiagnostic[];
-    /** Latest LSP mount diagnostics source, wired by the host entry. */
-    private lspStatusSource;
-    /** Credential-store seam for dropping a grant record (MCP re-authorize). */
-    private credentialsStore;
-    private toolSnapshotProvider;
-    /** Mount-registry seam: flags a mount key for an explicit rebuild (re-authorize). */
-    private mcpRemount;
-    /** Resolves the mount key owning one derived serverName; absent when the server is not mounted. */
-    private mcpServerOwner;
-    /** Backend source (the host settings namespace scope); default is the built-in client. */
-    private mcpBackendProvider;
-    /** Backend writer (a scope update); absent until the settings service resolves. */
-    private mcpBackendWriter;
-    /** Download-region source (the host settings namespace scope). */
-    private downloadRegionProvider;
-    private scanProjectLayouts;
+    get mcpDiagnostics(): McpMountDiagnostic[];
+    set mcpDiagnostics(value: McpMountDiagnostic[]);
+    /** The user-dimension suite root this catalog operates. */
+    get userRoot(): string;
+    /** The plugin storage root holding per-suite `${PLUGIN_DATA}` directories and overrides. */
+    get dataRoot(): string;
+    get sources(): SourceRef[];
+    /** Whether one suite currently carries an install entry. */
+    isInstalled(sourceId: string, suiteId: string): boolean;
     /** Apply the host's project-layout switch and invalidate every project snapshot. */
     setScanProjectLayouts(enabled: boolean): Promise<void>;
-    constructor(options: CatalogOptions);
-    /** Install the host tool snapshot provider used by the MCP status surface. */
-    setMcpToolSnapshotProvider(provider: () => readonly McpToolSnapshot[]): void;
-    /** Install the credential-store seam backing the MCP re-authorize action. */
-    setCredentialsStore(store: {
-        deleteGrantRecord(serverName: string): Promise<void>;
-    }): void;
-    /**
-     * Drop one MCP server's OAuth grant record so the next mount re-runs the
-     * browser authorization — the path for "I picked too narrow a scope".
-     * @param serverName - the derived serverName whose folded form keys the record.
-     * @throws when the credentials service is not mounted.
-     */
-    reauthorizeMcpServer(serverName: string): Promise<void>;
-    /**
-     * Install the MCP remount seam used by re-authorize: the registry flags the
-     * mount so the next reconcile tears the live bridge down and rebuilds it.
-     */
-    setMcpRemountHook(hook: (suiteId: string, serverKey: string) => void, serverOwner: (serverName: string) => {
-        suiteId: string;
-        serverKey: string;
-    } | undefined): void;
-    /** Whether the re-authorize action can run in this composition. */
-    mcpReauthorizeAvailable(): boolean;
-    /** Install the LSP mount status source used by the LSP status surface. */
-    setLspStatusSource(source: LspMountStatusSource): void;
-    /** Subscribe to completed catalog mutations; returns an unsubscribe function. */
-    subscribe(listener: () => void): () => void;
-    /** Build the flat MCP service inventory for the status surface. */
-    mcpStatus(): Promise<McpStatusPayload>;
-    /** Persist a user-owned MCP service and reconcile its bridge mount. */
-    addMcpServer(name: string, server: unknown): Promise<void>;
-    /** Read effective service configuration without exposing credential literals. */
-    serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
-    private resolveServerConfig;
-    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
-    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
-    /** The LSP status surface: declared servers merged with mount diagnostics. */
-    lspStatus(): Promise<LspStatusPayload>;
-    /** The user's direct LSP server table (normalized specs). */
-    lspServers(): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
-    /** Create one direct LSP declaration without replacing other user servers. */
-    addLspServer(name: string, config: unknown): Promise<void>;
-    /** Validate and persist the user's direct LSP server table. */
-    setLspServers(raw: unknown): Promise<Record<string, import('../model/types.js').LspServerSpec>>;
-    setLspServerEnabled(id: string, enabled: boolean): Promise<void>;
-    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
-    mcpOverrides(sourceId: string, suiteId: string): Promise<McpSuiteOverrides>;
-    /**
-     * Set or clear one server's MCP override and remount it. `override === null`
-     * clears the override (back to the source config). The serverKey must exist
-     * in the suite's parsed mcp.json.
-     */
-    setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
-    /**
-     * Re-run the MCP reconcile pass: retries failed mounts and clears residual
-     * tools, without changing any catalog state.
-     */
-    retryMounts(): Promise<void>;
-    /** The persisted backend choice without the host-client probe (mount-time provider). */
-    mcpBackend(): Promise<McpBackend>;
+    /** Load persisted user state once at plugin activation. */
+    load(): Promise<void>;
+    /** Append config-seeded sources missing from user state and persist them. */
+    mergeSources(sources: SourceRef[]): Promise<void>;
     /**
-     * The active MCP mount backend plus a live probe of the host client, and
-     * the download-region setting with its locale-resolved effective route —
-     * everything the plugin-config card renders.
+     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
+     * (skills / commands / agent personas). Catalog state is untouched — this
+     * only runs the change pipeline so the runtime remounts commands and the
+     * skill providers re-read their catalogs.
      */
-    mcpBackendInfo(): Promise<{
-        backend: McpBackend;
-        hostClient: HostMcpClientProbe;
-        downloadRegion: {
-            setting: DownloadRegionSetting;
-            effective: EffectiveRegion;
-        };
-    }>;
+    notifyPanelsChanged(): Promise<void>;
     /**
-     * Switch the MCP mount backend and remount every suite server through it.
-     * A host-client switch takes effect only where the host package resolves;
-     * unresolvable or unsupported transports surface as per-server diagnostics.
+     * Wait for the derived refresh triggered by the latest change, bounded so a
+     * stuck mount reports back instead of holding an explicit retry open.
      */
-    setMcpBackend(backend: McpBackend): Promise<void>;
-    /** Install the backend source (the host settings namespace's scope). */
-    setMcpBackendProvider(provider: () => Promise<McpBackend>): void;
-    /** Install the backend writer (a scope update on the same namespace). */
-    setMcpBackendWriter(writer: (backend: McpBackend) => Promise<void>): void;
-    /** Install the download-region source (the host settings namespace scope). */
-    setDownloadRegionProvider(provider: () => Promise<DownloadRegionSetting>): void;
-    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
-    allMcpOverrides(suites?: readonly Suite[]): Promise<Map<string, McpSuiteOverrides>>;
-    /** Load persisted user state once at plugin activation. */
-    load(): Promise<void>;
-    get sources(): SourceRef[];
-    /** The user-dimension suite root this catalog operates. */
-    get userRoot(): string;
+    refreshSettled(deadlineMs?: number): Promise<boolean>;
     /** Read one coherent user-dimension snapshot, reusing in-flight discovery. */
     readUserCatalog(): Promise<CatalogSnapshot>;
     /** Read one coherent project-dimension snapshot for a workspace cwd. */
     readProjectCatalog(cwd: string): Promise<CatalogSnapshot>;
-    private buildProjectSnapshot;
+    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
+    enabledUserSuites(): Promise<Suite[]>;
+    /** The full market overview from one user snapshot. */
+    overview(): Promise<OverviewPayload>;
     /** One suite's full detail for the market detail modal. */
     suiteDetail(sourceId: string, suiteId: string): Promise<SuiteDetail>;
     /** One skill's full SKILL.md text for the market detail modal. */
     skillContent(sourceId: string, suiteId: string, skillName: string): Promise<SkillContent>;
-    /** The full market overview from one user snapshot. */
-    overview(): Promise<OverviewPayload>;
-    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
-    enabledUserSuites(): Promise<Suite[]>;
-    /** Enabled user- and project-dimension suites for a workspace cwd. */
-    enabledSuitesForCwd(cwd: string): Promise<{
-        user: Suite[];
-        project: Suite[];
-    }>;
-    /** All suites of one dimension. */
-    suitesForDimension(dimension: SuiteDimension, dimensionRoot: string): Promise<Suite[]>;
-    /**
-     * Add a source and acquire it immediately (clone, download, or in-place).
-     *
-     * Git sources with an already-present checkout whose `origin` matches the
-     * input URL are adopted in place — the manual-clone repair path — so no
-     * second clone is made and no `-2` suffixed id is invented. Adopted
-     * checkouts are never deleted on source removal.
-     */
-    addSource(input: {
-        url: string;
-        branch?: string;
-        local?: boolean;
-        kind?: SourceKind;
-        sha256?: string;
-    }): Promise<SourceRef>;
-    /**
-     * First candidate id whose `.sources/` checkout already exists and whose
-     * `origin` remote matches the input URL (canonical-form equality) — the
-     * signature of a manual clone of the very same repository. Registered ids
-     * and checkouts of differently-origined directories never adopt.
-     */
-    private findAdoptableCheckout;
+    /** Add a source and acquire it immediately (clone, download, or in-place). */
+    addSource(input: SourceInput): Promise<SourceRef>;
     /** Register one unmanaged `.sources/` checkout as a source without touching its files. */
     adoptSource(id: string): Promise<SourceRef>;
     /** Unmanaged `.sources/` checkouts: present on disk, absent from state. */
@@ -253,53 +68,21 @@ export declare class Catalog {
         id: string;
         url?: string;
     }>>;
-    /** Progress snapshot of the source mutation currently in flight. */
-    private currentSourceState;
+    /** Update one source's URL, branch, kind, or archive digest. */
+    updateSource(sourceId: string, patch: SourcePatch): Promise<void>;
+    /** Remove a source and its install entries; `deleteCheckout` also deletes the managed checkout. */
+    removeSource(sourceId: string, deleteCheckout?: boolean): Promise<void>;
+    /** Refresh one source checkout, or every source when sourceId is omitted. */
+    refreshSource(sourceId?: string): Promise<void>;
+    /** Progress snapshot for the progress route. */
+    sourceProgress(): SourceProgress;
     /** Begin reporting progress for a source mutation. */
     beginSourceState(sourceId: string, step: string, cloned: boolean): void;
     /** Advance the in-flight source mutation step. */
     updateSourceStep(step: string): void;
     /** Stop reporting source mutation progress. */
     endSourceState(): void;
-    /** Progress snapshot for the progress route. */
-    sourceProgress(): {
-        active: boolean;
-        sourceId: string;
-        step: string;
-    };
-    /**
-     * First candidate id not claimed by a registered source; for git candidates
-     * the checkout directory must also be free, so a stale or foreign directory
-     * under `.sources/` is never cloned over (it would fail `git clone` with a
-     * confusing "destination exists" error). `ownedCheckout` marks the directory
-     * the in-flight mutation already controls, keeping a rename onto it legal.
-     * Local sources skip the disk check: they read their own path in place and
-     * never occupy `.sources/`.
-     */
-    private pickSourceId;
-    /** Update one source's URL, branch, kind, or archive digest. */
-    updateSource(sourceId: string, patch: {
-        url?: string;
-        branch?: string;
-        local?: boolean;
-        kind?: SourceKind;
-        sha256?: string;
-    }): Promise<void>;
-    /**
-     * Remove a source and its install entries. `deleteCheckout` (the UI's
-     * "also delete the managed market directory" option) physically removes the
-     * `.sources/<id>` checkout — including an adopted one, since a directory
-     * under `.sources` is manager-owned storage. A `local` source whose URL
-     * points outside `.sources` is registration-only: its directory is never
-     * touched. Deleting the checkout is what keeps a removed source from
-     * reappearing as an unmanaged entry.
-     */
-    removeSource(sourceId: string, deleteCheckout?: boolean): Promise<void>;
-    /** Refresh one source checkout, or every source when sourceId is omitted. */
-    refreshSource(sourceId?: string): Promise<void>;
-    /** Install a suite from a source and enable it. The client confirms the
-     * injected surfaces (skills / MCP / hooks / commands) in a pre-install
-     * dialog before this runs; disabling afterwards is always available. */
+    /** Install a suite from a source and enable it. */
     install(sourceId: string, suiteId: string): Promise<void>;
     /** Uninstall a suite while retaining the source checkout. */
     uninstall(sourceId: string, suiteId: string): Promise<void>;
@@ -307,42 +90,63 @@ export declare class Catalog {
     setEnabled(sourceId: string, suiteId: string, enabled: boolean): Promise<void>;
     /** Enable or disable one runtime surface of an installed suite. */
     setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
-    /** Append config-seeded sources missing from user state and persist them. */
-    mergeSources(sources: SourceRef[]): Promise<void>;
+    /** Build the flat MCP service inventory for the status surface. */
+    mcpStatus(): Promise<McpStatusPayload>;
+    /** Persist a user-owned MCP service and reconcile its bridge mount. */
+    addMcpServer(name: string, server: unknown): Promise<void>;
+    /** Read effective service configuration without exposing credential literals. */
+    serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    saveServerConfig(kind: 'mcp' | 'lsp', id: string, config: unknown): Promise<void>;
+    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
+    mcpOverrides(sourceId: string, suiteId: string): Promise<McpSuiteOverrides>;
+    /** Set or clear one server's MCP override and remount it. */
+    setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
     /**
-     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
-     * (skills / commands / agent personas). Catalog state is untouched — this
-     * only runs the change pipeline so the runtime remounts commands and the
-     * skill providers re-read their catalogs.
+     * Enable or disable one declared MCP server, addressed by the same
+     * source-qualified suite id its status row carries. Disabling writes an
+     * override rather than editing the suite's `mcp.json`, so a refresh cannot
+     * clobber the user's choice.
      */
-    notifyPanelsChanged(): Promise<void>;
-    private setInstalled;
+    setMcpServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
+    /** Re-run the MCP reconcile pass without changing any catalog state. */
+    retryMounts(): Promise<void>;
+    /** The persisted MCP backend choice without the host-client probe. */
+    mcpBackend(): Promise<McpBackend>;
     /**
-     * Acquire one source's content by kind: clone (git), download+extract
-     * (archive), or an in-place existence check (local). Returns a lock value
-     * when the acquisition yields one (archive SHA-256, tarball fallback
-     * digest); git HEAD is read separately by the callers.
+     * The active MCP mount backend plus a live probe of the host client, and
+     * the download-region setting with its locale-resolved effective route.
      */
-    private acquire;
-    /** The filesystem location of one source. */
-    private sourceCheckoutPath;
-    private buildSnapshot;
-    private invalidateSnapshot;
-    private invalidateScans;
+    mcpBackendInfo(): Promise<McpBackendInfo>;
+    /** Switch the MCP mount backend and remount every suite server through it. */
+    setMcpBackend(backend: McpBackend): Promise<void>;
+    /**
+     * Drop one MCP server's OAuth grant record so the next mount re-runs the
+     * browser authorization.
+     * @throws when the credentials service is not mounted.
+     */
+    reauthorizeMcpServer(serverName: string): Promise<void>;
+    /** Whether the re-authorize action can run in this composition. */
+    mcpReauthorizeAvailable(): boolean;
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    allMcpOverrides(suites?: readonly Suite[]): Promise<Map<string, McpSuiteOverrides>>;
+    /** The LSP status surface: declared servers merged with mount diagnostics. */
+    lspStatus(): Promise<LspStatusPayload>;
+    /** The user's direct LSP server table (normalized specs). */
+    lspServers(): Promise<LspServerTable>;
+    /** Create one direct LSP declaration without replacing other user servers. */
+    addLspServer(name: string, config: unknown): Promise<void>;
+    /** Validate and persist the user's direct LSP server table. */
+    setLspServers(raw: unknown): Promise<LspServerTable>;
+    /** Enable or disable one declared language server by row id. */
+    setLspServerEnabled(id: string, enabled: boolean): Promise<void>;
     /**
-     * Invalidate snapshots and run 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.
+     * Remove one profile's legacy LSP layer — the hand-written
+     * `cordis.patch.yml` rows an older release told users to add, which now
+     * register a seam this plugin owns.
      */
-    private notifyChanged;
-    private enqueue;
+    migrateLegacyLspSeam(profile: string): Promise<LspLegacySeamMigration>;
 }
-/**
- * The codeload tarball URL of a GitHub repository, or undefined for any
- * other host. `https://github.com/<owner>/<repo>` maps to
- * `https://codeload.github.com/<owner>/<repo>/tar.gz/refs/heads/<branch>`
- * (or `/tar.gz/HEAD` for the default branch) — the git-protocol fallback
- * when a clone cannot get through but plain HTTPS file download can.
- */
-export declare function codeloadTarballUrl(url: string, branch: string | undefined): string | undefined;
+export type { CatalogGitOptions, CatalogOptions };
+export type { CatalogSnapshot };
+export { codeloadTarballUrl };

package/lib/types/application/install-store.d.ts

@@ -0,0 +1,21 @@
+import { type SourceRef, type SuiteSurfaceKey } from '../model/types.js';
+import { type CatalogContext } from './catalog-context.js';
+import { type SourceStore } from './source-store.js';
+export declare class InstallStore {
+    private readonly context;
+    private readonly sources;
+    constructor(context: CatalogContext, sources: SourceStore);
+    /** Install a suite from a source and enable it. The client confirms the
+     * injected surfaces (skills / MCP / hooks / commands) in a pre-install
+     * dialog before this runs; disabling afterwards is always available. */
+    install(sourceId: string, suiteId: string): Promise<void>;
+    /** Uninstall a suite while retaining the source checkout. */
+    uninstall(sourceId: string, suiteId: string): Promise<void>;
+    /** Enable or disable an installed suite. */
+    setEnabled(sourceId: string, suiteId: string, enabled: boolean): Promise<void>;
+    /** Enable or disable one runtime surface of an installed suite. */
+    setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
+    /** Append config-seeded sources missing from user state and persist them. */
+    mergeSources(sources: SourceRef[]): Promise<void>;
+    private setInstalled;
+}

package/lib/types/application/lsp-service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LSP use cases: the status surface, the user's direct server table, and the
+ * per-server enable switch.
+ *
+ * Direct servers live in the shared Agent layout root (`~/.agents/lsp.json`)
+ * and are merged with the suites' inline declarations at mount time; a
+ * suite's own declaration stays source-owned and is never rewritten. The
+ * per-server enable switch stays plugin state under the data root.
+ */
+import type { LspLegacySeamMigration, LspStatusPayload } from '../contracts/lsp-status.js';
+import type { CatalogContext } from './catalog-context.js';
+import type { CatalogPorts, LspServerTable } from './ports.js';
+export declare class LspService {
+    private readonly context;
+    private readonly ports;
+    constructor(context: CatalogContext, ports: CatalogPorts);
+    /** The LSP status surface: declared servers merged with mount diagnostics. */
+    status(): Promise<LspStatusPayload>;
+    /** The profile layer behind a reported seam conflict, when one can be found. */
+    private legacySeam;
+    /**
+     * Remove one profile's legacy LSP layer, then re-reconcile.
+     *
+     * The removal edits a file the user owns, so the profile is matched against
+     * what was actually found on disk instead of trusting the request.
+     */
+    migrateLegacySeam(profile: string): Promise<LspLegacySeamMigration>;
+    /** The user's direct LSP server table (normalized specs). */
+    servers(): Promise<LspServerTable>;
+    /** Create one direct LSP declaration without replacing other user servers. */
+    addServer(name: string, config: unknown): Promise<void>;
+    /** Validate and persist the user's direct LSP server table. */
+    setServers(raw: unknown): Promise<LspServerTable>;
+    /** Enable or disable one declared language server by row id. */
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+}