@h-rig/core 0.0.6-alpha.155 → 0.0.6-alpha.156

package/dist/src/plugin-host.d.ts

@@ -1,5 +1,5 @@
-import type { BlockerClassifierRegistration, CliCommandRegistration, HookRegistration, PanelRegistration, ProductCapabilityRegistration, RepoSourceRegistration, AgentRoleRegistration, SkillRegistration, Stage, StageMutation, StageRun, TaskFieldExtension, TaskSourceRegistration, ValidatorRegistration } from "@rig/contracts";
-import type { RegisteredValidator, RigPluginWithRuntime, RuntimeBlockerClassifier, RuntimeCliCommand, RuntimeFeatureCapability, RuntimePanelProducer, TaskSourceFactoryEntry } from "./plugin-runtime";
+import type { AgentRoleRegistration, BlockerClassifierRegistration, CliCommandRegistration, HookRegistration, PanelRegistration, ProductCapabilityRegistration, RepoSourceRegistration, SkillRegistration, Stage, StageMutation, StageRun, TaskFieldExtension, TaskSourceRegistration, ValidatorRegistration } from "@rig/contracts";
+import type { BlockerClassifierEntry, CliCommand, FeatureCapability, Panel, RigPlugin, SessionExtensionEntry, TaskSource, Validator } from "./plugin-runtime";
 export interface PluginHost {
     getValidator(id: string): ValidatorRegistration | undefined;
     getHook(id: string): HookRegistration | undefined;
@@ -32,34 +32,41 @@ export interface PluginHost {
      */
     listStageMutations(): readonly StageMutation[];
     /**
-     * Executable stage implementations contributed by plugins (`runtime.stages`),
-     * merged by stage id. The kernel's stage runner uses these to execute
-     * plugin-contributed stages inserted via stageMutations.
+     * Executable stage implementations contributed by plugins, derived from
+     * `contributes.stages` entries that carry a `run`, keyed by stage id. The
+     * kernel's stage runner uses these to execute plugin-contributed stages
+     * inserted via stageMutations.
      */
     listStageExecutors(): Readonly<Record<string, StageRun>>;
     /**
-     * Executable validators contributed by plugins. Only validators whose
-     * metadata appears in `listValidators()` and whose plugin shipped a runtime
-     * implementation via `definePlugin(meta, { validators: [...] })` appear here.
-     * Validators registered metadata-only (no run() implementation) are absent.
+     * Executable validators contributed by plugins (single-channel: the same
+     * `contributes.validators` entries, which carry their `run`).
      */
-    listExecutableValidators(): readonly RegisteredValidator[];
+    listExecutableValidators(): readonly Validator[];
     /**
      * Executable task source factories contributed by plugins. Used by the
      * runtime's `buildTaskSourceRegistry` to instantiate non-standard task
      * source kinds (Linear, Jira, custom) declared by plugins.
      */
-    listExecutableTaskSources(): readonly TaskSourceFactoryEntry[];
-    listExecutableCapabilities(): readonly RuntimeFeatureCapability[];
-    listExecutablePanels(): readonly RuntimePanelProducer[];
-    listExecutableBlockerClassifiers(): readonly RuntimeBlockerClassifier[];
-    listExecutableCliCommands(): readonly RuntimeCliCommand[];
-    resolveExecutableCliCommand(requested: string): RuntimeCliCommand | undefined;
+    listExecutableTaskSources(): readonly TaskSource[];
+    listExecutableCapabilities(): readonly FeatureCapability[];
+    listExecutablePanels(): readonly Panel[];
+    listExecutableBlockerClassifiers(): readonly BlockerClassifierEntry[];
+    listExecutableCliCommands(): readonly CliCommand[];
+    /**
+     * Executable session-extension installers contributed by plugins. The
+     * agent-session host (rig-host) resolves these and invokes each `install(api)`
+     * at `createAgentSession` time, so the run lifecycle (and any other
+     * session-time extension) is resolved from the explicit plugin collection
+     * rather than injected directly by a leaf.
+     */
+    listSessionExtensions(): readonly SessionExtensionEntry[];
+    resolveExecutableCliCommand(requested: string): CliCommand | undefined;
     /**
      * Look up an executable task source factory by its `kind` (the value in
      * `config.taskSource.kind`). Returns undefined when no plugin provides
      * a factory for that kind.
      */
-    resolveTaskSourceFactoryByKind(kind: string): TaskSourceFactoryEntry | undefined;
+    resolveTaskSourceFactoryByKind(kind: string): TaskSource | undefined;
 }
-export declare function createPluginHost(plugins: readonly RigPluginWithRuntime[]): PluginHost;
+export declare function createPluginHost(plugins: readonly RigPlugin[]): PluginHost;

package/dist/src/plugin-host.js

@@ -21,102 +21,8 @@ function assertUniquePluginNames(plugins) {
     seen.add(plugin.name);
   }
 }
