dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/types/runtime/mcp-client/config.d.ts

@@ -10,8 +10,6 @@
  */
 import type { ReconnectConfig } from './connection.js';
 import type { McpServerPolicy } from '../../model/types.js';
-export type { ReconnectConfig, ResolvedReconnectPolicy } from './connection.js';
-export { RECONNECT_DEFAULTS } from './connection.js';
 /** Default timeout for individual MCP tool calls (ms). */
 export declare const DEFAULT_TOOL_CALL_TIMEOUT_MS = 60000;
 /** Valid `serverName`, kept below the public tool-name budget. */

package/lib/types/runtime/mcp-client/host-contract.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Structural mirrors of the harness tool-registration surface the bridge
+ * registers against: the runtime accepts the same object shape the upstream
+ * `@deepseek-ai/dsh-tools` bridge registers, so the model-facing behavior is
+ * identical. Mirrored rather than imported so the market never loads a second
+ * copy of the host runtime.
+ *
+ * @module runtime/mcp-client/host-contract
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { JsonSchemaNode } from './json-schema-subset.js';
+/** Lossless JSON value vocabulary the bridge exchanges with the registry. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+    content: JsonValue[];
+    structuredContent?: Structured;
+};
+/** The agent on whose behalf a tool call runs (structural mirror). */
+interface ToolExecutionAgent {
+    session?: {
+        requestHeader?: () => {
+            config?: {
+                provider?: string;
+                model?: string;
+            };
+        } | undefined;
+    };
+    options?: {
+        provider?: string;
+        model?: string;
+    };
+}
+/** Execution identity handed to a tool body (structural mirror). */
+export interface ToolExecution {
+    /** Caller-owned cancellation for this invocation. */
+    readonly signal: AbortSignal;
+    /** The calling agent, when the call came from one. */
+    readonly agent?: ToolExecutionAgent;
+}
+/** A settled tool outcome (structural mirror). */
+export interface ToolExecutionResult {
+    readonly value: JsonValue;
+    readonly content: ContentBlock[];
+    readonly isError: boolean;
+}
+/** One registered tool (structural mirror of the host registration shape). */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly output: {
+        readonly schema: JsonSchemaNode;
+        render(args: unknown, value: JsonValue): ContentBlock[];
+    };
+    execute(args: unknown, exec: ToolExecution): Promise<unknown>;
+    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;
+}
+/**
+ * The host surface the bridge needs: a tool registry, a logger, and the two
+ * optional services image projection consults. Structural — the cordis
+ * context is adapted onto this shape by the bridge shell.
+ */
+export interface ToolHost {
+    readonly logger: {
+        error(message: string): void;
+        warn(message: string): void;
+        info(message: string): void;
+    };
+    readonly tools: {
+        register(definition: ToolDefinition): () => void;
+    };
+    /** Optional service lookup; image projection degrades when absent. */
+    getService?(name: 'attachments' | 'llm'): unknown;
+}
+export {};

package/lib/types/runtime/mcp-client/oauth.d.ts

@@ -22,7 +22,7 @@
  * then last exactly as long as the process.
  *
  * Ported from the harness `dsh-mcp-client` OAuth implementation (upstream
- * commits archived at `docs/upstream-proposal/patches/`); the record format is
+ * commits archived at `docs/developer/upstream-proposal/patches/`); the record format is
  * byte-compatible, so grants written by either implementation are interchangeable.
  *
  * @module runtime/mcp-client/oauth

package/lib/types/runtime/mcp-client/plugin-identity.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This plugin's own identity as advertised to the servers it talks to: the MCP
+ * client implementation name and version, and the RFC 7591 `software_id` /
+ * `software_version` carried in OAuth dynamic-registration metadata.
+ *
+ * The version is read from the installed manifest through Node's package
+ * self-reference, so a release bumps exactly one number — `package.json`. A
+ * copy that can no longer resolve its own manifest (a bundle that inlined this
+ * module) reports {@link UNKNOWN_VERSION} rather than failing the connection.
+ *
+ * @module runtime/mcp-client/plugin-identity
+ */
+/** Name npm and the harness know this plugin by. */
+export declare const PLUGIN_NAME = "dsh-agent-plugins-market";
+/** This plugin's release version. */
+export declare const PLUGIN_VERSION: string;

