@h-rig/core 0.0.6-alpha.18 → 0.0.6-alpha.181

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

@@ -0,0 +1,31 @@
+import type { RegisteredTaskSource, RigConfig, TaskFieldExtension } from "@rig/contracts";
+import type { PluginHost } from "./plugin-host";
+import type { TaskSourceFactoryContext } from "./plugin-runtime";
+export interface TaskSourceRegistry {
+    register(s: RegisteredTaskSource): void;
+    resolveById(id: string): RegisteredTaskSource;
+    resolveByKind(kind: string): RegisteredTaskSource;
+    list(): readonly RegisteredTaskSource[];
+}
+export declare function createTaskSourceRegistry(): TaskSourceRegistry;
+/**
+ * Instantiate the task-source adapter selected by `config.taskSource.kind`
+ * from executable task-source factories contributed by loaded plugins.
+ *
+ * First-party adapters are not special-cased here: projects that use the
+ * standard GitHub Issues or files sources get those factories by loading
+ * `standard()` in `rig.config.ts`, exactly like any third-party adapter.
+ */
+export declare function buildTaskSourceRegistry(config: RigConfig, pluginHost?: PluginHost, context?: TaskSourceFactoryContext): TaskSourceRegistry;
+export interface TaskFieldRegistry {
+    get(id: string): TaskFieldExtension | undefined;
+    list(): readonly TaskFieldExtension[];
+    fieldNames(): readonly string[];
+    validateTaskFields(task: Record<string, unknown>): {
+        ok: true;
+    } | {
+        ok: false;
+        errors: string[];
+    };
+}
+export declare function createTaskFieldRegistry(extensions: readonly TaskFieldExtension[]): TaskFieldRegistry;

package/dist/src/plugin-host-registries.js

@@ -0,0 +1,79 @@
+// @bun
+// packages/core/src/plugin-host-registries.ts
+function createTaskSourceRegistry() {
+  const byId = new Map;
+  const order = [];
+  return {
+    register(s) {
+      if (byId.has(s.id))
+        throw new Error(`task source already registered: ${s.id}`);
+      byId.set(s.id, s);
+      order.push(s);
+    },
+    resolveById(id) {
+      const s = byId.get(id);
+      if (!s)
+        throw new Error(`task source not registered: ${id}`);
+      return s;
+    },
+    resolveByKind(kind) {
+      for (const s of order)
+        if (s.kind === kind)
+          return s;
+      throw new Error(`no task source registered for kind: ${kind}`);
+    },
+    list: () => order
+  };
+}
+function formatRegisteredKinds(pluginHost) {
+  const kinds = pluginHost ? pluginHost.listExecutableTaskSources().map((source) => source.kind) : [];
+  return kinds.length > 0 ? kinds.join(", ") : "none";
+}
+function buildTaskSourceRegistry(config, pluginHost, context) {
+  const registry = createTaskSourceRegistry();
+  const taskSourceConfig = config.taskSource;
+  const factory = pluginHost?.resolveTaskSourceFactoryByKind(taskSourceConfig.kind);
+  if (!factory) {
+    throw new Error(`No task source factory registered for kind "${taskSourceConfig.kind}". ` + `Registered kinds: ${formatRegisteredKinds(pluginHost)}. ` + "Load a plugin that contributes an executable task source factory for this kind.");
+  }
+  registry.register(factory.factory(taskSourceConfig, context ? { ...context, rigConfig: config } : undefined));
+  return registry;
+}
+function createTaskFieldRegistry(extensions) {
+  const byId = new Map;
+  for (const e of extensions) {
+    if (byId.has(e.id))
+      throw new Error(`task field extension already registered: ${e.id}`);
+    byId.set(e.id, e);
+  }
+  return {
+    get: (id) => byId.get(id),
+    list: () => Array.from(byId.values()),
+    fieldNames: () => Array.from(byId.values()).map((e) => e.fieldName),
+    validateTaskFields(task) {
+      const errors = [];
+      for (const ext of byId.values()) {
+        let schema;
+        try {
+          schema = JSON.parse(ext.schemaJson);
+        } catch {
+          errors.push(`task field "${ext.id}": schemaJson is not valid JSON`);
+          continue;
+        }
+        const isRequired = typeof schema === "object" && schema !== null && schema.required === true;
+        if (!isRequired)
+          continue;
+        const value = task[ext.fieldName];
+        if (value === undefined || value === null || value === "") {
+          errors.push(`task field "${ext.fieldName}" (from extension "${ext.id}") is required but missing`);
+        }
+      }
+      return errors.length === 0 ? { ok: true } : { ok: false, errors };
+    }
+  };
+}
+export {
+  createTaskSourceRegistry,
+  createTaskFieldRegistry,
+  buildTaskSourceRegistry
+};

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

