cyber-agentkit 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,724 @@
+import { n as harnessIds, t as HarnessId } from "./harness-id-BgKL-x6C.js";
+import { A as FoundSkill, C as defaultLayer, D as ReferenceCode, E as userReferencesDir, M as skillsIn, N as Platform, O as ReferenceWarning, S as SkillDefaults, T as referenceLayers, _ as ReferenceLayer, a as ReferenceTrace, b as ReferencePlugin, c as ReferenceTraceSection, d as referenceNames, f as resolveReference, g as SectionSource, h as MergeOperation, i as ReferenceStatus, j as skillName, k as ReferenceWarningCode, l as ResolveOptions, m as parseReferenceName, n as ExtendsStep, o as ReferenceTraceContribution, p as ReferenceName, r as OperationSource, s as ReferenceTraceLayer, t as AmbiguousCause, u as ResolvedReference, v as ReferenceLayerOptions, w as projectReferencesDir, x as ReferenceTier, y as ReferenceLayers } from "./resolve-reference-Cis-Ye6T.js";
+//#region src/harness/harness-environment.d.ts
+/**
+ * The parts of the running process a harness query depends on. Every field defaults to the
+ * current process, so callers pass them only to inspect another environment (or in tests).
+ */
+interface HarnessEnvironment {
+  /** Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Defaults to `os.homedir()`. */
+  readonly homedir?: string;
+  /** The project directory, for project-scoped settings. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Defaults to `process.platform`. */
+  readonly platform?: Platform;
+}
+//#endregion
+//#region src/dependencies/plugin-dependencies.d.ts
+/** One plugin another plugin declares it needs. */
+interface PluginDependency {
+  readonly name: string;
+  /** The marketplace to resolve it in. Absent: the declaring plugin's own marketplace (E-DEP-1). */
+  readonly marketplace?: string;
+  /** The version the declaring plugin asked for. Reported, never compared. */
+  readonly version?: string;
+}
+/**
+ * Read the `dependencies` array of a Claude Code `plugin.json`: `"name"`, `"name@marketplace"`, or
+ * `{ name, marketplace, version }` entries (E-DEP-1, E-CC-X1). Entries of any other shape are skipped.
+ */
+export declare function declaredPluginDependencies(manifest: unknown): PluginDependency[];
+interface PluginDependenciesRead {
+  readonly dependencies: readonly PluginDependency[];
+  /** The manifest the list came from; the last one tried when none declares any. */
+  readonly path: string;
+  /** Set when the manifest exists but could not be parsed. */
+  readonly error?: string;
+}
+/**
+ * Read what the plugin at `pluginRoot` declares: `dependencies` under `extensions["io.github.cyber-uni.plugin-manager"]`,
+ * else under `extensions["org.cyberuni.universal-plugin"]` in the root `plugin.json`, else `dependencies` in
+ * `.claude-plugin/plugin.json` (E-DEP-1, E-DEP-6, E-DEP-7).
+ */
+export declare function readPluginDependencies(pluginRoot: string): Promise<PluginDependenciesRead>;
+type DependencyState = 'enabled' | 'disabled' | 'installed' | 'missing' | 'unknown';
+interface CheckedDependency extends PluginDependency {
+  readonly state: DependencyState;
+  /** The `<plugin>@<marketplace>` install the state was read from. */
+  readonly id?: string;
+}
+interface PluginDependencyCheck {
+  readonly harness: HarnessId;
+  /** Whether the harness's manifest can declare dependencies (`supportsPluginDependencies`). */
+  readonly supported: boolean;
+  /** Whether the harness installs missing dependencies by itself. Only Claude Code does (E-DEP-2). */
+  readonly autoResolved: boolean;
+  readonly dependencies: readonly CheckedDependency[];
+  /** What to do next, in order. Empty when nothing is missing or disabled. */
+  readonly steps: readonly string[];
+  /** Set when the declaring manifest could not be read. */
+  readonly error?: string;
+  readonly research: readonly string[];
+}
+interface CheckPluginDependenciesOptions extends HarnessEnvironment {
+  /** The plugin whose manifest declares the dependencies. */
+  readonly pluginRoot?: string;
+  /** Dependencies already read; used instead of `pluginRoot`. */
+  readonly dependencies?: readonly PluginDependency[];
+}
+/**
+ * Check which declared dependencies the harness has installed and enabled, and return the steps
+ * that settle the rest. Nothing is installed.
+ */
+export declare function checkPluginDependencies(harness: HarnessId, options?: CheckPluginDependenciesOptions): Promise<PluginDependencyCheck>;
+//#endregion
+//#region src/detection/detect-harness.d.ts
+/**
+ * One environment variable `detectHarness()` found set, and which harness it points to.
+ */
+interface HarnessEvidence {
+  readonly harness: HarnessId;
+  /** The environment variable name. */
+  readonly signal: string;
+  readonly description: string;
+  /** The claim ID in `.research/harness-detection/evidence.md` that backs this signal. */
+  readonly research: string;
+}
+interface HarnessDetectionResult {
+  /** The detected harness, or `unknown` when no harness or more than one harness matched. */
+  readonly harness: HarnessId | 'unknown';
+  /** Every signal that was found set, including ones that did not settle the answer. */
+  readonly evidence: readonly HarnessEvidence[];
+  /**
+   * Harnesses whose signals were found. More than one means nested harnesses (one launched from
+   * another's shell inherits its variables), which the environment cannot order, so `harness` is
+   * `unknown`.
+   */
+  readonly candidates: readonly HarnessId[];
+}
+interface DetectHarnessOptions {
+  /** The environment to inspect. Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Detect which AI agent harness this process is running under, from its environment.
+ *
+ * Reports `unknown` rather than guessing: when no rule matches, and when rules for more than one
+ * harness match.
+ */
+export declare function detectHarness(options?: DetectHarnessOptions): HarnessDetectionResult;
+//#endregion
+//#region src/headless/headless-invocation.d.ts
+/** How to run a harness on one prompt with no user present. */
+type HeadlessInvocation = HeadlessMode | HeadlessUnavailable;
+interface HeadlessMode {
+  readonly harness: HarnessId;
+  readonly supported: true;
+  /** The command to run. */
+  readonly executable: string;
+  /** The arguments that put the harness in one-shot mode, such as `['-p']` or `['exec']`. */
+  readonly oneShot: readonly string[];
+  /**
+   * The flag whose value is the prompt. When absent, the prompt is the last positional argument.
+   */
+  readonly promptFlag?: string;
+  /** The flag that selects the model. */
+  readonly modelFlag: string;
+  readonly permission: HeadlessPermission;
+  /** The output formats it can print. The first is the default. */
+  readonly outputFormats: readonly HeadlessOutputFormat[];
+  /** Where a run's transcript is kept, or `undefined` when the vendor does not say. */
+  readonly transcript?: HeadlessTranscript;
+  /** The exit codes the vendor documents. A code the list does not name means failure. */
+  readonly exitCodes: readonly HeadlessExitCode[];
+  /** The claim IDs in `.research/harness-detection/evidence.md` that back these facts. */
+  readonly research: readonly string[];
+}
+interface HeadlessUnavailable {
+  readonly harness: HarnessId;
+  /** `false` when the harness has no headless mode; `'unknown'` when its facts are not verified. */
+  readonly supported: false | 'unknown';
+  readonly reason: string;
+  readonly research: readonly string[];
+}
+interface HeadlessPermission {
+  /** The flag that takes a permission or approval mode, when there is one. */
+  readonly flag?: string;
+  /** The values `flag` accepts. */
+  readonly values: readonly string[];
+  /** The arguments that let a run edit files and run commands without asking anyone. */
+  readonly unattended: readonly string[];
+}
+interface HeadlessOutputFormat {
+  /** The harness's own name for the format. */
+  readonly name: string;
+  /** The arguments that select it; empty for the default. */
+  readonly args: readonly string[];
+  /** Where token usage and cost appear, or `undefined` when the vendor does not document it. */
+  readonly usage?: HeadlessUsage;
+}
+interface HeadlessUsage {
+  /** The `type` of the event or message that carries usage; absent when the output is one object. */
+  readonly event?: string;
+  /** The field that holds token counts, as a dotted path. */
+  readonly tokens: string;
+  /** The field that holds the cost in US dollars, when the harness reports one. */
+  readonly costUsd?: string;
+  /** `last`: the final event holds the run's total. `sum`: add the field across every such event. */
+  readonly accumulate: 'last' | 'sum';
+}
+interface HeadlessTranscript {
+  /** The path, with `~` for the home directory and `<placeholders>` for the varying parts. */
+  readonly path: string;
+  /** The environment variable that moves the base directory the path starts from. */
+  readonly baseDirEnv?: string;
+  /** The arguments that keep a run from writing a transcript at all. */
+  readonly disable?: readonly string[];
+}
+interface HeadlessExitCode {
+  readonly code: number;
+  readonly meaning: string;
+}
+/**
+ * How to run a harness non-interactively on one prompt: the command, how to choose the model and
+ * permission mode, the output formats and where usage appears in them, the transcript location,
+ * and the exit codes.
+ *
+ * Returns `supported: false` for Copilot in VS Code, which documents no headless mode (E-VSC-H1).
+ * Returns `supported: 'unknown'` for OpenCode, Kilo Code, Cline, Crush, OpenHands, and the Auggie
+ * CLI: each has a one-shot mode, but the research read it only through a summarizing fetch or from
+ * source (E-OC-H1, E-KILO-H1, E-CLINE-H1, E-CRUSH-H1, E-OH-H1, E-AUG-H1).
+ */
+export declare function headlessInvocation(harness: HarnessId): HeadlessInvocation;
+interface HeadlessCommandOptions {
+  readonly prompt: string;
+  readonly model?: string;
+  /** A value for the permission flag, or `'unattended'` for a run nobody watches. */
+  readonly permission?: string;
+  /** The name of one of the harness's output formats. */
+  readonly outputFormat?: string;
+}
+interface HeadlessCommand {
+  readonly executable: string;
+  readonly args: readonly string[];
+}
+/**
+ * The command line for one headless run, built from `headlessInvocation()`. It does not run it.
+ *
+ * Returns `undefined` when the harness's headless mode is not supported or not verified. Throws
+ * when `outputFormat` names a format the harness lacks, or `permission` names a mode the harness
+ * has no flag for.
+ */
+export declare function headlessCommand(harness: HarnessId, options: HeadlessCommandOptions): HeadlessCommand | undefined;
+//#endregion
+//#region src/managed-policy/managed-policy-locations.d.ts
+/**
+ * Where a piece of managed (organization-enforced) policy lives.
+ *
+ * - `file` / `directory`: on the local disk; a caller can read it.
+ * - `macos-managed-preferences`: a macOS managed-preferences domain delivered by MDM.
+ * - `windows-registry`: a Windows registry key delivered by MDM or Group Policy.
+ * - `server`: held by the vendor or the organization and fetched at runtime; not readable locally.
+ */
+type ManagedPolicyKind = 'file' | 'directory' | 'macos-managed-preferences' | 'windows-registry' | 'server';
+interface ManagedPolicyLocation {
+  readonly kind: ManagedPolicyKind;
+  /** A path, preference domain, registry key, or, for `server`, a description of where it is held. */
+  readonly location: string;
+  readonly description: string;
+  /** The claim ID in `.research/harness-detection/evidence.md` that backs this location. */
+  readonly research: string;
+}
+interface ManagedPolicyOptions {
+  /** Defaults to `process.platform`. */
+  readonly platform?: Platform;
+  /** Used for `%ProgramFiles%` / `%ProgramData%` on Windows. Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * List where a harness keeps managed policy on the given platform, most authoritative first where
+ * the vendor documents an order. Server-side locations are included so a caller knows the local
+ * files are not the whole picture.
+ */
+export declare function managedPolicyLocations(harness: HarnessId, options?: ManagedPolicyOptions): readonly ManagedPolicyLocation[];
+//#endregion
+//#region src/plugins/enabled-plugins.d.ts
+/** The settings scope a plugin's enabled state came from. */
+type PluginScope = 'managed' | 'local' | 'project' | 'user';
+interface PluginEnablement {
+  /** The key the harness uses, `<plugin>@<marketplace>`. */
+  readonly id: string;
+  readonly enabled: boolean;
+  /** The scope whose value won. */
+  readonly scope: PluginScope;
+  /** The file the winning value was read from. */
+  readonly source: string;
+}
+interface EnabledPluginSource {
+  readonly scope: PluginScope;
+  readonly path: string;
+  /** `false` when the file does not exist. */
+  readonly found: boolean;
+  /** Set when the file exists but could not be parsed; its entries are then ignored. */
+  readonly error?: string;
+}
+interface EnabledPluginsResult {
+  readonly harness: HarnessId;
+  /** `false` when the harness keeps no readable record of enabled plugins. */
+  readonly supported: boolean;
+  /** Each plugin with an explicit entry, resolved across scopes. */
+  readonly plugins: readonly PluginEnablement[];
+  /** The files consulted, highest precedence first. */
+  readonly sources: readonly EnabledPluginSource[];
+  /**
+   * Sources that can also decide a plugin's state but that this package does not read, such as
+   * MDM or server-managed policy. When non-empty, `plugins` may not be the whole answer.
+   */
+  readonly unread: readonly string[];
+  /** The claim IDs in `.research/harness-detection/evidence.md` behind the resolution. */
+  readonly research: readonly string[];
+}
+interface EnabledPluginsOptions extends HarnessEnvironment {
+  /**
+   * Read the managed settings file from here instead of the harness's documented location.
+   * Useful when policy is staged elsewhere, and in tests.
+   */
+  readonly managedSettingsPath?: string;
+}
+/**
+ * Read which plugins a harness has enabled, from the settings files it keeps on disk.
+ *
+ * Only plugins with an explicit entry are reported; a plugin with no entry falls back to a
+ * harness- or plugin-defined default this package does not know. See `unread` for policy sources
+ * that may override what the files say.
+ */
+export declare function enabledPlugins(harness: HarnessId, options?: EnabledPluginsOptions): Promise<EnabledPluginsResult>;
+//#endregion
+//#region src/plugins/installed-plugins.d.ts
+interface InstalledPlugin {
+  /**
+   * `<plugin>@<marketplace>`, the key `enabledPlugins()` reports. A Copilot CLI direct install
+   * has no marketplace, so its id is the bare plugin name (E-COPILOT-P11).
+   */
+  readonly id: string;
+  /** The absolute folder the harness loads the plugin from. */
+  readonly path: string;
+  readonly version?: string;
+  /** The install scope, for harnesses that record one. */
+  readonly scope?: PluginScope;
+  /** The project a project- or local-scoped install belongs to. */
+  readonly projectPath?: string;
+  /** The claim IDs in `.research/harness-detection/evidence.md` behind this entry. */
+  readonly research: readonly string[];
+}
+interface InstalledPluginSource {
+  readonly path: string;
+  /** `false` when the file or folder does not exist. */
+  readonly found: boolean;
+  /** Set when it exists but could not be read; nothing is reported from it. */
+  readonly error?: string;
+}
+interface InstalledPluginsResult {
+  readonly harness: HarnessId;
+  /** `false` when this package has no verified install record for the harness. */
+  readonly supported: boolean;
+  /** One entry per install. Claude Code can install one plugin at several scopes. */
+  readonly plugins: readonly InstalledPlugin[];
+  /** The ids of installed plugins whose folder cannot be determined without guessing. */
+  readonly unresolved: readonly string[];
+  /** The files or folders consulted. */
+  readonly sources: readonly InstalledPluginSource[];
+  /** Installs the harness can load that this package does not read. */
+  readonly unread: readonly string[];
+  /** The claim IDs in `.research/harness-detection/evidence.md` behind the resolution. */
+  readonly research: readonly string[];
+}
+/**
+ * Map each plugin a harness has installed to the folder it is loaded from. Join the result with
+ * `enabledPlugins()` by `id` to find an enabled plugin's folder.
+ */
+export declare function installedPlugins(harness: HarnessId, environment?: HarnessEnvironment): Promise<InstalledPluginsResult>;
+//#endregion
+//#region src/plugins/package-dependencies.d.ts
+/**
+ * Includes `devDependencies` — a plugin can supply a project's testing or release workflow.
+ * Transitive dependencies are excluded: only what the manifest declares.
+ */
+export declare function declaredDependencies(manifest: unknown): string[];
+/**
+ * Anchored at the declaring manifest (required for pnpm's isolation), then falls back to a
+ * `node_modules` walk — an `exports` map without a `./package.json` entry blocks the first.
+ */
+export declare function packageDir(pkg: string, fromManifest: string): string | undefined;
+//#endregion
+//#region src/plugins/plugin-dependencies.d.ts
+/**
+ * Whether a harness lets a plugin declare other plugins it depends on. Only Claude Code does, via
+ * `dependencies` in `plugin.json` (E-CC-X1). The other harnesses' manifests have no such field
+ * (E-CUR-X1, E-CODEX-X1, E-COPILOT-X1, E-OC-X1, E-KILO-X1, E-GEM-P4, E-QWEN-P3, E-VSC-X1,
+ * E-CLINE-X1, E-CRUSH-X1, E-OH-X1, E-AUG-X1).
+ */
+export declare function supportsPluginDependencies(harness: HarnessId): boolean;
+//#endregion
+//#region src/plugins/plugin-manifest.d.ts
+/**
+ * Where a plugin keeps its manifest, relative to its root: the Agent Plugins `plugin.json` at the
+ * root (E-VSC-P2, E-COPILOT-P8), then each harness's own folder (E-CODEX-P4, E-CUR-P4, E-COPILOT-P8).
+ */
+export declare const pluginManifestPaths: readonly string[];
+/**
+ * The `name` in the first plugin manifest a folder holds, or `undefined` when it holds none: then
+ * the folder is not a plugin, whatever its `package.json` says.
+ */
+export declare function pluginManifestName(root: string): string | undefined;
+//#endregion
+//#region src/plugins/plugin-storage.d.ts
+/**
+ * - `plugin-cache`: installed plugin copies, one folder per marketplace, plugin, and version.
+ * - `installed-plugins`: installed plugin folders not split by version.
+ * - `local-plugins`: a folder the harness scans for plugins under development.
+ * - `marketplaces`: marketplace checkouts.
+ * - `install-record`: the file that records which plugins are installed.
+ * - `enabled-record`: the user-level file that records which plugins are enabled.
+ */
+type PluginStorageKind = 'plugin-cache' | 'installed-plugins' | 'local-plugins' | 'marketplaces' | 'install-record' | 'enabled-record';
+interface PluginStorageLocation {
+  readonly kind: PluginStorageKind;
+  readonly path: string;
+  readonly description: string;
+  /** The claim ID in `.research/harness-detection/evidence.md` that backs this location. */
+  readonly research: string;
+}
+interface PluginStorage {
+  readonly harness: HarnessId;
+  /** The harness's user-level config directory, after any override environment variable. */
+  readonly configDir: string;
+  readonly locations: readonly PluginStorageLocation[];
+}
+/**
+ * Where a harness keeps plugins at the user level. Paths are computed, not checked: a location may
+ * not exist until the first plugin is installed.
+ */
+export declare function pluginStorage(harness: HarnessId, environment?: HarnessEnvironment): PluginStorage;
+//#endregion
+//#region src/references/load-reference.d.ts
+/** `referenceLayers`' options, with the machine's own home directory, platform, and environment by default. */
+type LoadReferenceOptions = Omit<ReferenceLayerOptions, 'home' | 'platform'> & {
+  home?: string | undefined;
+  platform?: Platform | undefined;
+};
+/**
+ * Resolves one reference for `root` the way `reference show` does, returning the full record: every
+ * field `show` prints with `--metadata` and `--trace`. A name that is not a reference name comes back
+ * `invalid`, and one no contribution answers `missing`; neither throws.
+ */
+export declare function loadReference(name: string, options: LoadReferenceOptions): Promise<ResolvedReference>;
+//#endregion
+//#region src/references/reference-catalog.d.ts
+/** One row per name. */
+type ReferenceListRow = {
+  name: string;
+  description: string;
+  status: ReferenceStatus;
+  /** When `ambiguous`: each `<plugin>/<name>`, and each skill's default as `default of <skill>`. */
+  options?: string[];
+};
+/** One row per name per layer holding it, with the outcome that contribution gets. */
+type ReferenceListLayerRow = {
+  name: string;
+  tier: ReferenceTier;
+  plugin?: string;
+  skill?: string;
+  path: string;
+  description: string;
+  outcome: string;
+  /** A contribution with `extends` and no body. */
+  selection?: boolean;
+  /** A skill's default: the `default` step reaches it when this skill loads the name. */
+  reachedBy?: string;
+};
+type ReferenceListing = {
+  references: ReferenceListRow[];
+  layers: ReferenceListLayerRow[];
+  /** Why some skills' defaults are not listed: no harness detected, or one whose skill folders are not verified. */
+  defaults?: string;
+  warnings: ReferenceWarning[];
+};
+type ListOptions = ResolveOptions & {
+  /** Keep only names matching this pattern: `*` stands for any run of characters, everything else is literal and case-sensitive. */
+  pattern?: string | undefined;
+};
+type Source$2 = ReferenceLayers | readonly ReferenceLayer[];
+/**
+ * One row per name, with its description and, when not `found`, its status and options; and one row
+ * per name per layer holding it, and per installed skill holding a default of it. A name only skills'
+ * defaults hold resolves as the first such skill loads it. A `pattern` keeps only the names it matches exactly.
+ */
+export declare function listReferences(source: Source$2, options?: ListOptions): ReferenceListing;
+type MatchKind = 'name' | 'prefix' | 'close name' | 'description' | 'heading' | 'body';
+type SearchMatch = {
+  name: string;
+  description: string;
+  match: MatchKind;
+  /** The tier of the highest contribution whose text the document holds. */
+  tier: ReferenceTier;
+  plugin?: string;
+  skill?: string;
+  /** A match found as this skill loads the name, its default joined. */
+  loadedBy?: string;
+};
+type ReferenceSearch = {
+  matches: SearchMatch[];
+  /** Why some skills' defaults are not searched: no harness detected, or one whose skill folders are not verified. */
+  defaults?: string;
+};
+/**
+ * Every name resolves the way `show` would, and each skill's default as its skill loads it; a name
+ * no extends orders is searched once per plugin, as the qualified name `show` would need, and a name
+ * a `remove` turned off is left out.
+ */
+export declare function searchReferences(query: string, source: Source$2, options?: ResolveOptions): ReferenceSearch;
+//#endregion
+//#region src/references/reference-interface.d.ts
+/** `one`: the implementation is named `<id>`. `many`: each is named `<id>.<key>`. */
+type InterfaceCardinality = 'one' | 'many';
+/** The machine-readable part of an interface document, read from its `interface:` frontmatter. */
+type ReferenceInterface = {
+  id: string;
+  cardinality: InterfaceCardinality;
+  version: number;
+  /** The versions the owner's consumers accept; `[version]` when the document names none. */
+  versions: number[];
+  /** The implementation's top-level sections, in order. Every one is optional. Heading text is API. */
+  sections: string[];
+};
+/** One `implements:` value, `<id>@<version>`. */
+type ImplementsEntry = {
+  id: string;
+  version: number;
+};
+type InterfaceCheck = 'interface found' | 'version' | 'name' | 'order' | 'interface' | 'compose';
+type InterfaceCheckFailure = {
+  check: InterfaceCheck;
+  /** The interface id the failure is about, when the document names one. */
+  interface?: string;
+  message: string;
+};
+//#endregion
+//#region src/references/reference-check.d.ts
+type ReferenceCheckKind = 'interface' | 'implementation' | 'none';
+/** A failed check, named by the check; a name not `found` fails with its status code. */
+type ReferenceCheckFailure = {
+  check: InterfaceCheck | ReferenceCode;
+  /** The interface id the failure is about, when the document names one. */
+  interface?: string;
+  message: string;
+};
+type ReferenceCheckEntry = {
+  name: string;
+  kind: ReferenceCheckKind;
+  /** `passed` and `failed` are about the composed document; the others mean none was composed. */
+  status: 'passed' | 'failed' | 'missing' | 'ambiguous' | 'invalid';
+  failures: ReferenceCheckFailure[];
+  /** For an implementation: the listed sections it marks `**Unsupported.**` or leaves out. */
+  unsupported: string[];
+  /** Checked as this skill loads the name, its default joined. */
+  loadedBy?: string;
+};
+type CheckOptions = ResolveOptions & {
+  /** The references to check; every interface document and implementation found when omitted. */
+  names?: readonly string[] | undefined;
+};
+type Source$1 = ReferenceLayers | readonly ReferenceLayer[];
+/**
+ * Checks each named reference, or, with no names, every interface document and implementation found.
+ * A name several plugins hold is also checked as each `<plugin>/<name>`, so each author sees their own
+ * result, and each skill's default as its skill loads it.
+ */
+export declare function checkReferences(source: Source$1, options?: CheckOptions): ReferenceCheckEntry[];
+//#endregion
+//#region src/references/reference-implementations.d.ts
+type ReferenceImplementation = {
+  /** What a consumer loads: the name as it resolved, `<plugin>/<name>` when no extends orders the plugins holding it. */
+  pin: string;
+  description: string;
+  /** The listed sections it marks `**Unsupported.**` or leaves out, in the interface's order. */
+  unsupported: string[];
+  name: string;
+  /** The tier of the highest contribution whose text it holds. */
+  tier: ReferenceTier;
+  version: number;
+};
+type ExcludedImplementation = {
+  name: string;
+  reasons: string[];
+};
+type ReferenceImplementations = {
+  interface: string;
+  cardinality: InterfaceCardinality;
+  /** The versions an implementation must declare to be listed. */
+  accept: number[];
+  implementations: ReferenceImplementation[];
+  excluded: ExcludedImplementation[];
+  warnings: ReferenceWarning[];
+};
+type ImplementationsOptions = ResolveOptions & {
+  /** The versions the consumer knows; the interface's own `versions` when omitted. */
+  accept?: readonly number[] | undefined;
+};
+type Source = ReferenceLayers | readonly ReferenceLayer[];
+/**
+ * The implementations of interface `id` a consumer may load, each checked as `check` would on its
+ * composed document, and every candidate left out with why. A candidate is a name in the interface's
+ * namespace (`<id>` or `<id>.<key>`) or a reference that declares `implements: <id>@<n>`. A skill's
+ * default is never listed: it has no qualified name to pin. An unknown interface throws.
+ */
+export declare function referenceImplementations(id: string, source: Source, options?: ImplementationsOptions): ReferenceImplementations;
+//#endregion
+//#region src/references/reference-where.d.ts
+/** A file a customization or a selection of the name is written to. */
+type ReferenceWherePlace = {
+  scope: 'project' | 'user';
+  /** The project path is relative to the root; the user path is shown as the command displays it. */
+  path: string;
+  reaches: string;
+  /** `used`, `shadowed by ...`, or `not used (...)` when the file exists; `empty` when it does not. */
+  status: string;
+  /** The heading paths of the document below it, which a section operation can target. */
+  sections: string[];
+};
+type ReferenceWhereReport = {
+  name: string;
+  status: ReferenceStatus;
+  places: ReferenceWherePlace[];
+  /** When `ambiguous`: the options a selection written to a place chooses between. */
+  options?: string[];
+  /** Every layer checked, highest first; a plugin's or a default contribution is read-only. */
+  layers: ReferenceTraceLayer[];
+  warnings: ReferenceWarning[];
+};
+type WhereOptions = {
+  /** Absolute; a project write goes to its `.agents/references/`, and a project path is shown relative to it. */
+  root: string;
+  /** How a path outside the project is shown, such as with the home directory collapsed to `~`. */
+  display?: ((path: string) => string) | undefined;
+};
+/** The project and user files a customization of `name` is written to, with the document below each. */
+export declare function whereReference(input: string | ReferenceName, source: ReferenceLayers | readonly ReferenceLayer[], { root, display }: WhereOptions): ReferenceWhereReport;
+//#endregion
+//#region src/skills/harness-skill-folders.d.ts
+/**
+ * The harnesses whose skill folders are verified: project, user, machine-wide admin, and plugin
+ * skills (`.research/skill-resolution`, `.research/machine-wide-content`). Any other harness reads
+ * folders this library does not know, so its skills' defaults are not listed.
+ */
+export declare const skillFoldersVerified: readonly HarnessId[];
+type Env = Readonly<Record<string, string | undefined>>;
+type SkillFolderOptions = {
+  /** The project folders, nearest first, up to the repository root. */
+  chain: readonly string[];
+  home: string;
+  platform: Platform;
+  env?: Env | undefined;
+};
+/**
+ * The machine-wide admin skill folders: Claude Code's enterprise `<managed dir>/.claude/skills`
+ * (E-MW-CC-2), Codex's ADMIN scope `/etc/codex/skills` (E-MW-CODEX-1; its Windows folder is
+ * inferred, so it is left out), and OpenCode's `skill` and `skills` under its system folder
+ * (E-MW-OC-1, E-MW-OC-2).
+ */
+export declare function adminSkillFolders(harness: HarnessId, platform: Platform, env?: Env): string[];
+/**
+ * The project, user, and admin folders a harness reads skills from, each holding skill folders one
+ * level down; `undefined` when the harness's skill folders are not verified.
+ */
+export declare function harnessSkillFolders(harness: HarnessId, { chain, home, platform, env }: SkillFolderOptions): string[] | undefined;
+/**
+ * The folders a plugin's skills sit in: `skills/` under its root, and what a manifest `skills` field
+ * lists, which adds to `skills/` in Claude Code (E-SR-CC-1) and replaces it in Cursor, Codex, and
+ * Copilot CLI (E-SR-CUR-2, E-SR-CODEX-2, E-SR-COPILOT-2). Gemini CLI has no such field (E-SR-GEM-1),
+ * and OpenCode plugins ship no skills (E-SR-OC-3). A root holding `SKILL.md` is itself a skill
+ * (E-SR-CC-1, E-SR-CUR-1); the caller checks the root.
+ */
+export declare function pluginSkillFolders(harness: HarnessId, root: string): string[];
+//#endregion
+//#region src/skills/skill-invocation.d.ts
+interface PluginSkill {
+  /** The plugin's `name`. */
+  readonly plugin: string;
+  /** The skill's frontmatter `name`, which every harness uses as the skill segment. */
+  readonly skill: string;
+}
+interface SkillInvocation {
+  /** What a user types to invoke the skill: a slash command, or for Codex a `$` mention. */
+  readonly text: string;
+  /** Whether the text names the plugin, so same-named skills from two plugins stay distinct. */
+  readonly namespaced: boolean;
+  /**
+   * The claim ID that backs this form, in `.research/harness-detection/evidence.md`, or in
+   * `.research/skill-resolution/evidence.md` for an `E-SR-` ID.
+   */
+  readonly research: string;
+}
+/**
+ * How a user invokes a plugin's skill in a harness.
+ *
+ * Claude Code, Codex, and Copilot in VS Code namespace by plugin; elsewhere two plugins' skills with
+ * the same name collide. Codex names a plugin skill `<plugin>:<skill>`, and its `$` mention takes the
+ * whole name (E-SR-CODEX-5, E-SR-CODEX-18). Copilot CLI lists `<plugin>:<skill>` only while two
+ * enabled plugins share the name (E-SR-COPILOT-8); whether that form can be typed is not verified,
+ * so it returns the bare `/<skill>`.
+ *
+ * Kilo Code returns `/<skill>` in both the CLI and the VS Code extension; when a custom command or
+ * MCP prompt has the same name, the skill is typed `/<skill>:skill` instead (E-KILO-S3).
+ *
+ * OpenCode returns `/<skill>` too, but when a built-in (`init`, `review`), config command, or MCP
+ * prompt has the same name, that one wins and the skill has no command (E-OC-S3).
+ *
+ * Returns `undefined` for Gemini CLI, Qwen Code, and Crush, which document no typed form: the model
+ * loads a skill through a tool call when its description matches the task (E-GEM-S2, E-QWEN-S1,
+ * E-CRUSH-S1). Crush can also list a skill in its command
+ * palette, which is picked, not typed (E-CRUSH-S2). OpenHands triggers skills from the model too;
+ * only a plugin's commands take a `/<plugin>:<command>` form (E-OH-S2, E-OH-S3).
+ *
+ * Also returns `undefined` for the Auggie CLI: a plugin skill's internal name is `<plugin>:<skill>`,
+ * but what the user types for it is not confirmed (E-AUG-S3).
+ */
+export declare function skillInvocation(harness: HarnessId, { plugin, skill }: PluginSkill): SkillInvocation | undefined;
+//#endregion
+//#region src/skills/skills-directories.d.ts
+interface SkillsDirectories {
+  /** Directories relative to the project root, in the order the source lists them. */
+  readonly project: readonly string[];
+  /** Directories relative to the home directory, in the order the source lists them. */
+  readonly user: readonly string[];
+  /**
+   * The claim IDs that back these directories, in `.research/harness-detection/evidence.md`, or in
+   * `.research/skill-resolution/evidence.md` for an `E-SR-` ID.
+   */
+  readonly research: readonly string[];
+  /**
+   * Set when an environment variable moves the user directories: when it names a folder other than
+   * the default, `user` is not read, and `<that folder>/<skills>` is read instead.
+   */
+  readonly relocatedBy?: {
+    readonly variable: string;
+    readonly skills: string;
+  };
+}
+/**
+ * The directories a harness reads skills from, as its vendor documents them.
+ *
+ * Lists project and user directories read by default. Admin, bundled, and plugin skills are left
+ * out. Copilot CLI reads its user directories only while `COPILOT_HOME` is the default `~/.copilot`;
+ * set elsewhere, it reads `$COPILOT_HOME/skills` instead (`relocatedBy`, E-SR-COPILOT-9). Cline's `.agents/skills` rests on its source, which its docs do not yet name (E-CLINE-S3).
+ *
+ * Returns `undefined` where the directories are not confirmed: Qwen Code, whose source names the
+ * `.agents` root but not the directory under it (E-QWEN-S1); and Crush and OpenHands, where no
+ * directory is recorded.
+ */
+export declare function skillsDirectories(harness: HarnessId): SkillsDirectories | undefined;
+//#endregion
+export { type AmbiguousCause, type CheckOptions, type CheckPluginDependenciesOptions, type CheckedDependency, type DependencyState, type DetectHarnessOptions, type EnabledPluginSource, type EnabledPluginsOptions, type EnabledPluginsResult, type ExcludedImplementation, type ExtendsStep, type FoundSkill, type HarnessDetectionResult, type HarnessEnvironment, type HarnessEvidence, type HarnessId, type HeadlessCommand, type HeadlessCommandOptions, type HeadlessExitCode, type HeadlessInvocation, type HeadlessMode, type HeadlessOutputFormat, type HeadlessPermission, type HeadlessTranscript, type HeadlessUnavailable, type HeadlessUsage, type ImplementationsOptions, type ImplementsEntry, type InstalledPlugin, type InstalledPluginSource, type InstalledPluginsResult, type InterfaceCardinality, type InterfaceCheck, type InterfaceCheckFailure, type ListOptions, type LoadReferenceOptions, type ManagedPolicyKind, type ManagedPolicyLocation, type ManagedPolicyOptions, type MatchKind, type MergeOperation, type OperationSource, type Platform, type PluginDependenciesRead, type PluginDependency, type PluginDependencyCheck, type PluginEnablement, type PluginScope, type PluginSkill, type PluginStorage, type PluginStorageKind, type PluginStorageLocation, type ReferenceCheckEntry, type ReferenceCheckFailure, type ReferenceCheckKind, type ReferenceCode, type ReferenceImplementation, type ReferenceImplementations, type ReferenceInterface, type ReferenceLayer, type ReferenceLayerOptions, type ReferenceLayers, type ReferenceListLayerRow, type ReferenceListRow, type ReferenceListing, type ReferenceName, type ReferencePlugin, type ReferenceSearch, type ReferenceStatus, type ReferenceTier, type ReferenceTrace, type ReferenceTraceContribution, type ReferenceTraceLayer, type ReferenceTraceSection, type ReferenceWarning, type ReferenceWarningCode, type ReferenceWherePlace, type ReferenceWhereReport, type ResolveOptions, type ResolvedReference, type SearchMatch, type SectionSource, type SkillDefaults, type SkillFolderOptions, type SkillInvocation, type SkillsDirectories, type WhereOptions, defaultLayer, harnessIds, parseReferenceName, projectReferencesDir, referenceLayers, referenceNames, resolveReference, skillName, skillsIn, userReferencesDir };