@uniqbit/mate-core 0.15.1-canary.2 → 0.15.1-canary.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.1-canary.2",
+  "version": "0.15.1-canary.3",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/install.ts

@@ -9,6 +9,23 @@ import {
   resolveInstallContext,
 } from "../../lib/install";
 import { renderInstallExecution } from "../install-plan";
+import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import {
+  installDeclaredPlugins,
+  type PluginInstallResult,
+} from "../../tools/setup/dynamic-plugins/install";
+
+export function reportPluginInstallResults(results: PluginInstallResult[]): void {
+  for (const result of results) {
+    if (result.status === "failed") {
+      process.stderr.write(
+        `${frameworkCommandName()}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+      );
+    } else if (result.status === "installed") {
+      console.log(`  installed plugin ${result.package}@${result.resolvedVersion}`);
+    }
+  }
+}
 
 function printPlanText(plan: Awaited<ReturnType<typeof inspectInstallPlan>>): void {
   if (plan.context.message) process.stderr.write(`${plan.context.message}\n\n`);
@@ -37,6 +54,15 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     process.exitCode = 1;
     return false;
   }
+  // Companion-declared plugins install first and hydrate into the registry
+  // before the plan is built, so one run goes install → load → plan and their
+  // own install requirements are part of the plan.
+  if (context.kind === "companion" && context.companionPath && context.config.plugins?.length) {
+    reportPluginInstallResults(
+      await installDeclaredPlugins(context.companionPath, context.config.plugins),
+    );
+    await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  }
   const plan = await inspectInstallPlan(buildInstallPlan(context));
   const missing = plan.requirements.filter((item) => !item.satisfied);
   let execution: Awaited<ReturnType<typeof renderInstallExecution>>;

package/src/cli/main.ts

@@ -18,6 +18,7 @@ import { runUpdateCommand } from "./commands/update";
 import { runInstallCommand } from "./commands/install";
 import { inspectInstallPreflight } from "../lib/install";
 import { ensureUnambiguousCompanion } from "./commands/shared/companion-selection";
+import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
 
@@ -36,11 +37,13 @@ export function isInstallRecoveryCommand(command?: string, subcommand?: string):
 export interface MainDeps {
   ensureUnambiguousCompanion: typeof ensureUnambiguousCompanion;
   inspectInstallPreflight: typeof inspectInstallPreflight;
+  hydrateDynamicPlugins: typeof hydrateDynamicPlugins;
 }
 
 const mainDeps: MainDeps = {
   ensureUnambiguousCompanion,
   inspectInstallPreflight,
+  hydrateDynamicPlugins,
 };
 
 export async function main(argv = process.argv, deps: MainDeps = mainDeps): Promise<void> {
@@ -51,6 +54,12 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
+  // Companion-declared plugins register before cap-command detection so
+  // their commands route like compiled-in ones (including MCP servers whose
+  // command is their own cap subcommand). Diagnostics stay on stderr; a
+  // missing or ambiguous companion makes this a no-op.
+  await deps.hydrateDynamicPlugins();
+
   // Plugin commands (`mate cap <namespace> <command>`) own their stdout (an
   // MCP server speaks JSON-RPC over it), so banners and background chatter
   // are suppressed for them.

package/src/index.ts

@@ -21,6 +21,16 @@ export {
   type NormalizedRegistration,
 } from "./tools/setup/registry";
 export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli/plugin-commands";
+// Dynamic plugin authors: import from this package as TYPES ONLY. Runtime
+// imports resolve a second, uninitialized copy of mate-core inside the
+// plugin's own node_modules; all runtime behavior flows through PluginHost.
+export {
+  createPluginHost,
+  PLUGIN_API_VERSION,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+  type CreatePlugin,
+  type PluginHost,
+} from "./tools/setup/dynamic-plugins/host";
 export type {
   CapabilityPlugin,
   InstructionsService,
@@ -36,4 +46,8 @@ export type {
   SetupContext,
   TemplatesService,
 } from "./tools/setup/plugin";
-export type { FrameworkConfig } from "./lib/orchestrator/types";
+export type {
+  FrameworkConfig,
+  PluginDeclaration,
+  PluginDeclarationPolicy,
+} from "./lib/orchestrator/types";

package/src/lib/orchestrator/config-store.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../framework";
 import { getDefaultSetupSelections } from "./setup-compatibilities";
 import { YamlFileStore } from "./yaml-file-store";
-import { type FrameworkConfig } from "./types";
+import { ConfigError, type FrameworkConfig } from "./types";
 
 export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
 
@@ -54,6 +54,23 @@ export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkCon
   };
 }
 
+export const PLUGIN_DECLARATION_POLICIES = ["default", "optional"] as const;
+
+/**
+ * Validates the `plugins` list of a loaded config. Declared plugins may not
+ * claim `required` — required-ness is a distribution prerogative.
+ */
+export function validatePluginDeclarations(config: FrameworkConfig): void {
+  for (const declaration of config.plugins ?? []) {
+    const policy = declaration.policy as string | undefined;
+    if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+      throw new ConfigError(
+        `plugins entry "${declaration.package}": policy "${policy}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+      );
+    }
+  }
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
@@ -61,6 +78,7 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
 
   override async load(): Promise<FrameworkConfig> {
     const merged = mergeWithDefaults(await super.load());
+    validatePluginDeclarations(merged);
     const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
     const config = migrateRtkCapabilitySplit(merged);
     if (needsMigration) await this.save(config);

package/src/lib/orchestrator/types.ts

@@ -81,11 +81,34 @@ export interface CapabilityConfig {
  */
 export type EngineConstraints = Record<string, string>;
 
+/**
+ * Registration policy for a companion-declared plugin. `required` is a
+ * distribution prerogative and is rejected for declared plugins.
+ */
+export type PluginDeclarationPolicy = "default" | "optional";
+
+/**
+ * A companion-declared npm plugin: installed by setup/install into
+ * `.mate/dependencies/plugins/` and loaded on every invocation. Declaration
+ * registers the plugin; enablement stays in the `capabilities` list.
+ */
+export interface PluginDeclaration {
+  /** npm package name (e.g. `@acme/custom-plugin`). */
+  package: string;
+  /** Exact version, semver range, or the literal `latest`. */
+  version: string;
+  /** Registration policy; absent means `optional`. */
+  policy?: PluginDeclarationPolicy;
+  /** Opaque plugin parameters, passed to the plugin factory after resolution. */
+  config?: unknown;
+}
+
 export interface FrameworkConfig {
   type?: "working" | "companion";
   git?: GitModeProfile;
   profiles: Record<string, PolicyProfile>;
   capabilities?: CapabilityConfig[];
+  plugins?: PluginDeclaration[];
   migrations?: string[];
   cliTools?: CliToolConfig[];
   packageManagers?: string[];

package/src/lib/update-checker.ts

@@ -20,9 +20,24 @@ export const updateCheckerDeps = {
   toIsoString: () => new Date().toISOString(),
 };
 
+const updateStateFileSlug = (packageName: string): string =>
+  packageName.replace(/^@/, "").replace(/[^a-zA-Z0-9._-]+/g, "-");
+
+/**
+ * Every distribution built on mate-core shares `~/.mate`, but each checks its
+ * own update package — so the cached state is scoped per package. A shared
+ * file would let the default distribution's public-npm check poison a custom
+ * distribution's banner with a version it can never install.
+ */
 export class UpdateStateStore extends YamlFileStore<UpdateState> {
-  constructor() {
-    super(path.join(os.homedir(), `.${FRAMEWORK_NAME}`, "update-state.yaml"));
+  constructor(packageName: string = getUpdateConfig().packageName) {
+    super(
+      path.join(
+        os.homedir(),
+        `.${FRAMEWORK_NAME}`,
+        `update-state-${updateStateFileSlug(packageName)}.yaml`,
+      ),
+    );
   }
 
   protected onMissing(): Promise<UpdateState> {

package/src/tools/setup/capabilities/tokensave.ts

@@ -16,10 +16,6 @@ const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install tokensave";
 const TOKENSAVE_SCOOP_INSTALL_CMD =
   "scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave";
 
-function getTokensaveConfigPath(): string {
-  return path.join(process.env.HOME ?? "", ".tokensave", "config.toml");
-}
-
 interface CompanionOpenCodeSettings {
   mcp?: Record<string, unknown>;
   [key: string]: unknown;
@@ -132,47 +128,23 @@ async function tokensaveInstalled(repoPath: string): Promise<boolean> {
   return result.ok;
 }
 
-async function readTokensaveConfig(): Promise<string | null> {
-  try {
-    return await fs.readFile(getTokensaveConfigPath(), "utf8");
-  } catch {
-    return null;
-  }
-}
-
-async function writeTokensaveConfig(content: string): Promise<void> {
-  await fs.mkdir(path.dirname(getTokensaveConfigPath()), { recursive: true });
-  await fs.writeFile(getTokensaveConfigPath(), content, "utf8");
-}
-
-async function updateTokensaveInstalledAgents(providers: string[]): Promise<void> {
-  const content = await readTokensaveConfig();
-  if (!content) return;
-
+// Global agent integration (MCP entry, session hooks, wildcard permission grant, and
+// tokensave's own config bookkeeping) is owned by tokensave's installer — Mate never
+// hand-edits ~/.tokensave/config.toml. Runs in setup mode only; the installer is
+// idempotent, so re-running on every setup doubles as repair for stale global state.
+function installTokensaveAgentIntegrations(providers: string[], cwd: string): void {
   const agents = providers.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).sort();
-  if (agents.length === 0) return;
-
-  const existingLine = content.match(/^installed_agents\s*=\s*\[([^\]]*)\]/m);
-  if (!existingLine) return;
-
-  const existingStr = existingLine[1];
-  const existing = new Set(
-    existingStr
-      .split(",")
-      .map((s) => s.trim().replace(/^"|"$/g, ""))
-      .filter(Boolean),
-  );
-
   for (const agent of agents) {
-    existing.add(agent);
-  }
-
-  const sorted = [...existing].sort();
-  const newValue = `installed_agents = [${sorted.map((a) => `"${a}"`).join(", ")}]`;
-  const updated = content.replace(existingLine[0], newValue);
-
-  if (updated !== content) {
-    await writeTokensaveConfig(updated);
+    const result = tokensaveDeps.run(
+      ["install", "--agent", agent, "--git-hook", "no", "--wildcard-permissions"],
+      cwd,
+    );
+    if (!result.ok) {
+      const detail = result.stderr.trim();
+      process.stderr.write(
+        `tokensave: \`tokensave install --agent ${agent}\` failed${detail ? `: ${detail}` : ""} - continuing without global ${agent} integration\n`,
+      );
+    }
   }
 }
 
@@ -329,7 +301,9 @@ export function createTokensavePlugin(): CapabilityPlugin {
       if (!(await ensureTokensaveInstalled(targetPath))) {
         return;
       }
-      await updateTokensaveInstalledAgents(ctx.activeProviders);
+      if (ctx.mode === "setup") {
+        installTokensaveAgentIntegrations(ctx.activeProviders, targetPath);
+      }
     },
     async teardown(ctx) {
       if (!ctx.repoPath) return;

package/src/tools/setup/dynamic-plugins/config-resolution.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+
+import { parse } from "yaml";
+
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { pluginLocalOverridesPath } from "./paths";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Deep-merges a local override over a committed plugin config: objects merge
+ * recursively, arrays and scalars from the override replace the committed
+ * value. Either side may be absent.
+ */
+export function deepMergePluginConfig(committed: unknown, override: unknown): unknown {
+  if (override === undefined) return committed;
+  if (!isRecord(committed) || !isRecord(override)) return override;
+  const merged: Record<string, unknown> = { ...committed };
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = deepMergePluginConfig(committed[key], value);
+  }
+  return merged;
+}
+
+const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export interface InterpolationResult {
+  value: unknown;
+  /** Referenced-but-unset variable names, in first-seen order. */
+  missing: string[];
+}
+
+/**
+ * Replaces `${VAR}` occurrences in every string value with the corresponding
+ * environment value, recursively through objects and arrays. Unset variables
+ * are collected instead of substituted.
+ */
+export function interpolateEnvVars(
+  value: unknown,
+  env: Record<string, string | undefined>,
+): InterpolationResult {
+  const missing: string[] = [];
+  const visit = (node: unknown): unknown => {
+    if (typeof node === "string") {
+      return node.replace(VAR_PATTERN, (placeholder, name: string) => {
+        const resolved = env[name];
+        if (resolved === undefined) {
+          if (!missing.includes(name)) missing.push(name);
+          return placeholder;
+        }
+        return resolved;
+      });
+    }
+    if (Array.isArray(node)) return node.map(visit);
+    if (isRecord(node)) {
+      return Object.fromEntries(Object.entries(node).map(([key, entry]) => [key, visit(entry)]));
+    }
+    return node;
+  };
+  return { value: visit(value), missing };
+}
+
+/**
+ * Reads the gitignored `.mate/config/plugins.local.yaml`, a `plugins:` map
+ * keyed by package name. A missing or malformed file yields no overrides.
+ */
+export async function readLocalPluginOverrides(
+  companionPath: string,
+): Promise<Record<string, unknown>> {
+  try {
+    const raw = await fs.readFile(pluginLocalOverridesPath(companionPath), "utf8");
+    const parsed = parse(raw) as unknown;
+    if (!isRecord(parsed) || !isRecord(parsed.plugins)) return {};
+    return parsed.plugins;
+  } catch {
+    return {};
+  }
+}
+
+export type EffectivePluginConfigResult =
+  | { ok: true; config: unknown }
+  | { ok: false; missingVariables: string[] };
+
+/**
+ * Computes the config passed to a plugin factory: committed `config` block,
+ * deep-merged with the local override entry for the package, then `${VAR}`
+ * interpolated from the environment. Resolved values are never written back.
+ */
+export async function resolveEffectivePluginConfig(
+  companionPath: string,
+  declaration: PluginDeclaration,
+  env: Record<string, string | undefined> = process.env,
+): Promise<EffectivePluginConfigResult> {
+  const overrides = await readLocalPluginOverrides(companionPath);
+  const merged = deepMergePluginConfig(declaration.config, overrides[declaration.package]);
+  const { value, missing } = interpolateEnvVars(merged, env);
+  if (missing.length > 0) return { ok: false, missingVariables: missing };
+  return { ok: true, config: value };
+}

package/src/tools/setup/dynamic-plugins/host.ts

@@ -0,0 +1,51 @@
+import { getActiveDistribution } from "../../../distribution";
+import { ensureCapabilityEnabled } from "../../../cli/plugin-commands";
+import type { CapabilityPlugin, Plugin } from "../plugin";
+
+/** Host API version this core constructs. Grows only on breaking changes. */
+export const PLUGIN_API_VERSION = 1;
+
+/** Plugin API versions this core can load. */
+export const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[] = [PLUGIN_API_VERSION];
+
+/**
+ * The sole runtime surface a dynamic plugin receives into the running core.
+ *
+ * Dynamic plugin packages must not import runtime values from
+ * `@uniqbit/mate-core` — a dynamically imported plugin would resolve a second
+ * bundled copy whose module-level state was never initialized. Type-only
+ * imports are safe (erased at build); all behavior flows through this host.
+ * The surface evolves additively within an `apiVersion`.
+ */
+export interface PluginHost {
+  apiVersion: typeof PLUGIN_API_VERSION;
+  /** Identity of the running distribution. */
+  distribution: { name: string; version: string };
+  /**
+   * Verifies the named capability is enabled for the active companion,
+   * reporting guidance and setting a failing exit code when it is not.
+   */
+  ensureCapabilityEnabled(name: string): Promise<boolean>;
+}
+
+/**
+ * The factory a dynamic plugin package exports — as the default export, or as
+ * a named `createPlugin` export when no default function exists. Called once
+ * per invocation with the plugin's effective config (committed block merged
+ * with local overrides, env-interpolated). Config validation is the plugin's
+ * responsibility: throw with a descriptive message to reject it.
+ */
+export type CreatePlugin = (config: unknown, host: PluginHost) => Plugin | CapabilityPlugin;
+
+/** Builds the host bound to the running core instance. */
+export function createPluginHost(): PluginHost {
+  const distribution = getActiveDistribution();
+  return {
+    apiVersion: PLUGIN_API_VERSION,
+    distribution: {
+      name: distribution.config.name,
+      version: distribution.config.version,
+    },
+    ensureCapabilityEnabled: (name) => ensureCapabilityEnabled(name),
+  };
+}

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -0,0 +1,156 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { getActiveDistribution } from "../../../distribution";
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { PluginRegistry } from "../registry";
+import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
+import { PluginPinStore } from "./pin-store";
+
+// Packages already registered in this process; re-hydration (e.g. right after
+// an install inside the same run) only picks up plugins that failed before.
+const hydratedPackages = new Set<string>();
+
+export function resetDynamicPluginHydration(): void {
+  hydratedPackages.clear();
+}
+
+export interface HydrateDynamicPluginsDeps extends DynamicPluginLoadDeps {
+  cwd?: string;
+  /** Explicit companion context; skips quiet resolution. */
+  companionPath?: string;
+  registry?: PluginRegistry;
+  warn?: (message: string) => void;
+}
+
+function commandName(): string {
+  try {
+    return frameworkCommandName();
+  } catch {
+    return FRAMEWORK_NAME;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Quiet variant of companion resolution: never prompts, never errors. An
+ * ambiguous or absent companion means hydration is a no-op —
+ * `ensureUnambiguousCompanion` later in `main()` stays the authoritative,
+ * user-facing resolution.
+ */
+async function resolveCompanionQuietly(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<string | null> {
+  const pinned = env.MATE_ARTIFACT_PATH;
+  if (pinned) return path.resolve(pinned);
+  const resolver = new CompanionResolver(new GlobalConfigStore());
+  const resolution = await resolver.resolveWithDiagnostics(path.resolve(cwd));
+  if (resolution.ambiguousMatches.length > 1) return null;
+  if (resolution.match) return resolution.match.companionPath;
+  try {
+    // Running inside a companion directory itself.
+    await fs.access(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
+    return path.resolve(cwd);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Raw read of the companion's `plugins:` list. Deliberately avoids
+ * `ConfigStore.load()` — hydration runs on every invocation and must never
+ * create or migrate config files as a side effect.
+ */
+async function readDeclarations(companionPath: string): Promise<unknown[]> {
+  try {
+    const raw = await fs.readFile(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      "utf8",
+    );
+    const parsed = parse(raw) as unknown;
+    if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
+    return parsed.plugins;
+  } catch {
+    return [];
+  }
+}
+
+function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration; error?: string } {
+  if (!isRecord(entry) || typeof entry.package !== "string" || typeof entry.version !== "string") {
+    return { error: `ignoring malformed plugins entry: ${JSON.stringify(entry)}` };
+  }
+  const policy = entry.policy;
+  if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+    return {
+      error: `plugin "${entry.package}": policy "${String(policy)}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+    };
+  }
+  return { declaration: entry as unknown as PluginDeclaration };
+}
+
+/**
+ * Registers the companion's declared plugins into the active registry —
+ * compiled-in plugins first (they are already registered), declared order
+ * after. Runs before cap-command detection on every invocation. No-op
+ * without a companion or `plugins:` entries; all diagnostics go to stderr;
+ * never throws.
+ */
+export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}): Promise<void> {
+  const warn =
+    deps.warn ?? ((message: string) => process.stderr.write(`${commandName()}: ${message}\n`));
+  try {
+    const env = deps.env ?? process.env;
+    const companionPath =
+      deps.companionPath ?? (await resolveCompanionQuietly(deps.cwd ?? process.cwd(), env));
+    if (!companionPath) return;
+
+    const entries = await readDeclarations(companionPath);
+    if (entries.length === 0) return;
+
+    const pins = (await new PluginPinStore(companionPath).load()).plugins;
+    const registry = deps.registry ?? getActiveDistribution().registry;
+
+    for (const entry of entries) {
+      const { declaration, error } = validateDeclaration(entry);
+      if (!declaration) {
+        if (error) warn(error);
+        continue;
+      }
+      if (hydratedPackages.has(declaration.package)) continue;
+
+      // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
+      const result = await loadDynamicPlugin(companionPath, declaration, pins, deps);
+      if (!result.ok) {
+        warn(result.warning);
+        continue;
+      }
+
+      const namespace = result.plugin.cliNamespace ?? result.plugin.id;
+      const holder = registry
+        .getAll()
+        .find((existing) => (existing.cliNamespace ?? existing.id) === namespace);
+      if (holder) {
+        warn(
+          `plugin "${declaration.package}" ("${result.plugin.id}") claims cap namespace "${namespace}" already registered by "${holder.id}"; first registration wins.`,
+        );
+      }
+
+      registry.register({ plugin: result.plugin, policy: declaration.policy ?? "optional" });
+      hydratedPackages.add(declaration.package);
+    }
+  } catch (error) {
+    warn(
+      `dynamic plugin hydration failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/tools/setup/dynamic-plugins/install.ts

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { pluginInstallDir, pluginPackageRoot } from "./paths";
+import { PluginPinStore, type PluginPin } from "./pin-store";
+
+export type BunInstallRunner = (
+  installDir: string,
+) => Promise<{ ok: boolean; detail?: string }> | { ok: boolean; detail?: string };
+
+export interface PluginInstallDeps {
+  runBunInstall?: BunInstallRunner;
+}
+
+export interface PluginInstallResult {
+  package: string;
+  status: "installed" | "unchanged" | "failed";
+  resolvedVersion?: string;
+  error?: string;
+}
+
+/** Runs `bun install` in the plugin workspace, honoring the user's ambient registry/auth config. */
+function defaultBunInstall(installDir: string): { ok: boolean; detail?: string } {
+  const result = spawnSync("bun", ["install", "--silent"], { cwd: installDir, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      detail:
+        result.error?.message ??
+        result.stderr?.trim() ??
+        `bun install exited with ${result.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+async function readInstalledVersion(packageRoot: string): Promise<string | null> {
+  try {
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: string };
+    return manifest.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort integrity extraction from bun's text lockfile. The lockfile is
+ * JSONC (trailing commas); package entries are tuples whose last string is
+ * the registry integrity hash. Absence is tolerated per spec.
+ */
+async function readIntegrityFromBunLock(
+  installDir: string,
+  packageName: string,
+): Promise<string | undefined> {
+  try {
+    const raw = await fs.readFile(path.join(installDir, "bun.lock"), "utf8");
+    const parsed = JSON.parse(raw.replace(/,(\s*[}\]])/g, "$1")) as {
+      packages?: Record<string, unknown>;
+    };
+    const entry = parsed.packages?.[packageName];
+    if (!Array.isArray(entry)) return undefined;
+    return entry.find(
+      (element): element is string => typeof element === "string" && element.startsWith("sha"),
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Installs each declared plugin into `.mate/dependencies/plugins/<sanitized>/`
+ * and records `{ package, declaredVersion, resolvedVersion, integrity }` in
+ * the committed pin file. Exact/range versions resolve once and stay pinned
+ * until the declaration changes; `latest` re-resolves on every run. Matching
+ * pinned installs are left untouched.
+ */
+export async function installDeclaredPlugins(
+  companionPath: string,
+  declarations: PluginDeclaration[],
+  deps: PluginInstallDeps = {},
+): Promise<PluginInstallResult[]> {
+  const runBunInstall = deps.runBunInstall ?? defaultBunInstall;
+  const pinStore = new PluginPinStore(companionPath);
+  const previousPins = (await pinStore.load()).plugins;
+  const nextPins: PluginPin[] = [];
+  const results: PluginInstallResult[] = [];
+
+  for (const declaration of declarations) {
+    const pin = previousPins.find((candidate) => candidate.package === declaration.package);
+    const installDir = pluginInstallDir(companionPath, declaration.package);
+    const packageRoot = pluginPackageRoot(companionPath, declaration.package);
+    // oxlint-disable-next-line no-await-in-loop -- installs mutate a shared pin file sequentially
+    const installedVersion = await readInstalledVersion(packageRoot);
+
+    const pinMatches =
+      declaration.version !== "latest" &&
+      pin !== undefined &&
+      pin.declaredVersion === declaration.version &&
+      installedVersion === pin.resolvedVersion;
+    if (pinMatches) {
+      nextPins.push(pin);
+      results.push({
+        package: declaration.package,
+        status: "unchanged",
+        resolvedVersion: pin.resolvedVersion,
+      });
+      continue;
+    }
+
+    // oxlint-disable-next-line no-await-in-loop
+    const result = await installOne(installDir, packageRoot, declaration, runBunInstall);
+    results.push(result);
+    if (result.status === "installed" && result.resolvedVersion) {
+      nextPins.push({
+        package: declaration.package,
+        declaredVersion: declaration.version,
+        resolvedVersion: result.resolvedVersion,
+        // oxlint-disable-next-line no-await-in-loop
+        integrity: await readIntegrityFromBunLock(installDir, declaration.package),
+      });
+    }
+  }
+
+  // Pins mirror the declaration list; undeclared packages drop out.
+  if (JSON.stringify(nextPins) !== JSON.stringify(previousPins)) {
+    await pinStore.save({ plugins: nextPins });
+  }
+  return results;
+}
+
+async function installOne(
+  installDir: string,
+  packageRoot: string,
+  declaration: PluginDeclaration,
+  runBunInstall: BunInstallRunner,
+): Promise<PluginInstallResult> {
+  try {
+    // Fresh workspace per (re)install so `latest` and edited declarations
+    // actually re-resolve instead of reusing a stale lockfile.
+    await fs.rm(installDir, { recursive: true, force: true });
+    await fs.mkdir(installDir, { recursive: true });
+    await fs.writeFile(
+      path.join(installDir, "package.json"),
+      JSON.stringify(
+        { private: true, dependencies: { [declaration.package]: declaration.version } },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    const outcome = await runBunInstall(installDir);
+    if (!outcome.ok) {
+      throw new Error(outcome.detail ?? "bun install failed");
+    }
+    const resolvedVersion = await readInstalledVersion(packageRoot);
+    if (!resolvedVersion) {
+      throw new Error(`installed tree is missing ${declaration.package}/package.json`);
+    }
+    return { package: declaration.package, status: "installed", resolvedVersion };
+  } catch (error) {
+    return {
+      package: declaration.package,
+      status: "failed",
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/tools/setup/dynamic-plugins/loader.ts

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { Plugin } from "../plugin";
+import { resolveEffectivePluginConfig } from "./config-resolution";
+import {
+  createPluginHost,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+  type CreatePlugin,
+  type PluginHost,
+} from "./host";
+import { pluginPackageRoot } from "./paths";
+import type { PluginPin } from "./pin-store";
+
+interface PluginManifest {
+  version?: string;
+  main?: string;
+  module?: string;
+  exports?: unknown;
+  mate?: { pluginApiVersion?: unknown };
+}
+
+export type DynamicPluginLoadResult = { ok: true; plugin: Plugin } | { ok: false; warning: string };
+
+export interface DynamicPluginLoadDeps {
+  env?: Record<string, string | undefined>;
+  importModule?: (specifier: string) => Promise<Record<string, unknown>>;
+  host?: PluginHost;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function commandName(): string {
+  try {
+    return frameworkCommandName();
+  } catch {
+    return FRAMEWORK_NAME;
+  }
+}
+
+function resolveEntryFromExports(exportsField: unknown): string | undefined {
+  if (typeof exportsField === "string") return exportsField;
+  if (!isRecord(exportsField)) return undefined;
+  const dot = "." in exportsField ? exportsField["."] : exportsField;
+  if (typeof dot === "string") return dot;
+  if (!isRecord(dot)) return undefined;
+  for (const condition of ["bun", "import", "default", "require"]) {
+    const candidate = dot[condition];
+    if (typeof candidate === "string") return candidate;
+    if (isRecord(candidate) && typeof candidate.default === "string") return candidate.default;
+  }
+  return undefined;
+}
+
+/**
+ * Loads one declared plugin from its installed tree: pin verification, API
+ * version gate before import, dynamic import, factory resolution, effective
+ * config, factory invocation. Every failure class returns a single warning
+ * instead of throwing, so one broken plugin never takes down the CLI.
+ */
+export async function loadDynamicPlugin(
+  companionPath: string,
+  declaration: PluginDeclaration,
+  pins: PluginPin[],
+  deps: DynamicPluginLoadDeps = {},
+): Promise<DynamicPluginLoadResult> {
+  const name = declaration.package;
+  const packageRoot = pluginPackageRoot(companionPath, name);
+
+  let manifest: PluginManifest;
+  try {
+    manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as PluginManifest;
+  } catch {
+    return {
+      ok: false,
+      warning: `plugin "${name}" is not installed; run \`${commandName()} install\`.`,
+    };
+  }
+
+  const pin = pins.find((candidate) => candidate.package === name);
+  if (!pin) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has no recorded pin; run \`${commandName()} install\`.`,
+    };
+  }
+  if (pin.declaredVersion !== declaration.version) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" declares version "${declaration.version}" but was pinned from "${pin.declaredVersion}"; run \`${commandName()} install\`.`,
+    };
+  }
+  if (manifest.version !== pin.resolvedVersion) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has version ${manifest.version ?? "unknown"} installed but ${pin.resolvedVersion} pinned; run \`${commandName()} install\`.`,
+    };
+  }
+
+  // Version negotiation happens before any plugin code executes.
+  const apiVersion = manifest.mate?.pluginApiVersion ?? 1;
+  if (typeof apiVersion !== "number" || !SUPPORTED_PLUGIN_API_VERSIONS.includes(apiVersion)) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" requires plugin API version ${String(apiVersion)}; this CLI supports: ${SUPPORTED_PLUGIN_API_VERSIONS.join(", ")}.`,
+    };
+  }
+
+  const configResult = await resolveEffectivePluginConfig(companionPath, declaration, deps.env);
+  if (!configResult.ok) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" references unset environment variable${configResult.missingVariables.length > 1 ? "s" : ""}: ${configResult.missingVariables.join(", ")}.`,
+    };
+  }
+
+  const entryRelative =
+    resolveEntryFromExports(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";
+  const entryPath = path.resolve(packageRoot, entryRelative);
+  const importModule =
+    deps.importModule ??
+    ((specifier: string) => import(specifier) as Promise<Record<string, unknown>>);
+
+  let moduleExports: Record<string, unknown>;
+  try {
+    moduleExports = await importModule(pathToFileURL(entryPath).href);
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" could not be imported: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  const factory =
+    typeof moduleExports.default === "function"
+      ? (moduleExports.default as CreatePlugin)
+      : typeof moduleExports.createPlugin === "function"
+        ? (moduleExports.createPlugin as CreatePlugin)
+        : undefined;
+  if (!factory) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" has no factory export; expected a default-exported function or a named createPlugin export.`,
+    };
+  }
+
+  let plugin: Plugin;
+  try {
+    plugin = factory(configResult.config, deps.host ?? createPluginHost());
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" rejected its configuration: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  if (!isRecord(plugin) || typeof plugin.id !== "string" || plugin.id.length === 0) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" returned an invalid plugin object (missing id).`,
+    };
+  }
+  return { ok: true, plugin };
+}

package/src/tools/setup/dynamic-plugins/paths.ts

@@ -0,0 +1,42 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+
+/** Flattens an npm package name into a single directory segment. */
+export function sanitizePluginDirName(packageName: string): string {
+  return packageName.replace(/^@/, "").replace(/\//g, "-");
+}
+
+export function dynamicPluginsRoot(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "dependencies", "plugins");
+}
+
+/** Per-plugin install workspace holding a private package.json and node_modules. */
+export function pluginInstallDir(companionPath: string, packageName: string): string {
+  return path.join(dynamicPluginsRoot(companionPath), sanitizePluginDirName(packageName));
+}
+
+/** Root of the installed plugin package itself. */
+export function pluginPackageRoot(companionPath: string, packageName: string): string {
+  return path.join(
+    pluginInstallDir(companionPath, packageName),
+    "node_modules",
+    ...packageName.split("/"),
+  );
+}
+
+/** Committed pin file recording resolved plugin versions. */
+export function pluginPinFilePath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.lock.yaml");
+}
+
+/** Gitignored per-machine override file deep-merged over committed plugin config. */
+export function pluginLocalOverridesPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.local.yaml");
+}
+
+/** Companion-relative gitignore entry for the local override file. */
+export const PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/config/plugins.local.yaml`;
+
+/** Companion-relative gitignore entry for installed plugin trees (regenerated by install). */
+export const PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/dependencies/plugins/`;

package/src/tools/setup/dynamic-plugins/pin-store.ts

@@ -0,0 +1,30 @@
+import { YamlFileStore } from "../../../lib/orchestrator/yaml-file-store";
+import { pluginPinFilePath } from "./paths";
+
+/** Committed record of one declared plugin's resolved install. */
+export interface PluginPin {
+  package: string;
+  declaredVersion: string;
+  resolvedVersion: string;
+  integrity?: string;
+}
+
+export interface PluginPinFile {
+  plugins: PluginPin[];
+}
+
+export class PluginPinStore extends YamlFileStore<PluginPinFile> {
+  constructor(companionPath: string) {
+    super(pluginPinFilePath(companionPath));
+  }
+
+  override async load(): Promise<PluginPinFile> {
+    const parsed = await super.load();
+    return { plugins: Array.isArray(parsed?.plugins) ? parsed.plugins : [] };
+  }
+
+  protected onMissing(): Promise<PluginPinFile> {
+    // The pin file appears only once install records a resolved plugin.
+    return Promise.resolve({ plugins: [] });
+  }
+}

package/src/tools/setup/plugins/gitignore.ts

@@ -1,4 +1,8 @@
 import { getActiveDistribution } from "../../../distribution";
+import {
+  PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY,
+  PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY,
+} from "../dynamic-plugins/paths";
 import type { Plugin, SetupContext } from "../plugin";
 
 const MANAGED_START = (name: string) => `# ${name} managed: start`;
@@ -55,9 +59,16 @@ export async function writeManagedGitignoreBlock(
 }
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
-  return plugins
+  const entries = plugins
     .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))
     .flatMap((p) => p.gitignoreEntries?.(ctx) ?? []);
+  // Dynamic-plugin loading artifacts: the local override file and installed
+  // trees never version; the pin file (plugins.lock.yaml) stays committed and
+  // is deliberately not listed here.
+  if (ctx.config.plugins?.length) {
+    entries.push(PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY, PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY);
+  }
+  return entries;
 }
 
 export function createGitignorePlugin(

package/src/tools/setup.ts

@@ -31,6 +31,8 @@ import { createUvPlugin } from "./setup/package-managers/uv";
 import type { PackageManagerSetupDeps } from "./setup/package-managers/uv";
 import { applyRequiredSelectionsToConfig } from "./setup/policy";
 import { invalidateInstallState } from "../lib/install";
+import { hydrateDynamicPlugins } from "./setup/dynamic-plugins/hydrate";
+import { installDeclaredPlugins } from "./setup/dynamic-plugins/install";
 import {
   buildSetupInstallationPlan,
   executeSetupInstallationPlan,
@@ -181,6 +183,19 @@ export async function executeSetup(
   await configStore.save(config);
 
   const companionPath = path.resolve(cwd);
+  // Declared plugin packages install and hydrate before the setup plan runs,
+  // so a fresh clone reaches a fully applied state from one setup run
+  // (install → load → plan).
+  if (config.plugins?.length) {
+    for (const result of await installDeclaredPlugins(companionPath, config.plugins)) {
+      if (result.status === "failed") {
+        process.stderr.write(
+          `${FRAMEWORK_NAME}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+        );
+      }
+    }
+    await hydrateDynamicPlugins({ companionPath });
+  }
   await applySetupCompatibilities(companionPath, config, "setup");
   await invalidateInstallState({ kind: "companion", companionPath });