-function assertRuntimeMatchesMetadata(plugin) {
-  const declaredValidators = new Map((plugin.contributes?.validators ?? []).map((validator) => [validator.id, validator]));
-  const runtimeValidators = new Map((plugin?.validators ?? []).map((validator) => [validator.id, validator]));
-  for (const validator of runtimeValidators.values()) {
-    const metadata = declaredValidators.get(validator.id);
-    if (!metadata) {
-      throw new Error(`plugin "${plugin.name}" executable validator "${validator.id}" has no matching metadata entry in contributes.validators`);
-    }
-    if (metadata.category !== validator.category) {
-      throw new Error(`plugin "${plugin.name}" executable validator "${validator.id}" category "${validator.category}" does not match metadata category "${metadata.category}"`);
-    }
-  }
-  if (plugin?.validators) {
-    for (const validator of declaredValidators.values()) {
-      if (!runtimeValidators.has(validator.id)) {
-        throw new Error(`plugin "${plugin.name}" validator metadata "${validator.id}" has no runtime implementation`);
-      }
-    }
-  }
-  const declaredTaskSources = new Map((plugin.contributes?.taskSources ?? []).map((source) => [source.id, source]));
-  const runtimeTaskSources = new Map((plugin?.taskSources ?? []).map((source) => [source.id, source]));
-  for (const source of runtimeTaskSources.values()) {
-    const metadata = declaredTaskSources.get(source.id);
-    if (!metadata) {
-      throw new Error(`plugin "${plugin.name}" executable task source "${source.id}" has no matching metadata entry in contributes.taskSources`);
-    }
-    if (metadata.kind !== source.kind) {
-      throw new Error(`plugin "${plugin.name}" executable task source "${source.id}" kind "${source.kind}" does not match metadata kind "${metadata.kind}"`);
-    }
-  }
-  if (plugin?.taskSources) {
-    for (const source of declaredTaskSources.values()) {
-      if (!runtimeTaskSources.has(source.id)) {
-        throw new Error(`plugin "${plugin.name}" task source metadata "${source.id}" has no runtime implementation`);
-      }
-    }
-  }
-  const declaredHooks = new Map((plugin.contributes?.hooks ?? []).map((hook) => [hook.id, hook]));
-  const runtimeHooks = plugin?.hooks;
-  for (const hookId of Object.keys(runtimeHooks ?? {})) {
-    const metadata = declaredHooks.get(hookId);
-    if (!metadata) {
-      throw new Error(`plugin "${plugin.name}" typed hook "${hookId}" has no matching metadata entry in contributes.hooks`);
-    }
-    if (metadata.command) {
-      throw new Error(`plugin "${plugin.name}" hook "${hookId}" has both a typed implementation and a command string \u2014 pick one`);
-    }
-  }
-  if (runtimeHooks) {
-    for (const hook of declaredHooks.values()) {
-      if (!runtimeHooks[hook.id] && !hook.command) {
-        throw new Error(`plugin "${plugin.name}" hook metadata "${hook.id}" has no implementation (typed function or command)`);
-      }
-    }
-  }
-  const declaredCapabilities = new Map((plugin.contributes?.capabilities ?? []).map((capability) => [capability.id, capability]));
-  const runtimeCapabilities = new Map((plugin?.featureCapabilities ?? []).map((capability) => [capability.id, capability]));
-  for (const capability of runtimeCapabilities.values()) {
-    if (!declaredCapabilities.has(capability.id)) {
-      throw new Error(`plugin "${plugin.name}" executable capability "${capability.id}" has no matching metadata entry in contributes.capabilities`);
-    }
-  }
-  const declaredPanels = new Map((plugin.contributes?.panels ?? []).map((panel) => [panel.id, panel]));
-  const runtimePanels = new Map((plugin?.panels ?? []).map((panel) => [panel.id, panel]));
-  for (const panel of runtimePanels.values()) {
-    const metadata = declaredPanels.get(panel.id);
-    if (!metadata) {
-      throw new Error(`plugin "${plugin.name}" executable panel "${panel.id}" has no matching metadata entry in contributes.panels`);
-    }
-    if (metadata.slot !== panel.slot) {
-      throw new Error(`plugin "${plugin.name}" executable panel "${panel.id}" slot "${panel.slot}" does not match metadata slot "${metadata.slot}"`);
-    }
-    if (metadata.capabilityId !== panel.capabilityId) {
-      throw new Error(`plugin "${plugin.name}" executable panel "${panel.id}" capabilityId "${panel.capabilityId ?? "(none)"}" does not match metadata capabilityId "${metadata.capabilityId ?? "(none)"}"`);
-    }
-  }
-  const declaredBlockerClassifiers = new Map((plugin.contributes?.blockerClassifiers ?? []).map((classifier) => [classifier.id, classifier]));
-  const runtimeBlockerClassifiers = new Map((plugin?.blockerClassifiers ?? []).map((classifier) => [classifier.id, classifier]));
-  for (const classifier of runtimeBlockerClassifiers.values()) {
-    if (!declaredBlockerClassifiers.has(classifier.id)) {
-      throw new Error(`plugin "${plugin.name}" executable blocker classifier "${classifier.id}" has no matching metadata entry in contributes.blockerClassifiers`);
-    }
-  }
-  const declaredCliCommands = new Map((plugin.contributes?.cliCommands ?? []).map((command) => [command.id, command]));
-  const runtimeCliCommands = new Map((plugin?.cliCommands ?? []).map((command) => [command.id, command]));
-  for (const command of runtimeCliCommands.values()) {
-    if (!declaredCliCommands.has(command.id)) {
-      throw new Error(`plugin "${plugin.name}" executable cli command "${command.id}" has no matching metadata entry in contributes.cliCommands`);
-    }
-  }
-}
 function createPluginHost(plugins) {
   assertUniquePluginNames(plugins);
-  for (const plugin of plugins) {
-    assertRuntimeMatchesMetadata(plugin);
-  }
   const validators = [];
   const hooks = [];
   const skills = [];
@@ -128,38 +34,15 @@ function createPluginHost(plugins) {
   const capabilities = [];
   const panels = [];
   const blockerClassifiers = [];
+  const sessionExtensions = [];
   const stages = [];
   const stageMutations = [];
   const stageExecutors = {};
-  const executableValidators = [];
-  const executableTaskSources = [];
-  const executableCapabilities = [];
-  const executablePanels = [];
-  const executableBlockerClassifiers = [];
-  const executableCliCommands = [];
   for (const plugin of plugins) {
     const c = plugin.contributes;
     if (!c)
       continue;
     const pluginName = plugin.name;
-    if (plugin?.validators) {
-      executableValidators.push(...plugin.validators.map((item) => ({ item, pluginName })));
-    }
-    if (plugin?.taskSources) {
-      executableTaskSources.push(...plugin.taskSources.map((item) => ({ item, pluginName })));
-    }
-    if (plugin?.featureCapabilities) {
-      executableCapabilities.push(...plugin.featureCapabilities.map((item) => ({ item, pluginName })));
-    }
-    if (plugin?.panels) {
-      executablePanels.push(...plugin.panels.map((item) => ({ item, pluginName })));
-    }
-    if (plugin?.blockerClassifiers) {
-      executableBlockerClassifiers.push(...plugin.blockerClassifiers.map((item) => ({ item, pluginName })));
-    }
-    if (plugin?.cliCommands) {
-      executableCliCommands.push(...plugin.cliCommands.map((item) => ({ item, pluginName })));
-    }
     if (c.validators)
       validators.push(...c.validators.map((item) => ({ item, pluginName })));
     if (c.hooks)
@@ -182,27 +65,17 @@ function createPluginHost(plugins) {
       panels.push(...c.panels.map((item) => ({ item, pluginName })));
     if (c.blockerClassifiers)
       blockerClassifiers.push(...c.blockerClassifiers.map((item) => ({ item, pluginName })));
-    if (c.stages)
-      stages.push(...c.stages.map((item) => ({ item, pluginName })));
+    if (c.sessionExtensions)
+      sessionExtensions.push(...c.sessionExtensions.map((item) => ({ item, pluginName })));
     if (c.stageMutations)
       stageMutations.push(...c.stageMutations.map((item) => ({ item, pluginName })));
-    if (plugin?.stages)
-      Object.assign(stageExecutors, plugin.stages);
-  }
-  indexById(executableValidators, "executableValidator");
-  indexById(executableTaskSources, "executableTaskSource");
-  indexById(executableCapabilities, "executableCapability");
-  indexById(executablePanels, "executablePanel");
-  indexById(executableBlockerClassifiers, "executableBlockerClassifier");
-  indexById(executableCliCommands, "executableCliCommand");
-  const taskSourceFactoryByKind = new Map;
-  const taskSourceKindRegistrant = new Map;
-  for (const { item, pluginName } of executableTaskSources) {
-    if (taskSourceFactoryByKind.has(item.kind)) {
-      throw new Error(`duplicate task source kind "${item.kind}": registered by plugins "${taskSourceKindRegistrant.get(item.kind)}" and "${pluginName}"`);
+    if (c.stages) {
+      for (const stage of c.stages) {
+        stages.push({ item: stage, pluginName });
+        if (stage.run)
+          stageExecutors[stage.id] = stage.run;
+      }
     }
-    taskSourceFactoryByKind.set(item.kind, item);
-    taskSourceKindRegistrant.set(item.kind, pluginName);
   }
   const validatorMap = indexById(validators, "validator");
   const hookMap = indexById(hooks, "hook");
@@ -215,6 +88,16 @@ function createPluginHost(plugins) {
   const capabilityMap = indexById(capabilities, "capability");
   const panelMap = indexById(panels, "panel");
   const blockerClassifierMap = indexById(blockerClassifiers, "blockerClassifier");
+  indexById(sessionExtensions, "sessionExtension");
+  const taskSourceFactoryByKind = new Map;
+  const taskSourceKindRegistrant = new Map;
+  for (const { item, pluginName } of taskSources) {
+    if (taskSourceFactoryByKind.has(item.kind)) {
+      throw new Error(`duplicate task source kind "${item.kind}": registered by plugins "${taskSourceKindRegistrant.get(item.kind)}" and "${pluginName}"`);
+    }
+    taskSourceFactoryByKind.set(item.kind, item);
+    taskSourceKindRegistrant.set(item.kind, pluginName);
+  }
   const allValidators = validators.map((c) => c.item);
   const allHooks = hooks.map((c) => c.item);
   const allSkills = skills.map((c) => c.item);
@@ -228,12 +111,7 @@ function createPluginHost(plugins) {
   const allCapabilities = capabilities.map((c) => c.item);
   const allPanels = panels.map((c) => c.item);
   const allBlockerClassifiers = blockerClassifiers.map((c) => c.item);
-  const allExecutableValidators = executableValidators.map((c) => c.item);
-  const allExecutableTaskSources = executableTaskSources.map((c) => c.item);
-  const allExecutableCapabilities = executableCapabilities.map((c) => c.item);
-  const allExecutablePanels = executablePanels.map((c) => c.item);
-  const allExecutableBlockerClassifiers = executableBlockerClassifiers.map((c) => c.item);
-  const allExecutableCliCommands = executableCliCommands.map((c) => c.item);
+  const allSessionExtensions = sessionExtensions.map((c) => c.item);
   const executableCliCommandByName = new Map;
   const registerExecutableCliCommandSelector = (selector, contribution) => {
     const existing = executableCliCommandByName.get(selector);
@@ -242,7 +120,7 @@ function createPluginHost(plugins) {
     }
     executableCliCommandByName.set(selector, contribution);
   };
-  for (const contribution of executableCliCommands) {
+  for (const contribution of cliCommands) {
     const command = contribution.item;
     const family = command.family ?? command.id;
     registerExecutableCliCommandSelector(command.id, contribution);
@@ -277,12 +155,13 @@ function createPluginHost(plugins) {
     listStages: () => allStages,
     listStageMutations: () => allStageMutations,
     listStageExecutors: () => stageExecutors,
-    listExecutableValidators: () => allExecutableValidators,
-    listExecutableTaskSources: () => allExecutableTaskSources,
-    listExecutableCapabilities: () => allExecutableCapabilities,
-    listExecutablePanels: () => allExecutablePanels,
-    listExecutableBlockerClassifiers: () => allExecutableBlockerClassifiers,
-    listExecutableCliCommands: () => allExecutableCliCommands,
+    listExecutableValidators: () => allValidators.filter((v) => typeof v.run === "function"),
+    listExecutableTaskSources: () => allTaskSources,
+    listExecutableCapabilities: () => allCapabilities.filter((c) => typeof c.run === "function"),
+    listExecutablePanels: () => allPanels.filter((p) => typeof p.produce === "function"),
+    listExecutableBlockerClassifiers: () => allBlockerClassifiers,
+    listExecutableCliCommands: () => allCliCommands,
+    listSessionExtensions: () => allSessionExtensions,
     resolveExecutableCliCommand: (requested) => executableCliCommandByName.get(requested)?.item,
     resolveTaskSourceFactoryByKind: (kind) => taskSourceFactoryByKind.get(kind)
   };

package/dist/src/plugin-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { BlockerClassifierRegistration, CliCommandRegistration, HookImplementation, PanelRegistration, ProductCapabilityRegistration, RegisteredTaskSource, RigConfig, RigPlugin, StageRun, TaskSourceConfig, TaskSourceRegistration, ValidatorRegistration } from "@rig/contracts";
+import type { AgentRoleRegistration, BlockerClassifierRegistration, CapabilityReplacementSpec, CapabilityTag, CliCommandRegistration, HookImplementation, HookRegistration, PanelRegistration, ProductCapabilityRegistration, RegisteredTaskSource, RepoSourceRegistration, RigConfig, SessionExtensionRegistration, SkillRegistration, Stage, StageMutation, StageRun, TaskFieldExtension, TaskSourceConfig, TaskSourceRegistration, ValidatorRegistration } from "@rig/contracts";
 export interface ValidatorResult {
     id: string;
     passed: boolean;
@@ -13,7 +13,7 @@ export interface ValidatorContext {
     artifactsDir?: string;
     taskConfig?: unknown;
 }
-export interface RegisteredValidator extends ValidatorRegistration {
+export interface Validator extends ValidatorRegistration {
     run(ctx: ValidatorContext): Promise<ValidatorResult>;
 }
 /**
@@ -33,71 +33,102 @@ export interface TaskSourceFactoryContext {
     rigConfig?: RigConfig;
 }
 /**
- * Executable task-source factory contributed by a plugin. A plugin
- * registers a TaskSourceRegistration metadata entry (with `id` and `kind`)
- * AND a factory here that turns a TaskSourceConfig into a RegisteredTaskSource.
- *
- * `kind` is matched against `config.taskSource.kind` at boot. The first
- * matching plugin factory wins; if multiple plugins claim the same kind,
- * `createPluginHost` throws a duplicate-kind error.
+ * Task-source contribution: metadata (`id`, `kind`) plus the `factory` that
+ * turns a TaskSourceConfig into a RegisteredTaskSource. `kind` is matched
+ * against `config.taskSource.kind` at boot; duplicate kinds throw in
+ * `createPluginHost`.
  */
-export interface TaskSourceFactoryEntry extends TaskSourceRegistration {
+export interface TaskSource extends TaskSourceRegistration {
     factory(config: TaskSourceConfig, context?: TaskSourceFactoryContext): RegisteredTaskSource;
 }
-export interface RuntimeFeatureCapability extends ProductCapabilityRegistration {
+export interface FeatureCapability extends ProductCapabilityRegistration {
     run?: (input: unknown) => Promise<unknown> | unknown;
 }
-export interface RuntimePanelProducer extends PanelRegistration {
+/** @deprecated single-channel rename — use {@link FeatureCapability}. */
+export type RuntimeFeatureCapability = FeatureCapability;
+export interface Panel extends PanelRegistration {
     produce?: (context?: unknown) => Promise<unknown> | unknown;
 }
-export interface RuntimeBlockerClassifier extends BlockerClassifierRegistration {
+export interface BlockerClassifierEntry extends BlockerClassifierRegistration {
     classify(input: unknown): Promise<unknown> | unknown;
 }
+/** @deprecated single-channel rename — use {@link BlockerClassifierEntry}. */
+export type RuntimeBlockerClassifier = BlockerClassifierEntry;
 export interface RuntimeCliContext {
     projectRoot: string;
     outputMode?: string;
     dryRun?: boolean;
 }
-export interface RuntimeCliCommand extends CliCommandRegistration {
+export interface CliCommand extends CliCommandRegistration {
     run(context: RuntimeCliContext, args: readonly string[]): Promise<unknown> | unknown;
 }
-export interface RigPluginRuntime {
-    validators?: readonly RegisteredValidator[];
-    taskSources?: readonly TaskSourceFactoryEntry[];
-    /**
-     * Typed hook implementations keyed by hook id. Each key must match a
-     * declared `contributes.hooks` entry on the same plugin. A typed hook and
-     * a metadata `command` string are mutually exclusive per hook — and when
-     * this channel is present, every declared hook must be implemented one way
-     * or the other (same all-or-none rule as validators). The runtime's
-     * hook-materializer generates the shim command that routes Claude Code's
-     * hook invocation to the typed function (see
-     * `@rig/runtime/control-plane/hook-runner`).
-     */
-    hooks?: Record<string, HookImplementation>;
-    /**
-     * Executable stage implementations keyed by stage id — the runtime counterpart
-     * to `contributes.stageMutations` (which carries only the ordering descriptor).
-     * When a plugin inserts/replaces a stage, its `run(ctx)` lives here. The plugin
-     * host flattens these (`listStageExecutors()`) so the kernel's stage runner can
-     * execute plugin-contributed stages (e.g. the docs-drift pre-merge gate).
-     */
-    stages?: Record<string, StageRun>;
-    /**
-     * Executable product-capability registrations. This is deliberately separate
-     * from `capabilities`: that map is reserved for the five kernel provider
-     * capability tags resolved by `@rig/kernel-seed`.
-     */
-    featureCapabilities?: readonly RuntimeFeatureCapability[];
-    panels?: readonly RuntimePanelProducer[];
-    blockerClassifiers?: readonly RuntimeBlockerClassifier[];
-    cliCommands?: readonly RuntimeCliCommand[];
+/**
+ * Hook contribution: metadata plus an optional typed `handler`. A hook is
+ * implemented either by a typed `handler` or by a raw `command` string in its
+ * metadata — never both. The runtime's hook-materializer generates the shim
+ * command that routes Claude Code's hook invocation to the typed function.
+ */
+export interface Hook extends HookRegistration {
+    handler?: HookImplementation;
+}
+/**
+ * Stage contribution: the stage descriptor plus its executor. When a plugin
+ * inserts/replaces a stage (via a matching `stageMutations` entry), its
+ * `run(ctx)` lives here so the kernel's stage runner can execute it.
+ */
+export interface StageEntry extends Stage {
+    run?: StageRun;
+}
+/**
+ * Executable installer for a contributed session extension. The `api` argument
+ * is the agent-session extension API (the OMP/Pi `ExtensionAPI`), kept as `any`
+ * here on purpose: typing it against the OMP runtime would couple the
+ * substrate-agnostic plugin model to the OMP substrate (architecture reference
+ * §12). The plugin author (run-worker) and the consumer (rig-host) hold the
+ * concrete `ExtensionAPI` type; the plugin host only sees an opaque installer.
+ */
+export type SessionExtensionInstall = (api: any) => void | Promise<void>;
+export interface SessionExtensionEntry extends SessionExtensionRegistration {
+    install: SessionExtensionInstall;
+}
+/**
+ * Single-channel contributions. Fn-bearing kinds carry their executable fn on
+ * the same entry as their metadata; metadata-only kinds (skills, repoSources,
+ * agentRoles, taskFieldSchemas, stageMutations) are pure registrations.
+ */
+export interface PluginContributes {
+    validators?: readonly Validator[];
+    hooks?: readonly Hook[];
+    skills?: readonly SkillRegistration[];
+    repoSources?: readonly RepoSourceRegistration[];
+    agentRoles?: readonly AgentRoleRegistration[];
+    taskFieldSchemas?: readonly TaskFieldExtension[];
+    taskSources?: readonly TaskSource[];
+    cliCommands?: readonly CliCommand[];
+    stages?: readonly StageEntry[];
+    stageMutations?: readonly StageMutation[];
+    capabilities?: readonly FeatureCapability[];
+    panels?: readonly Panel[];
+    blockerClassifiers?: readonly BlockerClassifierEntry[];
+    sessionExtensions?: readonly SessionExtensionEntry[];
+}
+/**
+ * The authored plugin object. Validated against the `RigPlugin` metadata schema
+ * in @rig/contracts; the executable fns on `contributes` entries and the kernel
+ * `capabilityProviders` ride alongside and are ignored by Schema decode.
+ */
+export interface RigPlugin {
+    name: string;
+    version: string;
+    provides?: readonly CapabilityTag[];
+    requires?: readonly CapabilityTag[];
+    replaces?: readonly CapabilityReplacementSpec[];
+    contributes?: PluginContributes;
     /**
-     * Executable kernel-capability providers keyed by **capability tag**
-     * (`transport`, `journal`, …) — the same shape the kernel-seed resolver reads
-     * via `plugin.runtime.capabilities[tag]`. Which tags a plugin provides is
-     * declared by the top-level `provides: CapabilityTag[]`; this holds the impls.
+     * Kernel capability implementations keyed by the tag named in `provides`
+     * (`transport`, `journal`, `stage-runner`, `loader-policy`, `kernel`). This
+     * is the single home for what the old kernel `LoadedPlugin.runtime.capabilities`
+     * / `runtime.kernel` carried — kernel-seed resolves capabilities from here.
      */
-    capabilities?: Record<string, unknown>;
+    capabilityProviders?: Partial<Record<CapabilityTag, unknown>>;
 }
-export type RigPluginWithRuntime = RigPlugin & RigPluginRuntime;

package/dist/src/project-plugins.d.ts

@@ -0,0 +1,66 @@
+import type { RigConfig } from "@rig/contracts";
+import { type PluginHost } from "./plugin-host";
+import type { RigPlugin } from "./plugin-runtime";
+export type ProjectPluginResolutionMode = "strict-config-only";
+export type ProjectConfigPresence = {
+    readonly status: "loaded";
+    readonly path: string | null;
+} | {
+    readonly status: "missing";
+    readonly path: null;
+};
+export type ProjectPluginResolutionWarningCode = never;
+export type ProjectPluginResolutionWarning = {
+    readonly code: ProjectPluginResolutionWarningCode;
+    readonly level: "warning" | "info";
+    readonly message: string;
+};
+export type ProjectPluginResolution = {
+    readonly mode: ProjectPluginResolutionMode;
+    readonly projectRoot: string;
+    readonly surfaceName: string;
+    readonly configPresence: ProjectConfigPresence;
+    readonly config: RigConfig | null;
+    readonly warnings: readonly ProjectPluginResolutionWarning[];
+    readonly plugins: readonly RigPlugin[];
+};
+export type ProjectPluginHostResult = {
+    readonly host: PluginHost;
+    readonly resolved: ProjectPluginResolution;
+};
+export type LoadProjectConfig = (projectRoot: string) => Promise<RigConfig>;
+export type LoadProjectPluginSetOptions = {
+    readonly mode?: ProjectPluginResolutionMode;
+    readonly surfaceName?: string;
+    readonly load?: LoadProjectConfig;
+};
+export type ProjectPluginResolutionOptions = Omit<LoadProjectPluginSetOptions, "mode" | "surfaceName"> & {
+    readonly projectRoot: string;
+    readonly mode: ProjectPluginResolutionMode;
+    readonly surfaceName: string;
+};
+export declare function projectPluginResolutionWarningMessages(resolved: Pick<ProjectPluginResolution, "warnings">): readonly string[];
+export declare function loadProjectPluginSet(options: ProjectPluginResolutionOptions): Promise<ProjectPluginResolution>;
+export declare function loadProjectPluginSet(projectRoot: string, options?: LoadProjectPluginSetOptions): Promise<ProjectPluginResolution>;
+export type ResolvedPluginHost = {
+    readonly host: PluginHost;
+    readonly config: RigConfig;
+};
+export type ResolvePluginHostOptions = {
+    readonly load?: LoadProjectConfig;
+};
+/**
+ * The single cached plugin-host resolver. Returns the resolved host plus the
+ * loaded config for a project root, memoized per normalized root and validated
+ * by the rig.config file mtime — an edited config rebuilds the host (preserving
+ * loadConfig's mtime-cache semantics) while every other consumer in the same
+ * generation shares one resolved host.
+ *
+ * It propagates loadConfig's throw on a missing/broken config; each consumer
+ * keeps its own try/catch so per-call-site degradation (graceful-null vs
+ * surfaced error) is unchanged. A custom `load` bypasses the shared cache so it
+ * cannot poison the canonical on-disk host other consumers read.
+ */
+export declare function resolvePluginHost(projectRoot: string, options?: ResolvePluginHostOptions): Promise<ResolvedPluginHost>;
+export declare function createProjectPluginHost(options: ProjectPluginResolutionOptions): Promise<ProjectPluginHostResult>;
+export declare function createProjectPluginHost(projectRoot: string, options?: LoadProjectPluginSetOptions): Promise<ProjectPluginHostResult>;