package/lib/types/runtime/mcp-client/projection.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP result projection: turn the content blocks an MCP server returns into
+ * the host content vocabulary the model sees.
+ *
+ * Text-like blocks collapse into newline-joined text runs; declared images are
+ * decoded, admitted against the live model route, and saved to the durable
+ * attachment store. Every refusal — an unsupported media type, a model that
+ * does not declare image input, a storage fault — projects the block as text
+ * explaining why, and the canonical raw value stays available to programmatic
+ * callers in the tool result.
+ *
+ * Everything here reads an untrusted network payload: the MCP server is an
+ * external process and the SDK's declared-required fields may be absent at
+ * runtime, so each block is narrowed field by field.
+ *
+ * @module runtime/mcp-client/projection
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { JsonValue, McpResult, ToolExecution, ToolHost } from './host-contract.js';
+/** Async rich projection staged for one exact execution. */
+export interface PreparedProjection {
+    /** Canonical MCP value returned by execute before registry materialization. */
+    value: McpResult;
+    /** Synchronous output.render projection expected before finalization. */
+    fallback: ContentBlock[];
+    /** Image-enriched or explicit-refusal projection prepared during execute. */
+    content: ContentBlock[];
+}
+/** Whether an untrusted MCP content array contains a declared image block. */
+export declare function containsImage(content: JsonValue[]): boolean;
+/**
+ * Decode, preflight, and durably save one MCP result's ordered image batch.
+ * Any refusal projects every image as text while retaining the canonical raw
+ * value for programmatic callers.
+ */
+export declare function prepareImageProjection(host: ToolHost, exec: ToolExecution, content: JsonValue[], toolName: string): Promise<ContentBlock[]>;
+/**
+ * Extract text from an MCP content array into a single string.
+ * - text blocks: join with '\n'
+ * - image/audio/resource blocks: replaced with a placeholder
+ *
+ * Defensive: fields that the MCP spec declares required (mimeType, text) are
+ * guarded with fallbacks because this is a network trust boundary.
+ */
+export declare function extractText(mcpContent: JsonValue[], toolName: string): string;

package/lib/types/runtime/mcp-client/tools.d.ts

@@ -9,81 +9,15 @@
  * to the DeepSeek function-name constraints. The raw name is only ever sent on
  * the wire (`tools/call`); the public name is never parsed to recover it.
  *
- * The host contract below (`ToolDefinition`, `ToolExecution`,
- * `ToolExecutionResult`) is a structural mirror of `@deepseek-ai/dsh-tools`
- * rc.2's registration surface — the runtime accepts the same object shape the
- * upstream bridge registers, so the model-facing behavior is identical.
+ * The registration surface this module targets is mirrored by
+ * `./host-contract.js`; MCP results are mapped into host content blocks by
+ * `./projection.js`.
  *
  * @module runtime/mcp-client/tools
  */
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { ContentBlock } from '@deepseek-ai/dsh-llm';
-import type { JsonSchemaNode } from './json-schema-subset.js';
-/** Lossless JSON value vocabulary the bridge exchanges with the registry. */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
-export type McpResult<Structured extends JsonValue = JsonValue> = {
-    content: JsonValue[];
-    structuredContent?: Structured;
-};
-/** The agent on whose behalf a tool call runs (structural mirror). */
-interface ToolExecutionAgent {
-    session?: {
-        requestHeader?: () => {
-            config?: {
-                provider?: string;
-                model?: string;
-            };
-        } | undefined;
-    };
-    options?: {
-        provider?: string;
-        model?: string;
-    };
-} /** Execution identity handed to a tool body (structural mirror). */
-export interface ToolExecution {
-    /** Caller-owned cancellation for this invocation. */
-    readonly signal: AbortSignal;
-    /** The calling agent, when the call came from one. */
-    readonly agent?: ToolExecutionAgent;
-}
-/** A settled tool outcome (structural mirror). */
-export interface ToolExecutionResult {
-    readonly value: JsonValue;
-    readonly content: ContentBlock[];
-    readonly isError: boolean;
-}
-/** One registered tool (structural mirror of the host registration shape). */
-export interface ToolDefinition {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: Record<string, unknown>;
-    readonly output: {
-        readonly schema: JsonSchemaNode;
-        render(args: unknown, value: JsonValue): ContentBlock[];
-    };
-    execute(args: unknown, exec: ToolExecution): Promise<unknown>;
-    finalizeContent?(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): ContentBlock[] | undefined;
-}
-/**
- * The host surface the bridge needs: a tool registry, a logger, and the two
- * optional services image projection consults. Structural — the cordis
- * context is adapted onto this shape by the bridge shell.
- */
-export interface ToolHost {
-    readonly logger: {
-        error(message: string): void;
-        warn(message: string): void;
-        info(message: string): void;
-    };
-    readonly tools: {
-        register(definition: ToolDefinition): () => void;
-    };
-    /** Optional service lookup; image projection degrades when absent. */
-    getService?(name: 'attachments' | 'llm'): unknown;
-}
+import type { ToolHost } from './host-contract.js';
+export type { JsonValue, McpResult, ToolDefinition, ToolExecution, ToolExecutionResult, ToolHost } from './host-contract.js';
 /** Resolved options relevant to tool bridging. */
 export interface ToolBridgeOptions {
     enabledTools?: string[];
@@ -136,4 +70,3 @@ export declare function publicToolName(serverName: string, rawName: string): str
  *   disposers — the exact set of live registrations owned by this server.
  */
 export declare function syncTools(client: Client, host: ToolHost, opts: ToolBridgeOptions, previous: ToolDisposers): Promise<ToolDisposers>;
-export {};

package/lib/types/runtime/mcp-config.d.ts

@@ -1,11 +1,22 @@
 import type { Config } from './mcp-client/config.js';
-import { type McpSuiteOverrides } from './mcp-overrides.js';
-import type { McpServer, Suite } from '../model/types.js';
+import { type McpServerOverride, type McpSuiteOverrides } from './mcp-overrides.js';
+import type { McpServer, McpServerSse, McpServerStdio, McpServerStreamableHttp, Suite } from '../model/types.js';
 export interface McpMountRequest {
     suiteId: string;
     serverKey: string;
     config: Config;
 }
+/** One `mcp.json` server as it will actually be used, with the user's override applied. */
+export interface EffectiveMcpServer {
+    serverKey: string;
+    server: McpServerStdio | McpServerStreamableHttp | McpServerSse;
+    /** The override that produced this view; consumers render its state from it. */
+    override: McpServerOverride | undefined;
+    /** Whether the server is used at all — an override can disable a declaration without removing it. */
+    enabled: boolean;
+    /** External credential references the effective definition needs. */
+    credentialRefs: string[];
+}
 export type McpMountFailureCode = 'unsupported-transport' | 'missing-credential' | 'credential-error' | 'unmount-failed' | 'mount-failed'
 /** The derived serverName's namespace is already mounted by another MCP client — informational, not a failure. */
  | 'foreign-mount'
@@ -24,6 +35,14 @@ export interface McpCredentialResolver {
         source?: string;
     } | undefined>;
 }
