@cleocode/caamp 2026.4.5 → 2026.4.7

package/dist/index.d.ts

@@ -1733,6 +1733,49 @@ declare function removeSkill(skillName: string, providers: Provider[], isGlobal:
  */
 declare function listCanonicalSkills(): Promise<string[]>;
 
+/**
+ * Three-tier scope helper for Pi harness operations.
+ *
+ * @remarks
+ * Per ADR-035 §D1, CAAMP wraps Pi's native two-tier extension model
+ * (project-local `.pi/extensions/` → global `~/.pi/agent/extensions/`)
+ * with a third tier for the CleoOS-managed cross-project hub. The
+ * resulting hierarchy, in precedence order on reads:
+ *
+ * | Tier      | Path                                           | Who owns it              |
+ * | --------- | ---------------------------------------------- | ------------------------ |
+ * | `project` | `<cwd>/.pi/<asset>/`                           | repository               |
+ * | `user`    | `$PI_CODING_AGENT_DIR` or `~/.pi/agent/<asset>`| Pi itself                |
+ * | `global`  | `$CLEO_HOME/pi-<asset>/`                       | CleoOS (this wrapper)    |
+ *
+ * Pi's own discovery loader is NOT modified. The `global` tier is either
+ * copied or symlinked into the `user` tier on first use (lazy
+ * materialization), so Pi's native two-tier loader picks extensions up
+ * from the familiar location without needing a patch.
+ *
+ * This helper intentionally lives next to {@link ../harness/pi.ts} rather
+ * than being exported at a higher level — three-tier scope is a Pi
+ * concept today, and other harnesses (if any ever land) will want their
+ * own mapping.
+ *
+ * @see ADR-035 §D1 (Three-tier scope hierarchy with explicit precedence)
+ *
+ * @packageDocumentation
+ */
+/**
+ * Three-tier scope identifier for Pi harness operations.
+ *
+ * @remarks
+ * Each tier maps to a distinct root directory; see the module overview
+ * for the precedence and resolution rules. This is distinct from (and
+ * coexists with) the legacy {@link HarnessScope} discriminated union,
+ * which only supports two tiers (`global`/`project`) and is preserved
+ * for back-compat with existing skill/instruction installers.
+ *
+ * @public
+ */
+type HarnessTier = 'project' | 'user' | 'global';
+
 /**
  * Harness layer type definitions.
  *
@@ -1759,6 +1802,12 @@ declare function listCanonicalSkills(): Promise<string[]>;
  * the caller to provide the absolute project directory path — the harness
  * does not infer cwd.
  *
+ * This two-tier scope is the legacy shape used by the skill and
+ * instructions install paths. Pi-specific Wave-1 verbs (extensions,
+ * sessions, models, prompts, themes) use the three-tier
+ * {@link HarnessTier} hierarchy introduced in ADR-035 §D1 alongside this
+ * type — the two coexist and neither replaces the other.
+ *
  * @public
  */
 type HarnessScope = {
@@ -1768,48 +1817,237 @@ type HarnessScope = {
     projectDir: string;
 };
 /**
- * Declarative description of an MCP server that should be bridged into a
- * harness's native extension mechanism.
+ * Metadata describing a Pi extension discovered on disk.
  *
  * @remarks
- * This is a harness-agnostic input shape. Fields mirror the MCP
- * configuration surface: stdio transports use {@link command} + {@link args},
- * remote transports use {@link url} + optional {@link headers}, and all
- * transports may carry environment variables via {@link env}.
+ * Returned by {@link Harness.listExtensions}. The `tier` records which
+ * tier the extension lives at so that callers can surface the
+ * precedence story in their output.
  *
- * Harnesses that cannot host MCP servers as extensions will throw or omit
- * the {@link Harness.installMcpAsExtension} method entirely.
+ * @public
+ */
+interface ExtensionEntry {
+    /** Extension name (file basename without the `.ts` extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the extension file. */
+    path: string;
+    /**
+     * When `true`, this entry is shadowed by a higher-precedence entry
+     * with the same name. Exposed so list output can warn about
+     * cross-tier name collisions per ADR-035 §D1.
+     * @defaultValue false
+     */
+    shadowed?: boolean;
+}
+/**
+ * Metadata describing a Pi prompt directory discovered on disk.
+ *
+ * @remarks
+ * Returned by {@link Harness.listPrompts}. Prompts are directories
+ * containing a `prompt.md` plus optional metadata. The list operation
+ * reads only the directory listing — never the prompt bodies — to keep
+ * token usage minimal per ADR-035 §D1.
+ *
+ * @public
+ */
+interface PromptEntry {
+    /** Prompt name (directory basename). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the prompt directory. */
+    path: string;
+    /** See {@link ExtensionEntry.shadowed}. @defaultValue false */
+    shadowed?: boolean;
+}
+/**
+ * Metadata describing a Pi theme discovered on disk.
+ *
+ * @remarks
+ * Returned by {@link Harness.listThemes}. Themes are single `.ts` or
+ * `.json` files matching Pi's native theme module shape.
  *
  * @public
  */
-interface McpServerSpec {
-    /** Logical name of the MCP server (e.g. `"filesystem"`, `"brave-search"`). */
+interface ThemeEntry {
+    /** Theme name (file basename without the extension). */
+    name: string;
+    /** Tier at which this entry lives. */
+    tier: HarnessTier;
+    /** Absolute on-disk path to the theme file. */
+    path: string;
+    /** File extension of the theme file (e.g. `".ts"`, `".json"`). */
+    fileExt: string;
+    /** See {@link ExtensionEntry.shadowed}. @defaultValue false */
+    shadowed?: boolean;
+}
+/**
+ * Options accepted by the Pi install verbs (extensions, prompts, themes).
+ *
+ * @public
+ */
+interface HarnessInstallOptions {
+    /**
+     * When `true`, overwrite an existing file at the target tier. When
+     * `false` (the default) the install verb throws if the target exists.
+     * @defaultValue false
+     */
+    force?: boolean;
+}
+/**
+ * Summary header extracted from the first line of a Pi session JSONL file.
+ *
+ * @remarks
+ * Per ADR-035 §D2, `list`-style session operations read only line 1 of
+ * each `*.jsonl` file — never the full body — so this shape is what
+ * callers consume when enumerating sessions. The full session loader
+ * returns raw JSONL line strings as a separate type
+ * ({@link SessionDocument}).
+ *
+ * @public
+ */
+interface SessionSummary {
+    /** Session identifier as recorded in the line-1 header. */
+    id: string;
+    /** Session version as recorded in the line-1 header (e.g. `3`). */
+    version: number;
+    /** ISO-8601 timestamp from the line-1 header, or `null` when absent. */
+    timestamp: string | null;
+    /** Working directory recorded when the session was created. */
+    cwd: string | null;
+    /** Parent session id, if this session was forked from another. */
+    parentSession: string | null;
+    /** Absolute path to the session JSONL file on disk. */
+    filePath: string;
+    /** File modification time in milliseconds since the epoch. */
+    mtimeMs: number;
+}
+/**
+ * Raw content of a Pi session JSONL file, preserved line-by-line.
+ *
+ * @remarks
+ * Returned by {@link Harness.showSession} when a caller needs the full
+ * body. Each element is one JSONL line as a string (empty trailing
+ * lines are stripped). Callers that need typed entries parse each line
+ * themselves; the harness does not impose a type on entry bodies
+ * because Pi's own entry schema is open-ended (`message`, `thinking`,
+ * `custom`, etc.) and we do not want to fall behind Pi's schema
+ * evolution.
+ *
+ * @public
+ */
+interface SessionDocument {
+    /** Header summary (same shape as {@link SessionSummary}). */
+    summary: SessionSummary;
+    /** Raw JSONL lines in file order, excluding the line-1 header. */
+    entries: string[];
+}
+/**
+ * Pi model definition as recorded under `models.json:providers[].models`.
+ *
+ * @remarks
+ * Mirrors the `ModelDefinition` schema in
+ * `@mariozechner/pi-coding-agent`'s model-registry. Fields are typed
+ * loosely because Pi's schema is evolving (see ADR-035 §D3); the keys
+ * captured here are the minimum a CAAMP verb needs to reason about.
+ *
+ * @public
+ */
+interface PiModelDefinition {
+    /** Model id within the provider (e.g. `"claude-opus-4-20250514"`). */
+    id: string;
+    /** Human-readable model name. */
     name: string;
     /**
-     * Command to launch the server over stdio transport.
+     * Whether the model supports reasoning/thinking tokens.
      * @defaultValue undefined
      */
-    command?: string;
+    reasoning?: boolean;
     /**
-     * Arguments for the stdio command.
+     * Allowed input modalities (e.g. `["text"]`, `["text", "image"]`).
      * @defaultValue undefined
      */
-    args?: string[];
+    input?: Array<'text' | 'image'>;
     /**
-     * URL for SSE/HTTP transports.
+     * Context window size in tokens.
      * @defaultValue undefined
      */
-    url?: string;
+    contextWindow?: number;
     /**
-     * Environment variables for the server process.
+     * Maximum output tokens.
      * @defaultValue undefined
      */
-    env?: Record<string, string>;
+    maxTokens?: number;
+}
+/**
+ * Pi provider block as recorded under `models.json:providers[id]`.
+ *
+ * @remarks
+ * Mirrors the `ProviderConfig` schema in Pi's model-registry.
+ *
+ * @public
+ */
+interface PiModelProvider {
     /**
-     * HTTP headers for remote transports.
+     * Custom base URL for the provider (overrides default).
      * @defaultValue undefined
      */
-    headers?: Record<string, string>;
+    baseUrl?: string;
+    /**
+     * API key or `$ENV_VAR` reference.
+     * @defaultValue undefined
+     */
+    apiKey?: string;
+    /**
+     * Custom model definitions declared by the user.
+     * @defaultValue undefined
+     */
+    models?: PiModelDefinition[];
+}
+/**
+ * Entire `models.json` document shape used by Pi.
+ *
+ * @remarks
+ * Mirrors the `ModelsConfig` schema in Pi's model-registry. CAAMP reads
+ * and writes this file through {@link Harness.readModelsConfig} /
+ * {@link Harness.writeModelsConfig}.
+ *
+ * @public
+ */
+interface PiModelsConfig {
+    /** Map of provider id → provider block. */
+    providers: Record<string, PiModelProvider>;
+}
+/**
+ * A model entry as surfaced by {@link Harness.listModels}.
+ *
+ * @remarks
+ * Models are reported as a union of `models.json`-defined custom models
+ * and `settings.json:enabledModels` selections, with flags that record
+ * whether each entry is currently enabled and whether it is the
+ * configured default.
+ *
+ * @public
+ */
+interface ModelListEntry {
+    /** Provider id (e.g. `"anthropic"`). */
+    provider: string;
+    /** Model id within the provider. */
+    id: string;
+    /** Human-readable name, from `models.json` when available. */
+    name: string | null;
+    /** `true` when the model is present in `settings.json:enabledModels`. */
+    enabled: boolean;
+    /** `true` when the model is the configured default. */
+    isDefault: boolean;
+    /**
+     * `true` when this model is defined in `models.json` (custom). When
+     * `false`, the entry originates from `settings.json:enabledModels`
+     * only and is assumed to resolve against Pi's built-in registry.
+     */
+    custom: boolean;
 }
 /**
  * Description of a subagent task to be spawned under a harness.
@@ -1895,9 +2133,9 @@ interface SubagentHandle {
  * harness; the interface is shaped so future harnesses (Goose, OpenCode, ...)
  * can be added without changing any caller code.
  *
- * Optional methods ({@link installMcpAsExtension}, {@link spawnSubagent},
- * {@link configureModels}) may be omitted by harnesses that cannot support
- * them. Callers MUST feature-check before invoking.
+ * Optional methods ({@link spawnSubagent}, {@link configureModels}) may be
+ * omitted by harnesses that cannot support them. Callers MUST feature-check
+ * before invoking.
  *
  * @public
  */
@@ -1965,22 +2203,6 @@ interface Harness {
      * @param scope - Instruction file scope.
      */
     removeInstructions(scope: HarnessScope): Promise<void>;
-    /**
-     * Install an MCP server as a harness extension.
-     *
-     * @remarks
-     * For legacy providers with a native MCP config file, this is a
-     * passthrough. For Pi it generates a TypeScript extension file under
-     * `extensions/` that wraps the MCP server as a Pi tool via
-     * `pi.registerTool()`.
-     *
-     * Optional — harnesses that cannot host MCP bridges should omit this
-     * method. Callers MUST feature-check before invoking.
-     *
-     * @param server - Server spec to bridge.
-     * @param scope - Install scope.
-     */
-    installMcpAsExtension?(server: McpServerSpec, scope: HarnessScope): Promise<void>;
     /**
      * Spawn a subagent under this harness's control.
      *
@@ -2031,6 +2253,145 @@ interface Harness {
      * @param scope - Settings scope.
      */
     writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
+    /**
+     * Install a Pi extension TypeScript file from a local source path into
+     * the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T263, install verbs:
+     * - Validate that the source is a `.ts` file with an `export default`.
+     * - Copy (not symlink) the file into the target tier's extensions dir.
+     * - Error by default when the target already exists; the caller may
+     *   pass `opts.force = true` to enable overwrite.
+     *
+     * Optional on the interface because only first-class harnesses with a
+     * native extension mechanism support this verb.
+     *
+     * @param sourcePath - Absolute path to the source `.ts` file on disk.
+     * @param name - Extension name (used as the target file basename).
+     * @param tier - Target tier (`project`/`user`/`global`).
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @param opts - Install options (see {@link HarnessInstallOptions}).
+     */
+    installExtension?(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /**
+     * Remove a Pi extension by name from the given tier.
+     *
+     * @remarks
+     * Missing files are tolerated silently so the verb is usable as an
+     * idempotent "ensure absent" operation.
+     *
+     * @param name - Extension name (basename without `.ts`).
+     * @param tier - Target tier to remove from.
+     * @param projectDir - Project directory (required when `tier='project'`).
+     * @returns `true` when a file was removed, `false` when none existed.
+     */
+    removeExtension?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * List Pi extensions across all tiers, precedence-ordered.
+     *
+     * @remarks
+     * Entries are returned in precedence order (project → user → global).
+     * Higher-precedence tiers shadow lower-precedence entries with the
+     * same name; the returned {@link ExtensionEntry.shadowed} flag
+     * indicates shadowed copies so the caller can surface cross-tier name
+     * collisions per ADR-035 §D1.
+     *
+     * @param projectDir - Project directory for the `project` tier. When
+     *   omitted the `project` tier is skipped rather than failing.
+     */
+    listExtensions?(projectDir?: string): Promise<ExtensionEntry[]>;
+    /**
+     * List Pi sessions from the user-tier sessions directory.
+     *
+     * @remarks
+     * Per ADR-035 §D2, MUST read only line 1 of each `*.jsonl` file. The
+     * result is sorted by `mtimeMs` descending so the most recent
+     * sessions appear first.
+     *
+     * @param opts - Options controlling which directories to scan.
+     */
+    listSessions?(opts?: {
+        includeSubagents?: boolean;
+    }): Promise<SessionSummary[]>;
+    /**
+     * Load a Pi session's full body by id.
+     *
+     * @remarks
+     * Reads the entire file as-is. The caller is responsible for
+     * formatting / filtering; the harness only guarantees that the
+     * returned `entries` are the raw JSONL lines in file order.
+     *
+     * @param id - Session id as recorded in the line-1 header.
+     */
+    showSession?(id: string): Promise<SessionDocument>;
+    /**
+     * List every model known to Pi — both custom (`models.json`) and
+     * enabled selections (`settings.json:enabledModels`).
+     *
+     * @remarks
+     * Per ADR-035 §D3, this is a read-only union with per-entry flags.
+     * Mutation verbs (`add`, `remove`, `enable`, `disable`, `default`)
+     * are separate methods to preserve the dual-file authority model.
+     *
+     * @param scope - Legacy two-tier scope (global/project) that
+     *   determines which `models.json` and `settings.json` files to read.
+     */
+    listModels?(scope: HarnessScope): Promise<ModelListEntry[]>;
+    /**
+     * Read `models.json` for the given scope.
+     *
+     * @remarks
+     * Missing files resolve to `{ providers: {} }`. Malformed JSON also
+     * resolves to the empty config rather than throwing, matching
+     * {@link Harness.readSettings}'s tolerant contract.
+     */
+    readModelsConfig?(scope: HarnessScope): Promise<PiModelsConfig>;
+    /**
+     * Write `models.json` for the given scope atomically.
+     *
+     * @remarks
+     * The full config is written, not merged. Callers should read, patch,
+     * then write. Uses an atomic tmp-then-rename sequence so a crash
+     * mid-write cannot corrupt the file.
+     */
+    writeModelsConfig?(config: PiModelsConfig, scope: HarnessScope): Promise<void>;
+    /**
+     * Install a Pi prompt from a source directory into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T266, the source is a
+     * directory containing `prompt.md` plus optional metadata. The
+     * directory is copied recursively into the target tier. Conflict
+     * handling mirrors {@link installExtension}.
+     */
+    installPrompt?(sourceDir: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** List Pi prompts across all tiers. */
+    listPrompts?(projectDir?: string): Promise<PromptEntry[]>;
+    /** Remove a Pi prompt by name from the given tier. */
+    removePrompt?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /**
+     * Install a Pi theme from a source file into the given tier.
+     *
+     * @remarks
+     * Per ADR-035 §D1 and the spec hook for T267. The source may be a
+     * `.ts` TypeScript theme module or a `.json` theme file; the file
+     * extension is preserved so Pi picks the right loader.
+     */
+    installTheme?(sourceFile: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** List Pi themes across all tiers. */
+    listThemes?(projectDir?: string): Promise<ThemeEntry[]>;
+    /** Remove a Pi theme by name from the given tier. */
+    removeTheme?(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
 }
 
 /**
@@ -2085,10 +2446,6 @@ declare class PiHarness implements Harness {
      * Resolve the skills directory for a given scope.
      */
     private skillsDir;
-    /**
-     * Resolve the extensions directory for a given scope.
-     */
-    private extensionsDir;
     /**
      * Resolve the settings.json path for a given scope.
      */
@@ -2112,19 +2469,6 @@ declare class PiHarness implements Harness {
     injectInstructions(content: string, scope: HarnessScope): Promise<void>;
     /** {@inheritDoc Harness.removeInstructions} */
     removeInstructions(scope: HarnessScope): Promise<void>;
-    /**
-     * {@inheritDoc Harness.installMcpAsExtension}
-     *
-     * @remarks
-     * Emits a SCAFFOLD Pi extension file under `extensions/mcp-<name>.ts`.
-     * The scaffold registers a Pi tool whose `execute` function currently
-     * returns an "isError" payload explaining that the MCP bridge runtime
-     * is not yet implemented. This preserves the public lifecycle surface
-     * (install/list/remove) so orchestration code can treat the bridge as
-     * a first-class asset while the concrete JSON-RPC runtime is built out
-     * in a later wave.
-     */
-    installMcpAsExtension(server: McpServerSpec, scope: HarnessScope): Promise<void>;
     /**
      * {@inheritDoc Harness.spawnSubagent}
      *
@@ -2145,6 +2489,60 @@ declare class PiHarness implements Harness {
     writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
     /** {@inheritDoc Harness.configureModels} */
     configureModels(modelPatterns: string[], scope: HarnessScope): Promise<void>;
+    /**
+     * Resolve the `models.json` path for a given legacy two-tier scope.
+     *
+     * @remarks
+     * Lives next to `settings.json`. Global scope uses the Pi state root,
+     * project scope uses the project's `.pi/` directory, matching the
+     * dual-file authority model documented in ADR-035 §D3.
+     */
+    private modelsConfigPath;
+    /**
+     * Resolve the sessions directory — always user-tier because Pi owns
+     * session storage and the three-tier model folds session listings to
+     * the single authoritative location per ADR-035 §D2.
+     */
+    private sessionsDir;
+    /** {@inheritDoc Harness.installExtension} */
+    installExtension(sourcePath: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.removeExtension} */
+    removeExtension(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /** {@inheritDoc Harness.listExtensions} */
+    listExtensions(projectDir?: string): Promise<ExtensionEntry[]>;
+    /** {@inheritDoc Harness.listSessions} */
+    listSessions(opts?: {
+        includeSubagents?: boolean;
+    }): Promise<SessionSummary[]>;
+    /** {@inheritDoc Harness.showSession} */
+    showSession(id: string): Promise<SessionDocument>;
+    /** {@inheritDoc Harness.readModelsConfig} */
+    readModelsConfig(scope: HarnessScope): Promise<PiModelsConfig>;
+    /** {@inheritDoc Harness.writeModelsConfig} */
+    writeModelsConfig(config: PiModelsConfig, scope: HarnessScope): Promise<void>;
+    /** {@inheritDoc Harness.listModels} */
+    listModels(scope: HarnessScope): Promise<ModelListEntry[]>;
+    /** {@inheritDoc Harness.installPrompt} */
+    installPrompt(sourceDir: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.listPrompts} */
+    listPrompts(projectDir?: string): Promise<PromptEntry[]>;
+    /** {@inheritDoc Harness.removePrompt} */
+    removePrompt(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
+    /** {@inheritDoc Harness.installTheme} */
+    installTheme(sourceFile: string, name: string, tier: HarnessTier, projectDir?: string, opts?: HarnessInstallOptions): Promise<{
+        targetPath: string;
+        tier: HarnessTier;
+    }>;
+    /** {@inheritDoc Harness.listThemes} */
+    listThemes(projectDir?: string): Promise<ThemeEntry[]>;
+    /** {@inheritDoc Harness.removeTheme} */
+    removeTheme(name: string, tier: HarnessTier, projectDir?: string): Promise<boolean>;
 }
 
 /**
@@ -3572,6 +3970,362 @@ declare class MarketplaceClient {
     getSkill(scopedName: string): Promise<MarketplaceResult | null>;
 }
 
+/**
+ * MCP server config reader.
+ *
+ * @remarks
+ * Reads MCP server entries from a provider's per-agent config file using
+ * the format-agnostic {@link readConfig} substrate from `core/formats`.
+ * The provider's `capabilities.mcp` block is the single source of truth
+ * for the file path, format, and dot-notation key — this module never
+ * hard-codes provider-specific layout.
+ *
+ * Three operations are exported:
+ *
+ * - {@link listMcpServers} — enumerate every server entry on a single
+ *   provider's config file at a given scope.
+ * - {@link listAllMcpServers} — fan out across every MCP-capable
+ *   provider in the registry, returning a map keyed by provider id.
+ * - {@link detectMcpInstallations} — lighter-weight scan that just
+ *   reports which providers currently have any MCP config files on
+ *   disk (used by `caamp mcp detect`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scope identifier for MCP config file resolution.
+ *
+ * @remarks
+ * Mirrors the two-tier scope model the underlying provider config files
+ * already use: `project` reads `<projectDir>/<provider.configPathProject>`
+ * and `global` reads the absolute `provider.configPathGlobal` path. The
+ * three-tier {@link HarnessTier} model used by the Pi extensions
+ * verbs is intentionally not adopted here — MCP config files are owned
+ * by individual tools and live on those tools' two-tier hierarchy, not
+ * on a CleoOS-managed hub.
+ *
+ * @public
+ */
+type McpScope = 'project' | 'global';
+/**
+ * Result of a single provider's MCP installation probe.
+ *
+ * @remarks
+ * Returned by {@link detectMcpInstallations} for each provider that
+ * declares an MCP capability in the registry. The `configPath` field
+ * is the resolved file path the probe inspected; `exists` indicates
+ * whether the file is present on disk; `serverCount` is `null` when
+ * the file is missing or unparseable, otherwise the number of server
+ * entries found at the dot-notation key.
+ *
+ * @public
+ */
+interface McpDetectionEntry {
+    /** Provider id (e.g. `"claude-code"`). */
+    providerId: string;
+    /** Human-readable provider name. */
+    providerName: string;
+    /** Resolved scope of the probed config file. */
+    scope: McpScope;
+    /** Absolute path to the provider's MCP config file. */
+    configPath: string;
+    /** Whether the config file exists on disk. */
+    exists: boolean;
+    /** Number of server entries found, or `null` when the file is missing/unparseable. */
+    serverCount: number | null;
+    /** ISO 8601 timestamp of the file's last modification, or `null` when the file is missing. */
+    lastModified: string | null;
+}
+/**
+ * Resolve a provider's MCP config file path for the given scope, or
+ * `null` if the provider does not declare an MCP capability or the
+ * scope is unsupported.
+ *
+ * @remarks
+ * Thin wrapper over {@link resolveProviderConfigPath} that filters out
+ * providers without an MCP capability up front so callers can use a
+ * single null check rather than two.
+ *
+ * @param provider - Provider to resolve a config path for.
+ * @param scope - Scope to resolve.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns The absolute config file path, or `null` when unavailable.
+ *
+ * @public
+ */
+declare function resolveMcpConfigPath(provider: Provider, scope: McpScope, projectDir?: string): string | null;
+/**
+ * List MCP server entries declared in a single provider's config file.
+ *
+ * @remarks
+ * Reads the provider's MCP config file using the format-agnostic
+ * {@link readConfig} substrate, walks the dot-notation
+ * `provider.capabilities.mcp.configKey` to find the servers section,
+ * and returns one {@link McpServerEntry} per child key.
+ *
+ * Returns an empty array (not an error) when:
+ *
+ * - the provider does not declare an MCP capability,
+ * - the resolved config path is unavailable for the requested scope,
+ * - the config file does not exist on disk,
+ * - the config file is empty or unparseable,
+ * - the config file exists but has no MCP servers section.
+ *
+ * "No file" is a normal state for an uninstalled tool, so callers
+ * should treat the empty array as success and only escalate to an
+ * error envelope when the user explicitly asked about a missing
+ * provider.
+ *
+ * @param provider - Provider whose config file to read.
+ * @param scope - Scope to resolve (project|global).
+ * @param projectDir - Project directory used for the `project` scope
+ *   (defaults to `process.cwd()`).
+ * @returns Array of MCP server entries, or `[]` when nothing was found.
+ *
+ * @public
+ */
+declare function listMcpServers(provider: Provider, scope: McpScope, projectDir?: string): Promise<McpServerEntry[]>;
+/**
+ * Map of provider id → MCP server entries for that provider.
+ *
+ * @remarks
+ * Return shape of {@link listAllMcpServers}. Providers without an MCP
+ * capability are intentionally absent from the map (rather than mapped
+ * to an empty array) so callers can iterate the result and immediately
+ * know which providers were probed.
+ *
+ * @public
+ */
+type McpServerEntriesByProvider = Map<string, McpServerEntry[]>;
+/**
+ * List MCP server entries for every MCP-capable provider in the
+ * registry at the given scope.
+ *
+ * @remarks
+ * Iterates {@link getAllProviders}, filters to those with a
+ * `capabilities.mcp` block, calls {@link listMcpServers} on each, and
+ * collects the results into a map keyed by provider id.
+ *
+ * Each provider is probed independently — a parse failure on one
+ * provider will not affect the others. The result map only contains
+ * entries for providers that were actually probed (i.e. had an MCP
+ * capability), so consumers can iterate `result.entries()` without
+ * skipping non-MCP providers.
+ *
+ * @param scope - Scope to resolve for every provider.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns Map of provider id → server entries.
+ *
+ * @public
+ */
+declare function listAllMcpServers(scope: McpScope, projectDir?: string): Promise<McpServerEntriesByProvider>;
+/**
+ * Probe every MCP-capable provider in the registry to determine which
+ * ones have a config file on disk and how many servers are configured.
+ *
+ * @remarks
+ * Lightweight detection used by `caamp mcp detect`. Unlike
+ * {@link listAllMcpServers} this does not return individual server
+ * entries — it just reports a count plus the file mtime so callers can
+ * answer "which tools on my machine already have MCP configured?"
+ * without paying the cost of materialising every server entry.
+ *
+ * @param scope - Scope to probe.
+ * @param projectDir - Project directory used for the `project` scope.
+ * @returns Array of detection entries, one per MCP-capable provider.
+ *
+ * @public
+ */
+declare function detectMcpInstallations(scope: McpScope, projectDir?: string): Promise<McpDetectionEntry[]>;
+
+/**
+ * MCP server config installer.
+ *
+ * @remarks
+ * Writes a single MCP server entry into a provider's config file using
+ * the format-agnostic {@link writeConfig} substrate from `core/formats`.
+ * The provider's `capabilities.mcp` block is the single source of
+ * truth for the file path, format, and dot-notation key.
+ *
+ * Conflict-on-write semantics:
+ *
+ * - When the target server name does not yet exist in the file, the
+ *   write succeeds and {@link InstallMcpServerResult.conflicted} is
+ *   `false`.
+ * - When the target server name already exists in the file and `force`
+ *   is `false`, the installer DOES NOT write — it returns
+ *   `installed: false, conflicted: true` so the caller can emit a
+ *   typed conflict error envelope.
+ * - When `force` is `true`, an existing entry is overwritten and the
+ *   result reports `installed: true, conflicted: true` so the caller
+ *   can surface the overwrite in its envelope.
+ *
+ * Parent directories of the resolved config path are created lazily on
+ * write — see {@link writeConfig} for the per-format details.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options accepted by {@link installMcpServer}.
+ *
+ * @public
+ */
+interface InstallMcpServerOptions {
+    /** Scope to write to (project|global). */
+    scope: McpScope;
+    /** When `true`, overwrite an existing server entry instead of failing. */
+    force?: boolean;
+    /** Project directory used for the `project` scope. */
+    projectDir?: string;
+}
+/**
+ * Result of an {@link installMcpServer} call.
+ *
+ * @remarks
+ * `installed` is `true` only when the file was actually written.
+ * `conflicted` is `true` whenever the target server name was already
+ * present, regardless of whether the write went through (force was
+ * supplied) or was suppressed (force was withheld).
+ *
+ * @public
+ */
+interface InstallMcpServerResult {
+    /** Whether the entry was written to the config file. */
+    installed: boolean;
+    /** Whether the target server name already existed before the call. */
+    conflicted: boolean;
+    /** Absolute path to the config file that was (or would have been) written. */
+    sourcePath: string;
+    /** Provider id the entry was written for. */
+    providerId: string;
+    /** Server name that was written. */
+    serverName: string;
+}
+/**
+ * Install an MCP server entry into a single provider's config file.
+ *
+ * @remarks
+ * Resolves the provider's MCP config path for the requested scope,
+ * checks for an existing entry with the same server name, and either
+ * writes the new config (when no conflict, or when `force` is set) or
+ * returns a non-installed conflict result.
+ *
+ * Throws a plain `Error` (not a `LAFSCommandError`) when the provider
+ * has no MCP capability or no config path for the requested scope —
+ * those are caller-side validation failures and should be caught and
+ * re-thrown as typed `LAFSCommandError`s in the command layer.
+ *
+ * @param provider - Target provider.
+ * @param serverName - Name/key for the new server entry.
+ * @param config - Canonical {@link McpServerConfig} payload to write.
+ * @param opts - Install options (scope, force, projectDir).
+ * @returns Structured install result describing what happened.
+ * @throws `Error` when the provider has no MCP capability or no
+ *   project-scoped config path is available.
+ *
+ * @public
+ */
+declare function installMcpServer(provider: Provider, serverName: string, config: McpServerConfig, opts: InstallMcpServerOptions): Promise<InstallMcpServerResult>;
+
+/**
+ * MCP server config remover.
+ *
+ * @remarks
+ * Removes a single MCP server entry from a provider's config file
+ * using the format-agnostic {@link removeConfig} substrate from
+ * `core/formats`. The provider's `capabilities.mcp` block is the
+ * single source of truth for the file path, format, and dot-notation
+ * key.
+ *
+ * Both single-provider and all-providers variants are exported. Both
+ * are idempotent: removing a server that does not exist returns
+ * `removed: false` rather than throwing.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options accepted by {@link removeMcpServer} and
+ * {@link removeMcpServerFromAll}.
+ *
+ * @public
+ */
+interface RemoveMcpServerOptions {
+    /** Scope to target (project|global). */
+    scope: McpScope;
+    /** Project directory used for the `project` scope. */
+    projectDir?: string;
+}
+/**
+ * Result of a single-provider {@link removeMcpServer} call.
+ *
+ * @remarks
+ * `removed` is `true` only when an entry was actually deleted from
+ * the file. The `reason` field carries an optional discriminator when
+ * the call was a no-op so the command layer can surface a precise
+ * envelope (e.g. "no config file" vs "entry not present").
+ *
+ * @public
+ */
+interface RemoveMcpServerResult {
+    /** Provider id the call targeted. */
+    providerId: string;
+    /** Server name the call targeted. */
+    serverName: string;
+    /** Resolved config file path, or `null` when the provider had no MCP capability. */
+    sourcePath: string | null;
+    /** Whether an entry was actually deleted. */
+    removed: boolean;
+    /**
+     * Diagnostic discriminator when `removed` is `false`.
+     *
+     * - `"no-mcp-capability"` — provider does not consume MCP servers
+     * - `"no-config-path"` — provider has no config path for the scope
+     * - `"file-missing"` — config file does not exist on disk
+     * - `"entry-missing"` — config file exists but had no matching entry
+     *
+     * Set to `null` when `removed` is `true`.
+     */
+    reason: 'no-mcp-capability' | 'no-config-path' | 'file-missing' | 'entry-missing' | null;
+}
+/**
+ * Remove an MCP server entry from a single provider's config file.
+ *
+ * @remarks
+ * Idempotent: when the entry is not present (or the file is missing
+ * entirely) the call returns `removed: false` with a structured
+ * `reason` rather than throwing.
+ *
+ * @param provider - Provider whose config file to modify.
+ * @param serverName - Server name/key to remove.
+ * @param opts - Removal options.
+ * @returns Structured result describing whether the entry was removed.
+ *
+ * @public
+ */
+declare function removeMcpServer(provider: Provider, serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult>;
+/**
+ * Remove an MCP server entry from every MCP-capable provider in the
+ * registry that currently has it configured.
+ *
+ * @remarks
+ * Iterates {@link getAllProviders}, calls {@link removeMcpServer} on
+ * each MCP-capable provider, and collects the per-provider results.
+ * Each provider is processed independently — a failure on one does
+ * not abort the others. The result array contains one entry per
+ * MCP-capable provider, even when the entry was not present (so
+ * callers can render a complete report).
+ *
+ * @param serverName - Server name/key to remove from every provider.
+ * @param opts - Removal options applied uniformly to every provider.
+ * @returns Array of per-provider removal results.
+ *
+ * @public
+ */
+declare function removeMcpServerFromAll(serverName: string, opts: RemoveMcpServerOptions): Promise<RemoveMcpServerResult[]>;
+
 /**
  * Scope for path resolution, either global (user home) or project-local.
  *
@@ -6345,4 +7099,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpServerConfig, type McpServerEntry, type McpServerSpec, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installSkill, isCaampOwnedSkill, isMarketplaceScoped, isQuiet, isVerbose, listCanonicalSkills, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveDefaultTargetProviders, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };