@cleocode/caamp 2026.4.3 → 2026.4.5

package/dist/index.d.ts

@@ -1,3 +1,55 @@
+/**
+ * Priority tier identifier stored in registry.json.
+ *
+ * @remarks
+ * Providers are tiered to express selection precedence and tooling defaults.
+ * Exactly **one** provider in a registry MAY have the `"primary"` tier — it
+ * is the first-class harness and default target when no `--agent` flag is
+ * given. The registry loader does not enforce this cardinality rule; instead
+ * {@link RegistryProvider.priority} consumers such as `getPrimaryProvider()`
+ * expect either zero or one provider with `"primary"` priority.
+ *
+ * @public
+ */
+type ProviderPriority = 'primary' | 'high' | 'medium' | 'low';
+/**
+ * Lifecycle status identifier stored in registry.json.
+ *
+ * @remarks
+ * The registry uses four discrete lifecycle states. The enum is duplicated
+ * here (and in `src/types.ts`) so the raw and resolved Provider shapes can
+ * share precise typing without circular imports.
+ *
+ * @public
+ */
+type ProviderStatus = 'active' | 'beta' | 'deprecated' | 'planned';
+/**
+ * Supported MCP config file formats.
+ *
+ * @remarks
+ * These mirror the wider {@link ConfigFormat} enum in `src/types.ts` but
+ * are restated here to avoid importing the resolved runtime type into the
+ * raw JSON schema definitions.
+ *
+ * @public
+ */
+type McpConfigFormat = 'json' | 'jsonc' | 'yaml' | 'toml';
+/**
+ * MCP transport protocols a provider may advertise.
+ *
+ * @public
+ */
+type McpTransportType = 'stdio' | 'sse' | 'http' | 'websocket';
+/**
+ * Harness role category for a primary or standalone harness.
+ *
+ * @remarks
+ * - `"orchestrator"` — can spawn subagents and coordinate multi-provider workflows.
+ * - `"standalone"` — runs as a single agent without delegating to spawn targets.
+ *
+ * @public
+ */
+type RegistryHarnessKind = 'orchestrator' | 'standalone';
 /**
  * How a provider resolves skill file precedence between vendor and agents directories.
  *
@@ -27,18 +79,44 @@ type SkillsPrecedence = 'vendor-only' | 'agents-canonical' | 'agents-first' | 'a
  * @public
  */
 type HookEvent = string;
+/**
+ * The on-disk layout of a provider's hook configuration.
+ *
+ * @remarks
+ * - `"json"`, `"yaml"`, `"toml"`, `"javascript"` — single configuration file
+ *   consumed by the provider.
+ * - `"typescript-directory"` — a directory of `.ts` extension files (Pi's model).
+ *
+ * @public
+ */
+type RegistryHookFormat = 'json' | 'yaml' | 'toml' | 'javascript' | 'typescript-directory';
+/**
+ * Which native event catalog a provider's hook system uses.
+ *
+ * @remarks
+ * - `"canonical"` — uses the core CAAMP `canonicalEvents` catalog from
+ *   `providers/hook-mappings.json`.
+ * - `"pi"` — uses the Pi-specific catalog (sibling entry to `canonicalEvents`)
+ *   that enumerates Pi's native lifecycle events such as `before_agent_start`
+ *   and `resources_discover`.
+ *
+ * @public
+ */
+type RegistryHookCatalog = 'canonical' | 'pi';
 /**
  * Mechanism a provider uses to spawn subagents.
  *
  * @remarks
  * - `"native"` - Built-in spawning via the provider's own runtime.
+ * - `"native-child-process"` - Built-in spawning that forks a local child
+ *   process (Pi's `pi --mode json -p --no-session` pattern).
  * - `"mcp"` - Spawning via MCP tool calls.
  * - `"cli"` - Spawning via CLI subprocess invocation.
  * - `"api"` - Spawning via a remote API endpoint.
  *
  * @public
  */
-type SpawnMechanism = 'native' | 'mcp' | 'cli' | 'api';
+type SpawnMechanism = 'native' | 'native-child-process' | 'mcp' | 'cli' | 'api';
 
 /**
  * SkillLibrary interface - SDK standard contract for skill libraries.
@@ -329,6 +407,7 @@ type ConfigFormat = 'json' | 'jsonc' | 'yaml' | 'toml';
  * - `"stdio"` - Standard input/output (local process)
  * - `"sse"` - Server-Sent Events (remote)
  * - `"http"` - HTTP/Streamable HTTP (remote)
+ * - `"websocket"` - WebSocket full-duplex (remote)
  *
  * @example
  * ```typescript
@@ -337,7 +416,7 @@ type ConfigFormat = 'json' | 'jsonc' | 'yaml' | 'toml';
  *
  * @public
  */