+/**
+ * The effective view of one suite's `mcp.json` servers: the user's per-server
+ * overrides applied, every row flagged with whether it is used at all, and each
+ * row's credential references read off the effective shape. Mounting, status
+ * and detail rendering read this one projection, so a server cannot be listed
+ * as enabled while mounting something else.
+ */
+export declare function effectiveMcpServers(suite: Suite, overrides?: McpSuiteOverrides): EffectiveMcpServer[];
 /**
  * Build one mount request per supported mcp.json server, resolving every
  * `${NAME}` through the credential resolver before a child process or HTTP
@@ -33,12 +52,14 @@ export interface McpCredentialResolver {
  * @param overrides user-owned per-server overrides (url/headers/env/args
  *   replacement plus enable/disable); applied before mount. Disabled servers
  *   are omitted entirely.
- * @returns mount requests plus per-server failures. serverName collisions are
- *   reported by the mount registry, not here.
+ * @returns mount requests, per-server failures, and the credential references
+ *   the effective servers need. serverName collisions are reported by the
+ *   mount registry, not here.
  */
 export declare function toMcpMounts(suite: Suite, pluginDataRoot: string, overrides?: McpSuiteOverrides, resolver?: McpCredentialResolver): Promise<{
     mounts: McpMountRequest[];
     failures: McpMountFailure[];
+    credentialRefs: string[];
 }>;
 /** Find external credential references used by one MCP server definition. */
 export declare function credentialRefsInServer(server: McpServer): string[];

package/lib/types/runtime/mcp-direct-config.d.ts

@@ -1,7 +1,21 @@
-import type { Suite } from '../model/types.js';
+import { type McpSuiteConfig, type Suite } from '../model/types.js';
 export declare const USER_MCP_SOURCE = "@user-mcp";
 export declare const USER_MCP_SUITE = "user-mcp";
-/** User-created services reuse the owned bridge lifecycle without changing host configuration. */
-export declare function loadUserMcpSuite(dataRoot: string): Promise<Suite>;
+/**
+ * User-created services reuse the owned bridge lifecycle without changing host configuration.
+ *
+ * The declarations live in the shared Agent layout root
+ * (`~/.agents/mcp.json`), so a service the user adds by hand is ordinary
+ * `mcpServers` JSON in the same place other Agent tools look.
+ *
+ * The suite always carries an `mcp` document — an absent or malformed
+ * `mcp.json` leaves an empty one — so callers read `.mcp.servers` directly
+ * instead of re-checking the optional field.
+ */
+export declare function loadUserMcpSuite(agentsRoot: string): Promise<Suite & {
+    mcp: McpSuiteConfig;
+}>;
 /** Add one service atomically; reject collisions and malformed config before writing. */
-export declare function addUserMcpServer(dataRoot: string, name: string, server: unknown): Promise<void>;
+export declare function addUserMcpServer(agentsRoot: string, name: string, server: unknown): Promise<void>;
+/** The user's hand-written MCP declaration file: `<agentsRoot>/mcp.json`. */
+export declare function userMcpPath(agentsRoot: string): string;