@@ -0,0 +1,77 @@
+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, SeedEntrypoint, TaskSource, Validator } from "./plugin-runtime";
+export interface PluginHost {
+    getValidator(id: string): ValidatorRegistration | undefined;
+    getHook(id: string): HookRegistration | undefined;
+    getSkill(id: string): SkillRegistration | undefined;
+    getRepoSource(id: string): RepoSourceRegistration | undefined;
+    getAgentRole(id: string): AgentRoleRegistration | undefined;
+    getTaskFieldExtension(id: string): TaskFieldExtension | undefined;
+    getTaskSource(id: string): TaskSourceRegistration | undefined;
+    getCliCommand(id: string): CliCommandRegistration | undefined;
+    getCapability(id: string): ProductCapabilityRegistration | undefined;
+    getPanel(id: string): PanelRegistration | undefined;
+    getBlockerClassifier(id: string): BlockerClassifierRegistration | undefined;
+    listValidators(): readonly ValidatorRegistration[];
+    listHooks(): readonly HookRegistration[];
+    listSkills(): readonly SkillRegistration[];
+    listRepoSources(): readonly RepoSourceRegistration[];
+    listAgentRoles(): readonly AgentRoleRegistration[];
+    listTaskFieldExtensions(): readonly TaskFieldExtension[];
+    listTaskSources(): readonly TaskSourceRegistration[];
+    listCliCommands(): readonly CliCommandRegistration[];
+    listCapabilities(): readonly ProductCapabilityRegistration[];
+    listPanels(): readonly PanelRegistration[];
+    listBlockerClassifiers(): readonly BlockerClassifierRegistration[];
+    listStages(): readonly Stage[];
+    /**
+     * Stage mutations contributed by all loaded plugins, flattened in load order.
+     * The kernel resolves these (+ the default-lifecycle stages) into the run
+     * pipeline — this is the wire that makes "every plugin mutates the lifecycle"
+     * real (drift pre-merge gate, closure observer, reclassify observer).
+     */
+    listStageMutations(): readonly StageMutation[];
+    /**
+     * 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 (single-channel: the same
+     * `contributes.validators` entries, which carry their `run`).
+     */
+    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 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[];
+    listSeedEntrypoints(): readonly SeedEntrypoint[];
+    resolveSeedEntrypointByBasename(basename: string): SeedEntrypoint | undefined;
+    resolveSeedEntrypointByWorkerArg(workerArg: string): SeedEntrypoint | undefined;
+    resolveInsidePtySeedEntrypoint(): SeedEntrypoint | undefined;
+    resolveExecutableCliCommand(requested: string): CliCommand | undefined;
+    resolveDefaultRootCliCommand(): 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): TaskSource | undefined;
+}
+export declare function createPluginHost(plugins: readonly RigPlugin[]): PluginHost;

package/dist/src/plugin-host.js