-type TransportType = 'stdio' | 'sse' | 'http';
+type TransportType = 'stdio' | 'sse' | 'http' | 'websocket';
 /**
  * Method used to detect whether an AI agent is installed on the system.
  *
@@ -394,6 +473,57 @@ interface DetectionConfig {
     flatpakId?: string;
 }
 
+/**
+ * Resolved MCP server integration metadata for a provider.
+ *
+ * @remarks
+ * Present only for providers that consume MCP servers via a per-agent
+ * config file. Providers that use extensions instead of MCP configs
+ * (e.g. Pi) omit this block. Template variables in paths are expanded
+ * at registry load time.
+ *
+ * @public
+ */
+interface ProviderMcpCapability {
+    /** Dot-notation key path for MCP server config (e.g. `"mcpServers"`). */
+    configKey: string;
+    /** Resolved config file format. */
+    configFormat: ConfigFormat;
+    /** Resolved global config file path. */
+    configPathGlobal: string;
+    /** Project-relative config file path, or `null` if unsupported. */
+    configPathProject: string | null;
+    /** MCP transport protocols this provider supports. */
+    supportedTransports: TransportType[];
+    /** Whether the provider supports custom HTTP headers for remote MCP servers. */
+    supportsHeaders: boolean;
+}
+/**
+ * Resolved first-class harness capability for a provider.
+ *
+ * @remarks
+ * Present only for providers that act as orchestrators or standalone
+ * harnesses. Paths under {@link extensionsPath} and {@link globalExtensionsHub}
+ * are resolved with platform template expansion at load time.
+ *
+ * @public
+ */
+interface ProviderHarnessCapability {
+    /** Harness kind (`"orchestrator"` or `"standalone"`). */
+    kind: RegistryHarnessKind;
+    /** Provider ids this harness can spawn as subagents. Empty for standalone. */
+    spawnTargets: string[];
+    /** Whether the harness drives a CleoOS conductor loop. */
+    supportsConductorLoop: boolean;
+    /** Whether the harness accepts stage guidance injection. */
+    supportsStageGuidance: boolean;
+    /** Whether the harness bridges CANT events. */
+    supportsCantBridge: boolean;
+    /** Resolved path to the harness's runtime extensions directory. */
+    extensionsPath: string;
+    /** Resolved CLEO-managed shared extensions hub path, if configured. */
+    globalExtensionsHub: string | null;
+}
 /**
  * Resolved skills capability for a provider at runtime.
  *
@@ -417,18 +547,29 @@ interface ProviderSkillsCapability {
  *
  * @remarks
  * Describes which hook lifecycle events a provider supports and where
- * the hook configuration file is located. The hook format indicates how
- * the configuration should be read and written.
+ * the hook configuration file (or extensions directory) is located. The
+ * hook format indicates how the configuration should be read and written;
+ * the `"typescript-directory"` value denotes providers (like Pi) whose
+ * hooks are compiled from a directory of TypeScript files rather than
+ * a single config file.
  *
  * @public
  */
 interface ProviderHooksCapability {
     /** Hook lifecycle events this provider supports. */
     supported: HookEvent[];
-    /** Resolved path to hook configuration file, or `null`. */
+    /** Resolved path to the hook configuration file or directory, or `null`. */
     hookConfigPath: string | null;
-    /** Format of the hook config file. */
-    hookFormat: 'json' | 'yaml' | 'toml' | 'javascript' | null;
+    /** Resolved project-relative hook configuration path, or `null`. */
+    hookConfigPathProject: string | null;
+    /** Format of the hook config. */
+    hookFormat: RegistryHookFormat | null;
+    /** Which native event catalog this provider's hooks are drawn from. */
+    nativeEventCatalog: RegistryHookCatalog;
+    /** Whether hooks may inject or modify the system prompt. */
+    canInjectSystemPrompt: boolean;
+    /** Whether hooks may block tool calls. */
+    canBlockTools: boolean;
 }
 /**
  * Resolved spawn capability for a provider at runtime.
@@ -451,18 +592,30 @@ interface ProviderSpawnCapability {
     supportsParallelSpawn: boolean;
     /** Mechanism used for spawning. */
     spawnMechanism: SpawnMechanism | null;
+    /**
+     * Literal command-line invocation used by the harness to spawn a child
+     * worker. Only meaningful when `spawnMechanism === "native-child-process"`.
+     */
+    spawnCommand: string[] | null;
 }
 /**
- * Aggregate provider capabilities for skills, hooks, and spawn.
+ * Aggregate provider capabilities for MCP, harness role, skills, hooks, and spawn.
  *
  * @remarks
- * Groups the three capability dimensions into a single object that is
- * always populated on the resolved {@link Provider} interface at runtime.
- * Unlike the raw registry type, all three fields are required here.
+ * Groups the capability dimensions into a single object on the resolved
+ * {@link Provider} interface at runtime. Skills, hooks, and spawn are
+ * always populated (with safe defaults when absent from the registry).
+ * MCP and harness are optional because not every provider is an MCP
+ * consumer (e.g. Pi uses extensions instead) and not every provider is
+ * a first-class harness (most are pure spawn targets).
  *
  * @public
  */
 interface ProviderCapabilities {
+    /** MCP server integration, when the provider consumes MCP via a config file. */
+    mcp: ProviderMcpCapability | null;
+    /** Harness role, present only for orchestrators and standalone harnesses. */
+    harness: ProviderHarnessCapability | null;
     /** Skills path resolution and precedence. */
     skills: ProviderSkillsCapability;
     /** Hook/lifecycle event support. */
@@ -470,41 +623,26 @@ interface ProviderCapabilities {
     /** Subagent spawn capabilities. */
     spawn: ProviderSpawnCapability;
 }
-/**
- * Priority tier for a provider, used for sorting and default selection.
- *
- * - `"high"` - Major, widely-used agents
- * - `"medium"` - Established but less common agents
- * - `"low"` - Niche or experimental agents
- *
- * @public
- */
-type ProviderPriority = 'high' | 'medium' | 'low';
-/**
- * Lifecycle status of a provider in the registry.
- *
- * - `"active"` - Fully supported
- * - `"beta"` - Supported but may have rough edges
- * - `"deprecated"` - Still present but no longer recommended
- * - `"planned"` - Not yet implemented
- *
- * @public
- */
-type ProviderStatus = 'active' | 'beta' | 'deprecated' | 'planned';
+
 /**
  * A resolved AI agent provider definition with platform-specific paths.
  *
  * @remarks
  * Providers are loaded from `providers/registry.json` and resolved at runtime
- * to expand platform-specific path variables (`$HOME`, `$CONFIG`, etc.).
- * This is the primary type used throughout the CAAMP codebase for working
- * with provider configurations.
+ * to expand platform-specific path variables (`$HOME`, `$CONFIG`, `$CLEO_HOME`,
+ * etc.). This is the primary type used throughout the CAAMP codebase for
+ * working with provider configurations.
+ *
+ * MCP server integration metadata (config key, format, paths, transports,
+ * headers) lives on {@link ProviderCapabilities.mcp} rather than at the
+ * top level. Providers that do not consume MCP servers (e.g. Pi, which uses
+ * TypeScript extensions) have `capabilities.mcp === null`.
  *
  * @example
  * ```typescript
  * const provider = getProvider("claude-code");
- * if (provider) {
- *   console.log(provider.configPathGlobal);
+ * if (provider?.capabilities.mcp) {
+ *   console.log(provider.capabilities.mcp.configPathGlobal);
  * }
  * ```
  *
@@ -527,31 +665,19 @@ interface Provider {
     pathProject: string;
     /** Instruction file name (e.g. `"CLAUDE.md"`, `"AGENTS.md"`). */
     instructFile: string;
-    /** Dot-notation key path for MCP server config (e.g. `"mcpServers"`). */
-    configKey: string;
-    /** Config file format used by this provider. */
-    configFormat: ConfigFormat;
-    /** Resolved global config file path. */
-    configPathGlobal: string;
-    /** Project-relative config file path, or `null` if unsupported. */
-    configPathProject: string | null;
     /** Resolved global skills directory path. */
     pathSkills: string;
     /** Project-relative skills directory path. */
     pathProjectSkills: string;
     /** Detection configuration for auto-discovering this provider. */
     detection: DetectionConfig;
-    /** MCP transport protocols this provider supports. */
-    supportedTransports: TransportType[];
-    /** Whether the provider supports custom HTTP headers for remote MCP servers. */
-    supportsHeaders: boolean;
     /** Priority tier for sorting and default selection. */
     priority: ProviderPriority;
     /** Lifecycle status in the registry. */
     status: ProviderStatus;
     /** Whether the provider is compatible with the Agent Skills standard. */
     agentSkillsCompatible: boolean;
-    /** Provider capabilities for skills, hooks, and spawn. Always populated at runtime. */
+    /** Provider capabilities (MCP, harness, skills, hooks, spawn). Always populated at runtime. */
     capabilities: ProviderCapabilities;
 }
 /**
@@ -1341,169 +1467,801 @@ interface InstructionUpdateSummary {
  * providers by their instruction file targets and injects content using
  * marker-based sections.
  *
- * @param providers - The providers whose instruction files to update
- * @param content - The instruction content to inject
- * @param scope - The scope for instruction updates, defaults to `"project"`
- * @param projectDir - The project root directory, defaults to `process.cwd()`
- * @returns A summary of updated files and actions taken per file
+ * @param providers - The providers whose instruction files to update
+ * @param content - The instruction content to inject
+ * @param scope - The scope for instruction updates, defaults to `"project"`
+ * @param projectDir - The project root directory, defaults to `process.cwd()`
+ * @returns A summary of updated files and actions taken per file
+ *
+ * @example
+ * ```typescript
+ * const summary = await updateInstructionsSingleOperation(
+ *   providers,
+ *   "## CAAMP Config\nUse these MCP servers...",
+ *   "project",
+ * );
+ * console.log(`Updated ${summary.updatedFiles} files`);
+ * ```
+ *
+ * @public
+ */
+declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
+
+/**
+ * Format utility functions
+ */
+/**
+ * Deep merge two objects, with `source` values winning on conflict.
+ *
+ * Recursively merges nested plain objects. Arrays and non-object values from
+ * `source` overwrite `target` values.
+ *
+ * @param target - Base object to merge into
+ * @param source - Object with values that take precedence
+ * @returns A new merged object (does not mutate inputs)
+ *
+ * @remarks
+ * Only plain objects are recursively merged. Arrays and primitive values from
+ * `source` replace `target` values outright. Neither input is mutated.
+ *
+ * @example
+ * ```typescript
+ * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+ * // { a: 1, b: { c: 2, d: 3 } }
+ * ```
+ *
+ * @public
+ */
+declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Get a nested value from an object using a dot-notation key path.
+ *
+ * @param obj - Object to traverse
+ * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
+ * @returns The value at the key path, or `undefined` if not found
+ *
+ * @remarks
+ * Splits the key path on `.` and walks the object tree. Returns `undefined`
+ * at the first missing or non-object segment.
+ *
+ * @example
+ * ```typescript
+ * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
+ * getNestedValue({ a: 1 }, "a.b"); // undefined
+ * ```
+ *
+ * @public
+ */
+declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
+/**
+ * Ensure that the parent directories of a file path exist.
+ *
+ * Creates directories recursively if they do not exist.
+ *
+ * @param filePath - Absolute path to a file (parent directories will be created)
+ *
+ * @remarks
+ * Uses `mkdir` with `recursive: true` so existing directories are not an error.
+ *
+ * @example
+ * ```typescript
+ * await ensureDir("/path/to/new/dir/file.json");
+ * // /path/to/new/dir/ now exists
+ * ```
+ *
+ * @public
+ */
+declare function ensureDir(filePath: string): Promise<void>;
+
+/**
+ * Provides format-agnostic config read, write, and remove operations that
+ * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
+ * format.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Read and parse a config file in the specified format.
+ *
+ * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @returns Parsed config object
+ * @throws If the file cannot be read or the format is unsupported
+ *
+ * @remarks
+ * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
+ * any unrecognized format string.
+ *
+ * @example
+ * ```typescript
+ * const config = await readConfig("/path/to/config.json", "jsonc");
+ * ```
+ *
+ * @public
+ */
+declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
+/**
+ * Write a server entry to a config file, preserving existing content.
+ *
+ * Dispatches to the appropriate format handler. For JSONC files, comments are
+ * preserved using `jsonc-parser`.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
+ * @param serverName - Name/key for the server entry
+ * @param serverConfig - Server configuration object to write
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
+ * For YAML and TOML, the file is fully re-serialized after deep-merging.
+ *
+ * @example
+ * ```typescript
+ * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
+ * ```
+ *
+ * @public
+ */
+declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
+/**
+ * Remove a server entry from a config file in the specified format.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section
+ * @param serverName - Name/key of the server entry to remove
+ * @returns `true` if the entry was removed, `false` otherwise
+ * @throws If the format is unsupported
+ *
+ * @remarks
+ * Delegates to the format-specific removal function. Returns `false` when the
+ * file does not exist or the entry is not found.
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
+ * ```
+ *
+ * @public
+ */
+declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
+
+/**
+ * Skill installer - canonical + symlink model
+ *
+ * Skills are stored once in a canonical location (.agents/skills/<name>/)
+ * and symlinked to each target agent's skills directory.
+ */
+
+/**
+ * Result of installing a skill to the canonical location and linking to agents.
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill(sourcePath, "my-skill", providers, true);
+ * if (result.success) {
+ *   console.log(`Installed to ${result.canonicalPath}`);
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+interface SkillInstallResult {
+    /** Skill name. */
+    name: string;
+    /** Absolute path to the canonical installation directory. */
+    canonicalPath: string;
+    /** Provider IDs that were successfully linked. */
+    linkedAgents: string[];
+    /** Error messages from failed link operations. */
+    errors: string[];
+    /** Whether at least one agent was successfully linked. */
+    success: boolean;
+}
+/**
+ * Install a skill from a local path to the canonical location and link to agents.
+ *
+ * @remarks
+ * Copies the skill directory to the canonical skills directory and creates symlinks
+ * (or copies on Windows) from each provider's skills directory to the canonical path.
+ *
+ * @param sourcePath - Local path to the skill directory to install
+ * @param skillName - Name for the installed skill
+ * @param providers - Target providers to link the skill to
+ * @param isGlobal - Whether to link to global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Install result with linked agents and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
+ * if (result.success) {
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
+/**
+ * Remove a skill from the canonical location and all agent symlinks.
+ *
+ * @remarks
+ * Removes symlinks from each provider's skills directory and then removes the
+ * canonical copy from the centralized canonical skills directory.
+ *
+ * @param skillName - Name of the skill to remove
+ * @param providers - Providers to unlink the skill from
+ * @param isGlobal - Whether to target global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Object with arrays of successfully removed provider IDs and error messages
+ *
+ * @example
+ * ```typescript
+ * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
+ * console.log(`Removed from: ${removed.join(", ")}`);
+ * ```
+ *
+ * @public
+ */
+declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
+    removed: string[];
+    errors: string[];
+}>;
+/**
+ * List all skills installed in the canonical skills directory.
+ *
+ * @remarks
+ * Returns the directory names of all skills, which correspond to skill names.
+ * Includes both regular directories and symlinks in the canonical location.
+ *
+ * @returns Array of skill names
+ *
+ * @example
+ * ```typescript
+ * const skills = await listCanonicalSkills();
+ * // ["my-skill", "another-skill"]
+ * ```
+ *
+ * @public
+ */
+declare function listCanonicalSkills(): Promise<string[]>;
+
+/**
+ * Harness layer type definitions.
+ *
+ * @remarks
+ * Defines the contract every first-class CAAMP harness must implement.
+ * A harness is a provider that CAAMP treats natively — not through the
+ * generic MCP-config-file path. Pi is the first (and currently only)
+ * harness. The interface is intentionally generic so future harnesses
+ * (Goose, OpenCode, ...) can slot in without shape churn.
+ *
+ * All methods are async even when they could be sync, so implementations
+ * that need I/O (filesystem, child process) are not forced to lie about
+ * their return types.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scope at which a harness operation should be performed.
+ *
+ * @remarks
+ * Harness operations target either the user's global state root (e.g.
+ * `~/.pi/agent/`) or a specific project directory. Project scope requires
+ * the caller to provide the absolute project directory path — the harness
+ * does not infer cwd.
+ *
+ * @public
+ */
+type HarnessScope = {
+    kind: 'global';
+} | {
+    kind: 'project';
+    projectDir: string;
+};
+/**
+ * Declarative description of an MCP server that should be bridged into a
+ * harness's native extension mechanism.
+ *
+ * @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}.
+ *
+ * Harnesses that cannot host MCP servers as extensions will throw or omit
+ * the {@link Harness.installMcpAsExtension} method entirely.
+ *
+ * @public
+ */
+interface McpServerSpec {
+    /** Logical name of the MCP server (e.g. `"filesystem"`, `"brave-search"`). */
+    name: string;
+    /**
+     * Command to launch the server over stdio transport.
+     * @defaultValue undefined
+     */
+    command?: string;
+    /**
+     * Arguments for the stdio command.
+     * @defaultValue undefined
+     */
+    args?: string[];
+    /**
+     * URL for SSE/HTTP transports.
+     * @defaultValue undefined
+     */
+    url?: string;
+    /**
+     * Environment variables for the server process.
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * HTTP headers for remote transports.
+     * @defaultValue undefined
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Description of a subagent task to be spawned under a harness.
+ *
+ * @remarks
+ * Generic across harnesses: the same shape describes a Pi-managed child,
+ * a future Goose-managed child, or any other. The {@link targetProviderId}
+ * is a routing hint passed to the harness; concrete harnesses may use it
+ * to select an inner agent or simply record it for observability.
+ *
+ * @public
+ */
+interface SubagentTask {
+    /** Provider id of the agent to spawn (e.g. `"claude-code"`). */
+    targetProviderId: string;
+    /** The prompt / instruction to give the spawned agent. */
+    prompt: string;
+    /**
+     * Working directory for the spawned agent.
+     * @defaultValue undefined
+     */
+    cwd?: string;
+    /**
+     * Environment variable overrides layered atop the parent environment.
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * Abort signal. When it aborts, the harness will terminate the subagent.
+     * @defaultValue undefined
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Final result of a subagent's execution.
+ *
+ * @remarks
+ * Collected once the child process exits. {@link parsed} is populated
+ * on a best-effort basis: if the subagent emits JSON on stdout the
+ * harness will parse it, otherwise {@link parsed} is left undefined.
+ *
+ * @public
+ */
+interface SubagentResult {
+    /** Process exit code, or `null` if the process was killed by a signal. */
+    exitCode: number | null;
+    /** Full stdout captured from the subagent. */
+    stdout: string;
+    /** Full stderr captured from the subagent. */
+    stderr: string;
+    /**
+     * Parsed JSON output, when the target supports a JSON output mode and
+     * emitted well-formed JSON on stdout.
+     * @defaultValue undefined
+     */
+    parsed?: unknown;
+}
+/**
+ * Live handle to a running subagent.
+ *
+ * @remarks
+ * Returned synchronously from {@link Harness.spawnSubagent}. The caller
+ * may await {@link result} to collect the final output, or invoke
+ * {@link abort} to terminate the child early.
+ *
+ * @public
+ */
+interface SubagentHandle {
+    /** PID of the spawned process, or `null` if spawning did not yield one. */
+    pid: number | null;
+    /** Promise resolving to the subagent's final output once the process exits. */
+    result: Promise<SubagentResult>;
+    /** Synchronously terminate the subagent. Safe to call after exit. */
+    abort: () => void;
+}
+/**
+ * Contract every first-class harness must implement.
+ *
+ * @remarks
+ * A harness is a provider that CAAMP treats natively — installing skills,
+ * MCP bridges, instruction files, and subagent spawns through harness-specific
+ * mechanisms rather than a generic MCP config file. Pi is the first concrete
+ * 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.
+ *
+ * @public
+ */
+interface Harness {
+    /** Short id matching the provider id (e.g. `"pi"`). */
+    readonly id: string;
+    /** The underlying resolved provider entry. */
+    readonly provider: Provider;
+    /**
+     * Install a skill using the harness's native mechanism.
+     *
+     * @remarks
+     * For Pi: copy the source skill directory into
+     * `~/.pi/agent/skills/<skillName>/` (global) or `<projectDir>/.pi/skills/<skillName>/`
+     * (project). Pi resolves paths at load time so a symlink would work, but
+     * CAAMP prefers a recursive copy to avoid cross-filesystem symlink issues.
+     *
+     * @param sourcePath - Absolute path to the skill directory to install.
+     * @param skillName - Target skill name (becomes the directory name on disk).
+     * @param scope - Install target scope.
+     */
+    installSkill(sourcePath: string, skillName: string, scope: HarnessScope): Promise<void>;
+    /**
+     * Remove a skill previously installed via this harness.
+     *
+     * @remarks
+     * Missing skills are tolerated silently so callers can use this as an
+     * idempotent "ensure absent" operation.
+     *
+     * @param skillName - Skill name to remove.
+     * @param scope - Install target scope.
+     */
+    removeSkill(skillName: string, scope: HarnessScope): Promise<void>;
+    /**
+     * List skills installed in this harness's skill directory for a scope.
+     *
+     * @remarks
+     * Returns the skill directory names (not absolute paths). Missing scope
+     * directories return an empty array rather than throwing.
+     *
+     * @param scope - Scope to inspect.
+     * @returns Array of skill directory names.
+     */
+    listSkills(scope: HarnessScope): Promise<string[]>;
+    /**
+     * Inject content into the harness's instruction file using a marker-based
+     * idempotent block.
+     *
+     * @remarks
+     * For Pi the target file is `~/.pi/agent/AGENTS.md` (global) or
+     * `<projectDir>/AGENTS.md` at the project root (not under `.pi/`). The
+     * injection uses `<!-- CAAMP:START -->` / `<!-- CAAMP:END -->` markers so
+     * subsequent calls replace the block in place.
+     *
+     * @param content - The content to inject inside the marker block.
+     * @param scope - Instruction file scope.
+     */
+    injectInstructions(content: string, scope: HarnessScope): Promise<void>;
+    /**
+     * Remove the CAAMP injection block from the harness's instruction file.
+     *
+     * @remarks
+     * The surrounding file content is preserved. Missing files are tolerated.
+     *
+     * @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.
+     *
+     * @remarks
+     * For Pi: invokes `child_process.spawn` with the provider's configured
+     * `capabilities.spawn.spawnCommand`, appending the task prompt as a
+     * trailing positional argument. The returned handle lets the caller await
+     * completion or abort early.
+     *
+     * Optional — harnesses that cannot spawn other agents should omit this
+     * method. Callers MUST feature-check before invoking.
+     *
+     * @param task - Subagent task specification.
+     * @returns A live subagent handle.
+     */
+    spawnSubagent?(task: SubagentTask): Promise<SubagentHandle>;
+    /**
+     * Configure which models are available in the harness's model picker.
+     *
+     * @remarks
+     * For Pi: writes the provided glob list to `settings.json:enabledModels`.
+     *
+     * Optional — harnesses without a model picker should omit this method.
+     *
+     * @param modelPatterns - Glob patterns enumerating enabled models.
+     * @param scope - Settings scope.
+     */
+    configureModels?(modelPatterns: string[], scope: HarnessScope): Promise<void>;
+    /**
+     * Read the harness's current settings as an opaque object.
+     *
+     * @remarks
+     * The shape is harness-specific; callers that care about fields must know
+     * the concrete harness's schema. Missing files resolve to an empty object.
+     *
+     * @param scope - Settings scope.
+     * @returns Opaque settings blob.
+     */
+    readSettings(scope: HarnessScope): Promise<unknown>;
+    /**
+     * Deep-merge a patch into the harness's settings and persist the result.
+     *
+     * @remarks
+     * The patch is merged, not replaced, so unrelated fields survive. The
+     * shape is harness-specific.
+     *
+     * @param patch - Partial settings object to merge.
+     * @param scope - Settings scope.
+     */
+    writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
+}
+
+/**
+ * Pi coding agent harness.
+ *
+ * @remarks
+ * Concrete {@link Harness} implementation for the Pi coding agent
+ * (https://github.com/badlogic/pi-mono). Pi is CAAMP's first first-class
+ * primary harness: it owns skills, instructions, extensions, and subagent
+ * spawning through native filesystem conventions rather than a generic
+ * MCP config file.
  *
- * @example
- * ```typescript
- * const summary = await updateInstructionsSingleOperation(
- *   providers,
- *   "## CAAMP Config\nUse these MCP servers...",
- *   "project",
- * );
- * console.log(`Updated ${summary.updatedFiles} files`);
- * ```
+ * Filesystem layout honoured by this harness:
+ * - Global state root: `$PI_CODING_AGENT_DIR` if set, else `~/.pi/agent/`.
+ * - Global skills: `<root>/skills/<name>/`
+ * - Global extensions: `<root>/extensions/*.ts`
+ * - Global settings: `<root>/settings.json`
+ * - Global instructions: `<root>/AGENTS.md`
+ * - Project skills: `<projectDir>/.pi/skills/<name>/`
+ * - Project extensions: `<projectDir>/.pi/extensions/*.ts`
+ * - Project settings: `<projectDir>/.pi/settings.json`
+ * - Project instructions: `<projectDir>/AGENTS.md` (at project root, NOT under `.pi/`)
  *
- * @public
+ * @packageDocumentation
  */
-declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
 
 /**
- * Format utility functions
- */
-/**
- * Deep merge two objects, with `source` values winning on conflict.
- *
- * Recursively merges nested plain objects. Arrays and non-object values from
- * `source` overwrite `target` values.
- *
- * @param target - Base object to merge into
- * @param source - Object with values that take precedence
- * @returns A new merged object (does not mutate inputs)
+ * Pi coding agent harness — CAAMP's first-class primary harness.
  *
  * @remarks
- * Only plain objects are recursively merged. Arrays and primitive values from
- * `source` replace `target` values outright. Neither input is mutated.
+ * Implements the full {@link Harness} contract using Pi's filesystem
+ * conventions. All mutating operations are idempotent: re-installing a
+ * skill overwrites it cleanly, injecting instructions twice replaces the
+ * marker block rather than appending, and removing absent assets is a
+ * no-op.
  *
- * @example
- * ```typescript
- * const merged = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
- * // { a: 1, b: { c: 2, d: 3 } }
- * ```
+ * @see {@link https://github.com/badlogic/pi-mono | pi-mono}
  *
  * @public
  */
-declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+declare class PiHarness implements Harness {
+    readonly provider: Provider;
+    /** Provider id, always `"pi"`. */
+    readonly id = "pi";
+    /**
+     * Construct a harness bound to a resolved Pi provider.
+     *
+     * @param provider - The resolved provider entry for `"pi"`.
+     */
+    constructor(provider: Provider);
+    /**
+     * 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.
+     */
+    private settingsPath;
+    /**
+     * Resolve the AGENTS.md instruction file path for a given scope.
+     *
+     * @remarks
+     * Global scope lives under the Pi state root; project scope lives at
+     * the project root (NOT under `.pi/`), matching Pi's convention of
+     * auto-discovering `AGENTS.md` from the working directory upwards.
+     */
+    private agentsMdPath;
+    /** {@inheritDoc Harness.installSkill} */
+    installSkill(sourcePath: string, skillName: string, scope: HarnessScope): Promise<void>;
+    /** {@inheritDoc Harness.removeSkill} */
+    removeSkill(skillName: string, scope: HarnessScope): Promise<void>;
+    /** {@inheritDoc Harness.listSkills} */
+    listSkills(scope: HarnessScope): Promise<string[]>;
+    /** {@inheritDoc Harness.injectInstructions} */
+    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}
+     *
+     * @remarks
+     * Invokes Pi's configured `spawnCommand` (e.g.
+     * `["pi", "--mode", "json", "-p", "--no-session"]`) with the task prompt
+     * appended as the trailing positional argument. The {@link SubagentTask.targetProviderId}
+     * is a routing hint carried in the prompt stream; Pi's own extension
+     * layer dispatches to the correct inner agent.
+     *
+     * Throws immediately when the provider entry is missing a `spawnCommand`
+     * so callers see configuration errors early rather than at child-exit time.
+     */
+    spawnSubagent(task: SubagentTask): Promise<SubagentHandle>;
+    /** {@inheritDoc Harness.readSettings} */
+    readSettings(scope: HarnessScope): Promise<unknown>;
+    /** {@inheritDoc Harness.writeSettings} */
+    writeSettings(patch: Record<string, unknown>, scope: HarnessScope): Promise<void>;
+    /** {@inheritDoc Harness.configureModels} */
+    configureModels(modelPatterns: string[], scope: HarnessScope): Promise<void>;
+}
+
 /**
- * Get a nested value from an object using a dot-notation key path.
- *
- * @param obj - Object to traverse
- * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
- * @returns The value at the key path, or `undefined` if not found
+ * Harness layer dispatcher.
  *
  * @remarks
- * Splits the key path on `.` and walks the object tree. Returns `undefined`
- * at the first missing or non-object segment.
+ * This module is the single entry point for resolving a concrete
+ * {@link Harness} implementation from a provider (or from the registry's
+ * primary provider). It owns the switch that maps provider ids to
+ * implementations so the rest of CAAMP never needs to construct harness
+ * classes directly.
  *
- * @example
- * ```typescript
- * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
- * getNestedValue({ a: 1 }, "a.b"); // undefined
- * ```
+ * Today only Pi has a harness implementation. Future harnesses (Goose,
+ * OpenCode, ...) will be added to {@link getHarnessFor} alongside Pi.
  *
- * @public
+ * @packageDocumentation
  */
-declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
+
 /**
- * Ensure that the parent directories of a file path exist.
- *
- * Creates directories recursively if they do not exist.
- *
- * @param filePath - Absolute path to a file (parent directories will be created)
+ * Return the harness implementation for a provider, or `null` if the
+ * provider has no first-class harness.
  *
  * @remarks
- * Uses `mkdir` with `recursive: true` so existing directories are not an error.
+ * This is the primary dispatcher. As new harnesses are added, their
+ * provider id → implementation mapping lives here.
+ *
+ * @param provider - Resolved provider to look up.
+ * @returns A harness instance, or `null` if the provider is a pure spawn
+ * target with no native harness.
  *
  * @example
  * ```typescript
- * await ensureDir("/path/to/new/dir/file.json");
- * // /path/to/new/dir/ now exists
+ * const pi = getProvider("pi");
+ * if (pi) {
+ *   const harness = getHarnessFor(pi);
+ *   await harness?.installSkill("/path/to/skill", "my-skill", { kind: "global" });
+ * }
  * ```
  *
  * @public
  */
-declare function ensureDir(filePath: string): Promise<void>;
-
-/**
- * Provides format-agnostic config read, write, and remove operations that
- * dispatch to JSON/JSONC, YAML, or TOML handlers based on the specified
- * format.
- *
- * @packageDocumentation
- */
-
+declare function getHarnessFor(provider: Provider): Harness | null;
 /**
- * Read and parse a config file in the specified format.
- *
- * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @returns Parsed config object
- * @throws If the file cannot be read or the format is unsupported
+ * Return the primary harness declared in the registry, if any.
  *
  * @remarks
- * Supported formats: `"json"`, `"jsonc"`, `"yaml"`, `"toml"`. Throws for
- * any unrecognized format string.
+ * Resolves the registry's primary provider (via
+ * {@link getPrimaryProvider}) and returns its harness implementation.
+ * Callers use this to resolve the default `--agent` target when no flag
+ * is provided.
+ *
+ * @returns The primary harness, or `null` if no primary provider exists
+ * or the primary provider has no harness implementation.
  *
  * @example
  * ```typescript
- * const config = await readConfig("/path/to/config.json", "jsonc");
+ * const primary = getPrimaryHarness();
+ * if (primary) {
+ *   console.log(`Primary harness: ${primary.provider.toolName}`);
+ * }
  * ```
  *
  * @public
  */
-declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
+declare function getPrimaryHarness(): Harness | null;
 /**
- * Write a server entry to a config file, preserving existing content.
- *
- * Dispatches to the appropriate format handler. For JSONC files, comments are
- * preserved using `jsonc-parser`.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
- * @param serverName - Name/key for the server entry
- * @param serverConfig - Server configuration object to write
- * @throws If the format is unsupported
+ * Return every provider that has a harness implementation.
  *
  * @remarks
- * For JSONC files, comments and formatting are preserved using `jsonc-parser`.
- * For YAML and TOML, the file is fully re-serialized after deep-merging.
+ * Iterates all registered providers and collects their harness instances.
+ * Useful for diagnostics and for surfaces like
+ * `caamp providers list --harnesses`.
  *
- * @example
- * ```typescript
- * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
- * ```
+ * @returns Array of harness instances, one per provider that implements
+ * the {@link Harness} contract.
  *
  * @public
  */
-declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
+declare function getAllHarnesses(): Harness[];
 /**
- * Remove a server entry from a config file in the specified format.
- *
- * @param filePath - Absolute path to the config file
- * @param format - Config file format
- * @param key - Dot-notation key path to the servers section
- * @param serverName - Name/key of the server entry to remove
- * @returns `true` if the entry was removed, `false` otherwise
- * @throws If the format is unsupported
+ * Resolve the default set of target providers when the user has not passed
+ * `--agent`.
  *
  * @remarks
- * Delegates to the format-specific removal function. Returns `false` when the
- * file does not exist or the entry is not found.
+ * Resolution policy:
+ *
+ * 1. If the registry's primary harness (the provider with
+ *    `priority === "primary"`) is installed on the current system,
+ *    return `[primaryProvider]` so that commands dispatch to the
+ *    primary harness by default.
+ * 2. Otherwise, return the set of installed providers at priority
+ *    `"primary"` or `"high"`. This restores the legacy "detected high-tier
+ *    providers" fallback that CAAMP has always used when no primary
+ *    harness is available.
+ * 3. If the priority filter yields an empty list (e.g. in tests that stub
+ *    providers without a `priority` field, or in fresh installs with only
+ *    medium/low-tier providers detected), fall back to the full installed
+ *    provider list so that commands retain a valid target.
+ *
+ * This helper is intentionally defensive: it swallows registry-related
+ * exceptions (returning an empty-primary-harness result) so stubbed test
+ * environments that do not wire the full provider registry still behave
+ * sensibly.
+ *
+ * @returns Ordered list of providers to target by default.
  *
  * @example
  * ```typescript
- * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
+ * const targets = resolveDefaultTargetProviders();
+ * if (targets.length === 0) {
+ *   console.error("No target providers found. Use --agent or --all.");
+ * }
  * ```
  *
  * @public
  */
-declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
+declare function resolveDefaultTargetProviders(): Provider[];
 
 /**
  * All hook event categories (8 total).
@@ -3090,9 +3848,9 @@ declare function getAgentsLinksDir(scope?: PathScope, projectDir?: string): stri
  *
  * @remarks
  * Replaces template variables like `$HOME`, `$CONFIG`, `$VSCODE_CONFIG`,
- * `$ZED_CONFIG`, `$CLAUDE_DESKTOP_CONFIG`, and `$AGENTS_HOME` with their
- * actual platform-specific values. Used to resolve paths from the provider
- * registry JSON.
+ * `$ZED_CONFIG`, `$CLAUDE_DESKTOP_CONFIG`, `$AGENTS_HOME`, and `$CLEO_HOME`
+ * with their actual platform-specific values. Used to resolve paths from
+ * the provider registry JSON.
  *
  * @param template - The template string containing `$VARIABLE` placeholders
  * @returns The resolved absolute path with all variables expanded
@@ -3478,8 +4236,10 @@ declare function resolveAlias(idOrAlias: string): string;
  * @remarks
  * Provider priority is assigned in `providers/registry.json` and indicates the
  * relative importance of a provider for detection ordering and display.
+ * Callers filtering by `"primary"` should expect zero or one result; the
+ * registry loader does not enforce the single-primary invariant.
  *
- * @param priority - Priority level to filter by (`"high"`, `"medium"`, or `"low"`)
+ * @param priority - Priority level to filter by (`"primary"`, `"high"`, `"medium"`, or `"low"`)
  * @returns Array of providers matching the given priority
  *
  * @example
@@ -3491,6 +4251,29 @@ declare function resolveAlias(idOrAlias: string): string;
  * @public
  */
 declare function getProvidersByPriority(priority: ProviderPriority): Provider[];