package/lib/types/runtime/mcp-mounts.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { McpBackend } from './mcp-backend.js';
-import { type McpSuiteOverrides } from './mcp-overrides.js';
+import type { McpSuiteOverrides } from './mcp-overrides.js';
 import { type McpMountFailureCode } from './mcp-config.js';
 import type { Suite } from '../model/types.js';
 export interface McpMountDiagnostic {
@@ -23,7 +23,6 @@ export interface McpMountDiagnostic {
 export declare class McpMountRegistry {
     private readonly ctx;
     private readonly pluginDataRoot;
-    private readonly namespace?;
     private readonly live;
     private readonly names;
     private readonly credentialRefs;
@@ -33,11 +32,9 @@ export declare class McpMountRegistry {
     /** The active MCP mount backend ('builtin' bridge or host client compat mode). */
     private backendProvider;
     /** Serialize mount and unmount passes so a disable cannot race an in-flight spawn. */
-    private reconcileQueue;
-    /** Pending retry timers keyed by mount key, so a teardown can cancel them. */
+    private readonly passes;
+    /** Delayed re-attempts for mounts that are not live yet. */
     private readonly retries;
-    /** Attempt count per mount key; reset whenever a retry succeeds. */
-    private readonly attempts;
     /**
      * Mount keys flagged for an explicit rebuild (re-authorize): the next
      * reconcile must tear down and remount them even when the resolved config
@@ -46,7 +43,7 @@ export declare class McpMountRegistry {
     private readonly forcedRemounts;
     /** Snapshot of the last reconciled suite set, replayed by retry passes. */
     private lastEnabled;
-    constructor(ctx: Context, pluginDataRoot: string, namespace?: string | undefined);
+    constructor(ctx: Context, pluginDataRoot: string);
     /** Install the per-suite overrides provider (suiteId -> overrides). */
     setOverridesProvider(provider: () => Promise<Map<string, McpSuiteOverrides>>): void;
     /**
@@ -66,6 +63,12 @@ export declare class McpMountRegistry {
      * its in-memory tokens) untouched.
      */
     forceRemount(suiteId: string, serverKey: string): void;
+    /**
+     * Flag every live mount for a rebuild on the next reconcile: the manual
+     * retry path. A bridge whose server died underneath it still matches its own
+     * config fingerprint, so nothing else would ever re-verify that mount.
+     */
+    forceRemountAll(): void;
     /** The mount key owning one derived serverName; undefined when not mounted here. */
     serverOwner(serverName: string): {
         suiteId: string;
@@ -75,14 +78,6 @@ export declare class McpMountRegistry {
     reconcile(enabledSuites: Suite[]): Promise<McpMountDiagnostic[]>;
     /** Mount/unmount MCP servers to match the enabled suites exactly. */
     private reconcileNow;
-    /**
-     * Schedule a delayed re-attempt for a mount that still is not live.
-     *
-     * Mounts are retried because a remote endpoint or a credential may become
-     * available slightly after the suite is enabled. The schedule is bounded, and
-     * a server that keeps failing simply stops retrying until the next reconcile.
-     */
-    private scheduleRetry;
     /** Dispose every live mount after queued reconciliation passes settle. */
     disposeAll(): Promise<void>;
     /** Mount one precomputed request (source config merged with overrides). */

package/lib/types/runtime/mcp-overrides.d.ts

@@ -29,7 +29,7 @@ export declare function overridesDir(dataRoot: string): string;
 export declare function suiteOverridePath(dataRoot: string, suiteId: string): string;
 /** Load one suite's persisted overrides; unreadable files yield none. */
 export declare function loadSuiteOverrides(dataRoot: string, suiteId: string): Promise<McpSuiteOverrides>;
-/** Persist one suite's overrides atomically-ish (single writer, small file). */
+/** Persist one suite's overrides through the harness atomic write. */
 export declare function saveSuiteOverrides(dataRoot: string, suiteId: string, overrides: McpSuiteOverrides): Promise<void>;
 /** Keep only recognized fields with correct shapes; drop everything else. */
 export declare function sanitizeOverrides(raw: unknown): McpSuiteOverrides;

package/lib/types/runtime/mcp-status.d.ts

@@ -1,4 +1,4 @@
-import { type McpSuiteOverrides } from './mcp-overrides.js';
+import type { McpSuiteOverrides } from './mcp-overrides.js';
 import type { McpStatusPayload } from '../contracts/mcp-status.js';
 import { inspectToolRegistry, type McpToolSnapshot } from './tool-registry-observer.js';
 import type { Suite } from '../model/types.js';

package/lib/types/runtime/mount-lifecycle.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared mount lifecycle: the pass queue and the bounded retry schedule that
+ * every surface registry runs on top of its own mount/unmount semantics. Which
+ * failures are worth retrying stays the surface's own decision; only the timing
+ * and the bookkeeping live here.
+ */
+/** Structural `ctx.plugin` handle for one dynamically mounted plugin. */
+export interface MountPluginHandle {
+    await(): Promise<unknown>;
+    dispose(): void | Promise<void>;
+}
+/** Structural `ctx.plugin` surface for mounting one plugin instance. */
+export interface PluginMountContext {
+    plugin(plugin: unknown, config: unknown): MountPluginHandle;
+}
+/** One failed mount offered to the retry schedule. */
+export interface RetryTarget {
+    /** Mount key; also the retry identity, so a key holds at most one pending timer. */
+    key: string;
+    /** How the mount is named in log lines, e.g. `suite/server`. */
+    label: string;
+    /** Why the mount failed; omitted when the failure must not be retried. */
+    reason?: string;
+}
+/** Serializes reconcile passes: each pass starts after the previous one settles. */
+export declare class SerialPassQueue {
+    private tail;
+    /** Queue one pass behind the in-flight one, so a disable cannot race an in-flight spawn. */
+    run<T>(pass: () => Promise<T>): Promise<T>;
+}
+export interface RetrySchedulerOptions {
+    /** Re-run the surface's reconcile against its last known input. */
+    replay(): Promise<unknown>;
+    /** Write one lifecycle log line through the surface's own logger. */
+    log(message: string): void;
+}
+/** Delayed re-attempts for a mount that is not live yet, keyed by mount key. */
+export declare class RetryScheduler {
+    private readonly options;
+    /** Pending retry timers keyed by mount key, so a teardown can cancel them. */
+    private readonly timers;
+    /** Attempt count per mount key, dropped when its target stops being retryable. */
+    private readonly attempts;
+    constructor(options: RetrySchedulerOptions);
+    /**
+     * Arm the retry for one failed mount, replacing any timer already pending for
+     * its key. A target carrying no reason is a deterministic skip rather than a
+     * transient failure: it drops that key's budget and cancels its timer.
+     */
+    schedule(target: RetryTarget): void;
+    /** Cancel every pending retry and drop all attempt budgets. */
+    clear(): void;
+}

package/lib/types/runtime/profile-seam.d.ts

@@ -0,0 +1,64 @@
+/** Every package the plugin provisions for LSP, in declaration order. */
+export declare const LSP_PACKAGE_SPECIFIERS: readonly ["@deepseek-ai/dsh-lsp", "@deepseek-ai/dsh-lsp-stdio", "@deepseek-ai/dsh-tool-lsp"];
+/** Whether the launcher watches the profile patch file after boot. */
+export type PatchReload = 'live' | 'startup';
+/** One `insert` row that claims a seam the plugin owns. */
+export interface LegacySeamRow {
+    /** The row's `id`, or an empty string when the user wrote none. */
+    id: string;
+    /** The package name the row inserts. */
+    name: string;
+}
+/** A profile carrying a legacy LSP layer that must be removed. */
+export interface LegacyLspSeam {
+    /** Profile name, i.e. its directory basename. */
+    profile: string;
+    /** Absolute profile directory. */
+    dir: string;
+    /** Absolute path of the profile's patch file. */
+    patchPath: string;
+    /** The conflicting `insert` rows, in file order. */
+    rows: LegacySeamRow[];
+    /** `dsh.profile.bundles` entries naming one of {@link LSP_PACKAGE_SPECIFIERS}. */
+    bundles: string[];
+    /** Declared dependency names drawn from {@link LSP_PACKAGE_SPECIFIERS}. */
+    dependencies: string[];
+    /** Whether the host hot-reloads the patch file, i.e. whether a restart is needed. */
+    patchReload: PatchReload;
+}
+/** Outcome of removing one profile's legacy LSP layer. */
+export interface SeamMigrationResult {
+    profile: string;
+    patchPath: string;
+    /** Where the pre-edit content was kept. */
+    backupPath: string;
+    /** The rows that were removed. */
+    removed: LegacySeamRow[];
+    /** True when the host must restart before the removal takes effect. */
+    restartRequired: boolean;
+}
+/**
+ * Find every profile that still registers a legacy LSP seam.
+ *
+ * Best effort by design: profile files are the user's, so a directory that
+ * cannot be read or a patch file that does not parse is skipped rather than
+ * failing the status surface that calls this.
+ * @param home - the Harness home; defaults to `$DSH_HOME` or `~/.dsh`.
+ * @returns each matching profile, ordered by profile name.
+ */
+export declare function findLegacyLspSeams(home?: string): Promise<LegacyLspSeam[]>;
+/**
+ * Remove one profile's legacy LSP rows.
+ *
+ * The file is re-read here rather than trusting the caller's snapshot, so a
+ * migration always edits the current on-disk content. The rewrite is verified
+ * before it lands and the pre-edit content is written beside it first, so a
+ * failure leaves the profile exactly as it was.
+ * @param seam - a profile previously returned by {@link findLegacyLspSeams}.
+ * @param now - timestamp used in the backup filename; injectable for tests.
+ * @returns what was removed and where the backup went.
+ * @throws Error when the profile no longer carries a removable row, or the rewrite does not verify.
+ */
+export declare function migrateLegacyLspSeam(seam: LegacyLspSeam, now?: Date): Promise<SeamMigrationResult>;
+/** One-line remediation shared by the mount diagnostic and the status payload. */
+export declare function describeLegacySeam(seam: LegacyLspSeam): string;

package/lib/types/runtime/reconcile-scheduler.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Coalesced runtime reconciliation for the enabled suite set.
+ *
+ * Settings, credential and catalog events arrive in bursts and can land while
+ * a slow MCP connection is still opening. One pass is kept in flight and at
+ * most one fresh follow-up is remembered, so a burst collapses into a single
+ * reconcile instead of a queue of stale snapshots that each reconnect the
+ * same servers.
+ *
+ * @module runtime/reconcile-scheduler
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Suite } from '../model/types.js';
+import type { McpMountDiagnostic } from './mcp-mounts.js';
+import type { RuntimeReconciler } from './reconciler.js';
+/** The catalog surface one reconcile pass reads from and publishes to. */
+export interface ReconcileHost {
+    /** Enabled user-dimension suites to reconcile. */
+    enabledSuites(): Promise<Suite[]>;
+    /** Publish the pass's MCP mount diagnostics for the status surface. */
+    publishMcpDiagnostics(diagnostics: McpMountDiagnostic[]): void;
+}
+export declare class ReconcileScheduler {
+    private readonly ctx;
+    private readonly runtime;
+    private readonly host;
+    private disposed;
+    private requested;
+    private pass;
+    private readonly pendingCredentialRefs;
+    private credentialFlush;
+    private readonly releaseCredentialUpdates;
+    constructor(ctx: Context, runtime: RuntimeReconciler, host: ReconcileHost);
+    /** Reconcile now, joining the pass in flight and remembering one follow-up for it. */
+    request(): Promise<void>;
+    /** Stop scheduling; later events are dropped. */
+    dispose(): void;
+    private reconcileOnce;
+    /**
+     * Coalesce credential updates: the debounce collapses a burst into one pass,
+     * and the pending refs are kept until that pass runs, so an update arriving
+     * mid-reconcile is never dropped.
+     */
+    private flushCredentialUpdates;
+}

package/lib/types/runtime/reconciler.d.ts

@@ -44,6 +44,8 @@ export declare class RuntimeReconciler {
     usesCredential(ref: string): boolean;
     /** Flag one MCP mount for an explicit rebuild on the next reconcile. */
     forceMcpRemount(suiteId: string, serverKey: string): void;
+    /** Flag every live MCP mount for a rebuild on the next reconcile. */
+    forceMcpRemountAll(): void;
     /** The mount key owning one derived serverName; undefined when not mounted here. */
     mcpServerOwner(serverName: string): {
         suiteId: string;