@@ -21,49 +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.__runtime?.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.__runtime?.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.__runtime?.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.__runtime?.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`);
-      }
-    }
-  }
-}
 function createPluginHost(plugins) {
   assertUniquePluginNames(plugins);
-  for (const plugin of plugins) {
-    assertRuntimeMatchesMetadata(plugin);
-  }
   const validators = [];
   const hooks = [];
   const skills = [];
@@ -72,19 +31,19 @@ function createPluginHost(plugins) {
   const taskFieldExtensions = [];
   const taskSources = [];
   const cliCommands = [];
-  const executableValidators = [];
-  const executableTaskSources = [];
+  const capabilities = [];
+  const panels = [];
+  const blockerClassifiers = [];
+  const sessionExtensions = [];
+  const seedEntrypoints = [];
+  const stages = [];
+  const stageMutations = [];
+  const stageExecutors = {};
   for (const plugin of plugins) {
     const c = plugin.contributes;
     if (!c)
       continue;
     const pluginName = plugin.name;
-    if (plugin.__runtime?.validators) {
-      executableValidators.push(...plugin.__runtime.validators.map((item) => ({ item, pluginName })));
-    }
-    if (plugin.__runtime?.taskSources) {
-      executableTaskSources.push(...plugin.__runtime.taskSources.map((item) => ({ item, pluginName })));
-    }
     if (c.validators)
       validators.push(...c.validators.map((item) => ({ item, pluginName })));
     if (c.hooks)
@@ -101,17 +60,25 @@ function createPluginHost(plugins) {
       taskSources.push(...c.taskSources.map((item) => ({ item, pluginName })));
     if (c.cliCommands)
       cliCommands.push(...c.cliCommands.map((item) => ({ item, pluginName })));
-  }
-  indexById(executableValidators, "executableValidator");
-  indexById(executableTaskSources, "executableTaskSource");
-  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.capabilities)
+      capabilities.push(...c.capabilities.map((item) => ({ item, pluginName })));
+    if (c.panels)
+      panels.push(...c.panels.map((item) => ({ item, pluginName })));
+    if (c.blockerClassifiers)
+      blockerClassifiers.push(...c.blockerClassifiers.map((item) => ({ item, pluginName })));
+    if (c.sessionExtensions)
+      sessionExtensions.push(...c.sessionExtensions.map((item) => ({ item, pluginName })));
+    if (c.seedEntrypoints)
+      seedEntrypoints.push(...c.seedEntrypoints.map((item) => ({ item, pluginName })));
+    if (c.stageMutations)
+      stageMutations.push(...c.stageMutations.map((item) => ({ item, 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");
@@ -121,6 +88,52 @@ function createPluginHost(plugins) {
   const taskFieldExtMap = indexById(taskFieldExtensions, "taskFieldExtension");
   const taskSourceMap = indexById(taskSources, "taskSource");
   const cliCommandMap = indexById(cliCommands, "cliCommand");
+  const capabilityMap = indexById(capabilities, "capability");
+  const panelMap = indexById(panels, "panel");
+  const blockerClassifierMap = indexById(blockerClassifiers, "blockerClassifier");
+  indexById(sessionExtensions, "sessionExtension");
+  indexById(seedEntrypoints, "seedEntrypoint");
+  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 seedEntrypointByBasename = new Map;
+  const seedEntrypointByWorkerArg = new Map;
+  let insidePtySeedEntrypoint;
+  const registerSeedEntrypointSelector = (map, selectorKind, selector, contribution) => {
+    const existing = map.get(selector);
+    if (existing) {
+      throw new Error(`duplicate seed entrypoint ${selectorKind} "${selector}": registered by entrypoint "${existing.item.id}" from plugin "${existing.pluginName}" and entrypoint "${contribution.item.id}" from plugin "${contribution.pluginName}"`);
+    }
+    map.set(selector, contribution);
+  };
+  for (const contribution of seedEntrypoints) {
+    const entrypoint = contribution.item;
+    let selectorCount = 0;
+    if (entrypoint.basename) {
+      selectorCount += 1;
+      registerSeedEntrypointSelector(seedEntrypointByBasename, "basename", entrypoint.basename, contribution);
+    }
+    if (entrypoint.workerArg) {
+      selectorCount += 1;
+      registerSeedEntrypointSelector(seedEntrypointByWorkerArg, "workerArg", entrypoint.workerArg, contribution);
+    }
+    if (entrypoint.insidePty) {
+      selectorCount += 1;
+      if (insidePtySeedEntrypoint) {
+        throw new Error(`duplicate seed entrypoint inside-pty selector: registered by entrypoint "${insidePtySeedEntrypoint.item.id}" from plugin "${insidePtySeedEntrypoint.pluginName}" and entrypoint "${entrypoint.id}" from plugin "${contribution.pluginName}"`);
+      }
+      insidePtySeedEntrypoint = contribution;
+    }
+    if (selectorCount === 0) {
+      throw new Error(`seed entrypoint "${entrypoint.id}" from plugin "${contribution.pluginName}" must declare at least one selector (basename, workerArg, or insidePty)`);
+    }
+  }
   const allValidators = validators.map((c) => c.item);
   const allHooks = hooks.map((c) => c.item);
   const allSkills = skills.map((c) => c.item);
@@ -129,8 +142,39 @@ function createPluginHost(plugins) {
   const allTaskFieldExtensions = taskFieldExtensions.map((c) => c.item);
   const allTaskSources = taskSources.map((c) => c.item);
   const allCliCommands = cliCommands.map((c) => c.item);
-  const allExecutableValidators = executableValidators.map((c) => c.item);
-  const allExecutableTaskSources = executableTaskSources.map((c) => c.item);
+  const allStageMutations = stageMutations.map((c) => c.item);
+  const allStages = stages.map((c) => c.item);
+  const allCapabilities = capabilities.map((c) => c.item);
+  const allPanels = panels.map((c) => c.item);
+  const allBlockerClassifiers = blockerClassifiers.map((c) => c.item);
+  const allSessionExtensions = sessionExtensions.map((c) => c.item);
+  const allSeedEntrypoints = seedEntrypoints.map((c) => c.item);
+  const executableCliCommandByName = new Map;
+  const registerExecutableCliCommandSelector = (selector, contribution) => {
+    const existing = executableCliCommandByName.get(selector);
+    if (existing && existing.item.id !== contribution.item.id) {
+      throw new Error(`duplicate executable CLI selector "${selector}" registered by command "${existing.item.id}" from plugin "${existing.pluginName}" and command "${contribution.item.id}" from plugin "${contribution.pluginName}"`);
+    }
+    executableCliCommandByName.set(selector, contribution);
+  };
+  for (const contribution of cliCommands) {
+    const command = contribution.item;
+    const family = command.family ?? command.id;
+    registerExecutableCliCommandSelector(command.id, contribution);
+    registerExecutableCliCommandSelector(family, contribution);
+    for (const alias of command.aliases ?? []) {
+      registerExecutableCliCommandSelector(alias, contribution);
+    }
+  }
+  let defaultRootCliCommand;
+  for (const contribution of cliCommands) {
+    if (!contribution.item.rootDefault)
+      continue;
+    if (defaultRootCliCommand) {
+      throw new Error(`duplicate default root CLI command registered by command "${defaultRootCliCommand.item.id}" from plugin "${defaultRootCliCommand.pluginName}" and command "${contribution.item.id}" from plugin "${contribution.pluginName}"`);
+    }
+    defaultRootCliCommand = contribution;
+  }
   return {
     getValidator: (id) => validatorMap.get(id),
     getHook: (id) => hookMap.get(id),
@@ -140,6 +184,9 @@ function createPluginHost(plugins) {
     getTaskFieldExtension: (id) => taskFieldExtMap.get(id),
     getTaskSource: (id) => taskSourceMap.get(id),
     getCliCommand: (id) => cliCommandMap.get(id),
+    getCapability: (id) => capabilityMap.get(id),
+    getPanel: (id) => panelMap.get(id),
+    getBlockerClassifier: (id) => blockerClassifierMap.get(id),
     listValidators: () => allValidators,
     listHooks: () => allHooks,
     listSkills: () => allSkills,
@@ -148,8 +195,25 @@ function createPluginHost(plugins) {
     listTaskFieldExtensions: () => allTaskFieldExtensions,
     listTaskSources: () => allTaskSources,
     listCliCommands: () => allCliCommands,
-    listExecutableValidators: () => allExecutableValidators,
-    listExecutableTaskSources: () => allExecutableTaskSources,
+    listCapabilities: () => allCapabilities,
+    listPanels: () => allPanels,
+    listBlockerClassifiers: () => allBlockerClassifiers,
+    listStages: () => allStages,
+    listStageMutations: () => allStageMutations,
+    listStageExecutors: () => stageExecutors,
+    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,
+    listSeedEntrypoints: () => allSeedEntrypoints,
+    resolveSeedEntrypointByBasename: (value) => seedEntrypointByBasename.get(value)?.item,
+    resolveSeedEntrypointByWorkerArg: (value) => seedEntrypointByWorkerArg.get(value)?.item,
+    resolveInsidePtySeedEntrypoint: () => insidePtySeedEntrypoint?.item,
+    resolveExecutableCliCommand: (requested) => executableCliCommandByName.get(requested)?.item,
+    resolveDefaultRootCliCommand: () => defaultRootCliCommand?.item,
     resolveTaskSourceFactoryByKind: (kind) => taskSourceFactoryByKind.get(kind)
   };
 }

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

@@ -0,0 +1,173 @@
+import type { AgentRoleRegistration, BlockerClassifierRegistration, CapabilityReplacementSpec, CapabilityTag, CliCommandRegistration, HookImplementation, HookRegistration, PanelRegistration, ProductCapabilityRegistration, RegisteredTaskSource, RepoSourceRegistration, RigConfig, SeedEntrypointRegistration, SessionExtensionRegistration, SkillRegistration, Stage, StageMutation, StageRun, TaskFieldExtension, TaskSourceConfig, TaskSourceRegistration, ValidatorRegistration } from "@rig/contracts";
+export interface ValidatorResult {
+    id: string;
+    passed: boolean;
+    summary: string;
+    details?: string;
+}
+export interface ValidatorContext {
+    taskId: string;
+    workspaceRoot: string;
+    scope: readonly string[];
+    monorepoRoot?: string;
+    artifactsDir?: string;
+    taskConfig?: unknown;
+}
+export interface Validator extends ValidatorRegistration {
+    run(ctx: ValidatorContext): Promise<ValidatorResult>;
+}
+/**
+ * Project context handed to task-source factories at instantiation. The
+ * server process's cwd is NOT necessarily the project root (workspace-spawned
+ * servers run from the engine checkout), so factories that touch the
+ * filesystem must resolve relative config paths against `projectRoot`,
+ * never cwd.
+ */
+export interface TaskSourceFactoryContext {
+    projectRoot: string;
+    /**
+     * Full project config for adapters that need source-adjacent top-level
+     * settings (for example github.projects). Factories should still treat
+     * TaskSourceConfig as the primary adapter config.
+     */
+    rigConfig?: RigConfig;
+}
+/**
+ * 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 TaskSource extends TaskSourceRegistration {
+    factory(config: TaskSourceConfig, context?: TaskSourceFactoryContext): RegisteredTaskSource;
+}
+export type FeatureCapability = ProductCapabilityRegistration;
+/** @deprecated single-channel rename — use {@link FeatureCapability}. */
+export interface Panel extends PanelRegistration {
+    produce?: (context?: unknown) => Promise<unknown> | unknown;
+}
+export interface BlockerClassifierEntry extends BlockerClassifierRegistration {
+    classify(input: unknown): Promise<unknown> | unknown;
+}
+/** @deprecated single-channel rename — use {@link BlockerClassifierEntry}. */
+export interface RuntimeCliContext {
+    projectRoot: string;
+    outputMode?: string;
+    dryRun?: boolean;
+}
+export interface CliCommand extends CliCommandRegistration {
+    run(context: RuntimeCliContext, args: readonly string[]): Promise<unknown> | unknown;
+}
+/**
+ * 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;
+}
+export type SeedEntrypointRunResult = boolean | void | number;
+export interface SeedEntrypointContext {
+    argv: readonly string[];
+    execPath?: string;
+    basename?: string;
+    workerArg?: string;
+    parentPort?: unknown;
+}
+export interface SeedEntrypoint extends SeedEntrypointRegistration {
+    run(context: SeedEntrypointContext): Promise<SeedEntrypointRunResult> | SeedEntrypointRunResult;
+}
+/**
+ * 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.
+ */
+/** Context handed to a plugin when it default-fills its config fragment. */
+export interface ConfigDefaultsContext {
+    /** Absolute path to the project root being configured. */
+    readonly projectRoot: string;
+    /**
+     * Explicit `owner/repo` slug when a caller already knows it (the init wizard,
+     * a setup flow). When absent, a plugin that needs the repo identity derives it
+     * from its own domain (e.g. the github plugin reads the git remote). This is
+     * the single override seam so autocreate and the wizard share one composer.
+     */
+    readonly repoSlug?: string;
+}
+/**
+ * A plugin's contribution to the declarative `.rig/rigfig.toml`.
+ *
+ * Plugins are the things that ENRICH the config: each one owns the config
+ * properties IT needs and default-fills them with its OWN domain logic — the
+ * github plugin detects owner/repo from the git remote and fills the github
+ * task source + workspace id; the pr plugin fills `[pr]`; planning fills
+ * `[planning]`; and so on. The autocreate/init composer deep-merges every
+ * active plugin's fragment (in plugin order) into the written config. Returning
+ * null (or a plugin omitting `config`) contributes nothing.
+ *
+ * `defaults` is a fn — it rides on the authored RigPlugin and is ignored by the
+ * serializable manifest Schema, like every other executable contribution entry.
+ */
+export interface PluginConfigContribution {
+    defaults(context: ConfigDefaultsContext): Record<string, unknown> | null;
+}
+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[];
+    seedEntrypoints?: readonly SeedEntrypoint[];
+    /** Declarative config defaults this plugin contributes to `.rig/rigfig.toml`. */
+    config?: PluginConfigContribution;
+}
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    capabilityProviders?: Partial<Record<CapabilityTag, unknown>>;
+}

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

@@ -0,0 +1,63 @@
+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 ProjectPluginResolution = {
+    readonly mode: ProjectPluginResolutionMode;
+    readonly projectRoot: string;
+    readonly configPresence: ProjectConfigPresence;
+    readonly config: RigConfig | null;
+    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 load?: LoadProjectConfig;
+};
+export type ProjectPluginResolutionOptions = Omit<LoadProjectPluginSetOptions, "mode"> & {
+    readonly projectRoot: string;
+    readonly mode: ProjectPluginResolutionMode;
+};
+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>;
+/**
+ * Resolve the plugin host for a project root, returning the host plus the full
+ * resolution shape. This delegates to the single cached `resolvePluginHost`
+ * memo so every consumer in a process SHARES one resolved host for a root
+ * instead of re-evaluating rig.config.ts and constructing an independent host
+ * (architecture-reference §18: one resolved host per process/root). Graceful
+ * missing-config degradation and the custom-`load` bypass are preserved.
+ */
+export declare function createProjectPluginHost(options: ProjectPluginResolutionOptions): Promise<ProjectPluginHostResult>;
+export declare function createProjectPluginHost(projectRoot: string, options?: LoadProjectPluginSetOptions): Promise<ProjectPluginHostResult>;