+/**
+ * Get the single primary harness provider, if any is registered.
+ *
+ * @remarks
+ * Returns the provider with `priority === "primary"`. By convention a
+ * registry defines at most one primary harness; this function returns
+ * the first match if the invariant is violated and logs no warning. Use
+ * {@link getProvidersByPriority} instead if you need to diagnose
+ * duplicates.
+ *
+ * @returns The primary provider, or `undefined` if none is registered
+ *
+ * @example
+ * ```typescript
+ * const primary = getPrimaryProvider();
+ * if (primary) {
+ *   console.log(`Primary harness: ${primary.toolName}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getPrimaryProvider(): Provider | undefined;
 /**
  * Filter providers by their lifecycle status.
  *
@@ -3574,7 +4357,7 @@ declare function getProviderCount(): number;
  * The version is read from the top-level `version` field in `providers/registry.json`
  * and follows semver conventions. It is bumped when provider definitions change.
  *
- * @returns Version string from `providers/registry.json` (e.g. `"1.0.0"`)
+ * @returns Version string from `providers/registry.json` (e.g. `"2.0.0"`)
  *
  * @example
  * ```typescript
@@ -3679,8 +4462,8 @@ declare function getSpawnCapableProviders(): Provider[];
  *
  * @remarks
  * The spawn capability has four boolean flags that can be queried independently.
- * The `spawnMechanism` string field is excluded from the flag type since it is
- * not a boolean check.
+ * The `spawnMechanism` and `spawnCommand` fields are excluded from the flag
+ * type since they are not boolean checks.
  *
  * @param flag - One of the four boolean flags on {@link ProviderSpawnCapability}
  *              (`"supportsSubagents"`, `"supportsProgrammaticSpawn"`,
@@ -3697,7 +4480,7 @@ declare function getSpawnCapableProviders(): Provider[];
  *
  * @public
  */
-declare function getProvidersBySpawnCapability(flag: keyof Omit<ProviderSpawnCapability, 'spawnMechanism'>): Provider[];
+declare function getProvidersBySpawnCapability(flag: keyof Omit<ProviderSpawnCapability, 'spawnMechanism' | 'spawnCommand'>): Provider[];
 /**
  * Filter providers by their skills precedence value.
  *
@@ -3784,7 +4567,8 @@ declare function buildSkillsMap(): Array<{
  *
  * @remarks
  * Shorthand for `getProvider(idOrAlias)?.capabilities`. Returns the full
- * capabilities object containing skills, hooks, and spawn sub-objects.
+ * capabilities object containing mcp, harness, skills, hooks, and spawn
+ * sub-objects.
  *
  * @param idOrAlias - Provider ID or alias
  * @returns The provider's capabilities, or undefined if not found
@@ -4622,108 +5406,6 @@ declare function discoverSkill(skillDir: string): Promise<SkillEntry | null>;
  */
 declare function discoverSkills(rootDir: string): Promise<SkillEntry[]>;
 
-/**
- * Skill installer - canonical + symlink model
- *
- * Skills are stored once in a canonical location (.agents/skills/<name>/)
- * and symlinked to each target agent's skills directory.
- */
-
-/**
- * Result of installing a skill to the canonical location and linking to agents.
- *
- * @example
- * ```typescript
- * const result = await installSkill(sourcePath, "my-skill", providers, true);
- * if (result.success) {
- *   console.log(`Installed to ${result.canonicalPath}`);
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
- *
- * @public
- */
-interface SkillInstallResult {
-    /** Skill name. */
-    name: string;
-    /** Absolute path to the canonical installation directory. */
-    canonicalPath: string;
-    /** Provider IDs that were successfully linked. */
-    linkedAgents: string[];
-    /** Error messages from failed link operations. */
-    errors: string[];
-    /** Whether at least one agent was successfully linked. */
-    success: boolean;
-}
-/**
- * Install a skill from a local path to the canonical location and link to agents.
- *
- * @remarks
- * Copies the skill directory to the canonical skills directory and creates symlinks
- * (or copies on Windows) from each provider's skills directory to the canonical path.
- *
- * @param sourcePath - Local path to the skill directory to install
- * @param skillName - Name for the installed skill
- * @param providers - Target providers to link the skill to
- * @param isGlobal - Whether to link to global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Install result with linked agents and any errors
- *
- * @example
- * ```typescript
- * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
- * if (result.success) {
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
- * ```
- *
- * @public
- */
-declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
-/**
- * Remove a skill from the canonical location and all agent symlinks.
- *
- * @remarks
- * Removes symlinks from each provider's skills directory and then removes the
- * canonical copy from the centralized canonical skills directory.
- *
- * @param skillName - Name of the skill to remove
- * @param providers - Providers to unlink the skill from
- * @param isGlobal - Whether to target global or project skill directories
- * @param projectDir - Project directory (defaults to `process.cwd()`)
- * @returns Object with arrays of successfully removed provider IDs and error messages
- *
- * @example
- * ```typescript
- * const { removed, errors } = await removeSkill("my-skill", providers, true, "/my/project");
- * console.log(`Removed from: ${removed.join(", ")}`);
- * ```
- *
- * @public
- */
-declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
-    removed: string[];
-    errors: string[];
-}>;
-/**
- * List all skills installed in the canonical skills directory.
- *
- * @remarks
- * Returns the directory names of all skills, which correspond to skill names.
- * Includes both regular directories and symlinks in the canonical location.
- *
- * @returns Array of skill names
- *
- * @example
- * ```typescript
- * const skills = await listCanonicalSkills();
- * // ["my-skill", "another-skill"]
- * ```
- *
- * @public
- */
-declare function listCanonicalSkills(): Promise<string[]>;
-
 /**
  * Skill integrity checking
  *
@@ -4906,7 +5588,7 @@ declare function validateInstructionIntegrity(providers: Provider[], projectDir:
  *
  * @example
  * ```typescript
- * const library = loadLibraryFromModule("/home/user/.agents/libraries/ct-skills");
+ * const library = loadLibraryFromModule("/home/user/.agents/libraries/cleocode-skills");
  * console.log(`Loaded v${library.version} with ${library.listSkills().length} skills`);
  * ```
  *
@@ -4931,7 +5613,7 @@ declare function loadLibraryFromModule(root: string): SkillLibrary;
  *
  * @example
  * ```typescript
- * const library = buildLibraryFromFiles("/home/user/.agents/libraries/ct-skills");
+ * const library = buildLibraryFromFiles("/home/user/.agents/libraries/cleocode-skills");
  * const coreSkills = library.getCoreSkills();
  * console.log(`Core skills: ${coreSkills.map(s => s.name).join(", ")}`);
  * ```
@@ -5663,4 +6345,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 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 McpServerConfig, type McpServerEntry, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, type PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, 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 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 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, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, 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, 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 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 };