@moxxy/core 0.3.0

package/src/plugins/loader.ts

@@ -0,0 +1,79 @@
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { Plugin, ResolvedPluginManifest } from '@moxxy/sdk';
+import type { PluginLoader } from './host.js';
+
+export interface JitiLoaderOptions {
+  readonly cwd: string;
+  readonly cacheBust?: () => string;
+}
+
+let jitiInstance: ((id: string) => unknown) | null = null;
+
+async function getJiti(cwd: string): Promise<((id: string) => unknown) | null> {
+  if (jitiInstance) return jitiInstance;
+  try {
+    const mod = await import('jiti');
+    const factory = (mod as { createJiti?: (cwd: string, opts?: unknown) => (id: string) => unknown; default?: (cwd: string, opts?: unknown) => (id: string) => unknown }).createJiti ?? (mod as { default?: (cwd: string, opts?: unknown) => (id: string) => unknown }).default;
+    if (!factory) return null;
+    jitiInstance = factory(cwd, { interopDefault: true });
+    return jitiInstance;
+  } catch {
+    return null;
+  }
+}
+
+export function createPluginLoader(opts: JitiLoaderOptions): PluginLoader {
+  return {
+    async load(manifest: ResolvedPluginManifest): Promise<Plugin> {
+      const entry = path.resolve(manifest.packagePath, manifest.entry);
+      const isTs = entry.endsWith('.ts') || entry.endsWith('.tsx');
+
+      let mod: unknown;
+      if (isTs) {
+        const jiti = await getJiti(opts.cwd);
+        if (!jiti) {
+          throw new Error(
+            `Cannot load .ts plugin entry without jiti: ${entry}. Install 'jiti' as a dependency.`,
+          );
+        }
+        mod = jiti(entry);
+      } else {
+        const bust = opts.cacheBust?.() ?? `${Date.now()}-${Math.random()}`;
+        const url = `${pathToFileURL(entry).href}?v=${bust}`;
+        mod = await import(url);
+      }
+
+      const plugin = extractPlugin(mod);
+      if (!plugin) {
+        throw new Error(
+          `Plugin entry did not export a valid Plugin (default export with __moxxy === 'plugin'): ${entry}`,
+        );
+      }
+      // The runtime-reported version is the package.json version — the single
+      // source of truth. Plugin authors hardcode a placeholder `version` in
+      // definePlugin (commonly '0.0.0'), so stamp the manifest's packageVersion
+      // here; otherwise `moxxy plugins list` and PluginRegisteredEvent lie.
+      if (manifest.packageVersion && plugin.version !== manifest.packageVersion) {
+        return Object.freeze({ ...plugin, version: manifest.packageVersion });
+      }
+      return plugin;
+    },
+  };
+}
+
+function extractPlugin(mod: unknown): Plugin | null {
+  if (!mod || typeof mod !== 'object') return null;
+  const candidates: unknown[] = [
+    (mod as { default?: unknown }).default,
+    (mod as { default?: { default?: unknown } }).default?.default,
+    mod,
+    (mod as { plugin?: unknown }).plugin,
+  ];
+  for (const c of candidates) {
+    if (c && typeof c === 'object' && (c as { __moxxy?: string }).__moxxy === 'plugin') {
+      return c as Plugin;
+    }
+  }
+  return null;
+}

package/src/plugins/package-requirements.ts

@@ -0,0 +1,50 @@
+import { createRequire } from 'node:module';
+import { promises as fs } from 'node:fs';
+import { moxxyPackageSchema, type MoxxyRequirement } from '@moxxy/sdk';
+
+/**
+ * Read `moxxy.requirements` from a package's `package.json`, resolved by
+ * name from the given working directory. Returns an empty array when:
+ *   - the package can't be resolved (not installed in the cwd's resolution path)
+ *   - the package has no `moxxy` block
+ *   - the `moxxy` block exists but declares no requirements
+ *   - the `moxxy` block fails schema validation
+ *
+ * Errors are deliberately swallowed because this is used during boot
+ * for every static builtin: a missing or malformed package.json on one
+ * builtin shouldn't crash the CLI. The plugin host's registration gate
+ * still rejects plugins whose declared requirements aren't satisfied.
+ */
+export async function readPackageMoxxyRequirements(
+  packageName: string,
+  fromDir: string,
+): Promise<ReadonlyArray<MoxxyRequirement>> {
+  const pkgJsonPath = resolvePackageJson(packageName, fromDir);
+  if (!pkgJsonPath) return [];
+  let raw: string;
+  try {
+    raw = await fs.readFile(pkgJsonPath, 'utf8');
+  } catch {
+    return [];
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const moxxyBlock = (parsedJson as { moxxy?: unknown }).moxxy;
+  if (!moxxyBlock) return [];
+  const parsed = moxxyPackageSchema.safeParse(moxxyBlock);
+  if (!parsed.success) return [];
+  return parsed.data.requirements ?? [];
+}
+
+function resolvePackageJson(packageName: string, fromDir: string): string | null {
+  const require_ = createRequire(`${fromDir.replace(/\/+$/, '')}/`);
+  try {
+    return require_.resolve(`${packageName}/package.json`);
+  } catch {
+    return null;
+  }
+}

package/src/plugins/registry-kinds.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  defineAgent,
+  defineCacheStrategy,
+  defineChannel,
+  defineCommand,
+  defineCompactor,
+  defineEmbedder,
+  defineMode,
+  definePlugin,
+  defineProvider,
+  defineSurface,
+  defineSynthesizer,
+  defineTool,
+  defineTranscriber,
+  defineTunnelProvider,
+  defineViewRenderer,
+  defineWorkflowExecutor,
+  type Isolator,
+} from '@moxxy/sdk';
+import { silentLogger } from '../logger.js';
+import { ToolRegistryImpl } from '../registries/tools.js';
+import { ProviderRegistry } from '../registries/providers.js';
+import { ModeRegistry } from '../registries/modes.js';
+import { CompactorRegistry } from '../registries/compactors.js';
+import { CacheStrategyRegistry } from '../registries/cache-strategies.js';
+import { ViewRendererRegistry } from '../registries/view-renderers.js';
+import { TunnelProviderRegistry } from '../registries/tunnel-providers.js';
+import { ChannelRegistryImpl } from '../registries/channels.js';
+import { SurfaceRegistryImpl } from '../registries/surfaces.js';
+import { AgentRegistry } from '../registries/agents.js';
+import { CommandRegistry } from '../registries/commands.js';
+import { TranscriberRegistry } from '../registries/transcribers.js';
+import { SynthesizerRegistry } from '../registries/synthesizers.js';
+import { EmbedderRegistry } from '../registries/embedders.js';
+import { IsolatorRegistry } from '../registries/isolators.js';
+import { WorkflowExecutorRegistry } from '../registries/workflow-executors.js';
+import { RequirementRegistry } from '../requirements.js';
+import { HookDispatcherImpl } from './lifecycle.js';
+import { PluginHost } from './host.js';
+import { REGISTRY_KINDS } from './registry-kinds.js';
+
+// One minimal def per contribution kind, keyed by REGISTRY_KINDS `kind`.
+const isolator: Isolator = {
+  name: 'iso-1',
+  strength: 'none',
+  run: async (_call, handler) => handler(undefined),
+};
+
+const everyKindPlugin = definePlugin({
+  name: 'every-kind',
+  tools: [defineTool({ name: 'tool-1', description: '', inputSchema: z.any(), handler: () => null })],
+  providers: [
+    defineProvider({
+      name: 'prov-1',
+      models: [],
+      createClient: () => ({ name: 'prov-1', models: [], stream: async function* () {}, countTokens: async () => 0 }),
+    }),
+  ],
+  modes: [defineMode({ name: 'mode-1', run: async function* () {} })],
+  compactors: [defineCompactor({ name: 'comp-1', shouldCompact: () => false, compact: async () => ({}) as never })],
+  cacheStrategies: [defineCacheStrategy({ name: 'cs-1', plan: () => [] })],
+  viewRenderers: [defineViewRenderer({ name: 'vr-1', allowList: [], parse: () => ({ ok: false, errors: [] }), validate: () => [] })],
+  tunnelProviders: [defineTunnelProvider({ name: 'tp-1', open: () => Promise.resolve({ url: 'http://x', close: () => Promise.resolve() }) })],
+  channels: [defineChannel({ name: 'chan-1', description: '', create: () => ({ start: async () => {}, stop: async () => {} }) as never })],
+  surfaces: [defineSurface({ kind: 'surf-1', open: () => ({ kind: 'surf-1' }) as never })],
+  agents: [defineAgent({ name: 'agent-1', description: '' })],
+  commands: [defineCommand({ name: 'cmd-1', description: '', handler: () => ({ text: '' }) as never })],
+  transcribers: [defineTranscriber({ name: 'tr-1', createClient: () => ({}) as never })],
+  synthesizers: [defineSynthesizer({ name: 'synth-1', create: () => ({}) as never })],
+  embedders: [defineEmbedder({ name: 'emb-1', createClient: () => ({}) as never })],
+  isolators: [isolator],
+  workflowExecutors: [defineWorkflowExecutor({ name: 'wfx-1', run: async () => ({}) as never })],
+});
+
+function makeHost() {
+  const registries = {
+    tools: new ToolRegistryImpl({ logger: silentLogger, cwd: '/tmp' }),
+    providers: new ProviderRegistry(),
+    modes: new ModeRegistry(),
+    compactors: new CompactorRegistry(),
+    cacheStrategies: new CacheStrategyRegistry(),
+    viewRenderers: new ViewRendererRegistry(),
+    tunnelProviders: new TunnelProviderRegistry(),
+    channels: new ChannelRegistryImpl(),
+    surfaces: new SurfaceRegistryImpl(),
+    agents: new AgentRegistry(),
+    commands: new CommandRegistry(),
+    transcribers: new TranscriberRegistry(),
+    synthesizers: new SynthesizerRegistry(),
+    embedders: new EmbedderRegistry(),
+    isolators: new IsolatorRegistry(),
+    workflowExecutors: new WorkflowExecutorRegistry(),
+  };
+  const requirements = new RequirementRegistry({
+    tools: registries.tools,
+    providers: registries.providers,
+    modes: registries.modes,
+    compactors: registries.compactors,
+    channels: registries.channels,
+    agents: registries.agents,
+    commands: registries.commands,
+    transcribers: registries.transcribers,
+  });
+  const dispatcher = new HookDispatcherImpl({ logger: silentLogger });
+  const host = new PluginHost({
+    cwd: '/tmp',
+    logger: silentLogger,
+    ...registries,
+    requirements,
+    dispatcher,
+  });
+  // Map each REGISTRY_KINDS entry to its concrete registry instance so the
+  // assertions below cover every kind without a hand-maintained second list.
+  const byKind: Record<string, { list(): ReadonlyArray<unknown> }> = {
+    tool: registries.tools,
+    provider: registries.providers,
+    mode: registries.modes,
+    compactor: registries.compactors,
+    cacheStrategy: registries.cacheStrategies,
+    viewRenderer: registries.viewRenderers,
+    tunnelProvider: registries.tunnelProviders,
+    channel: registries.channels,
+    surface: registries.surfaces,
+    agent: registries.agents,
+    command: registries.commands,
+    transcriber: registries.transcribers,
+    synthesizer: registries.synthesizers,
+    embedder: registries.embedders,
+    isolator: registries.isolators,
+    workflowExecutor: registries.workflowExecutors,
+  };
+  return { host, byKind };
+}
+
+describe('PluginHost register/unregister lockstep (REGISTRY_KINDS)', () => {
+  it('the table covers every kind the test exercises', () => {
+    const { byKind } = makeHost();
+    // Guards that adding a REGISTRY_KINDS entry without updating this test (or
+    // vice-versa) is caught — the unload-leak assertion below is only as strong
+    // as this coverage.
+    expect(REGISTRY_KINDS.map((k) => k.kind).sort()).toEqual(Object.keys(byKind).sort());
+  });
+
+  it('registerStatic populates every registry kind', () => {
+    const { host, byKind } = makeHost();
+    host.registerStatic(everyKindPlugin);
+    for (const kind of REGISTRY_KINDS) {
+      expect(byKind[kind.kind]!.list().length, `${kind.kind} should be populated`).toBe(1);
+    }
+  });
+
+  it('unload reverses register for EVERY kind — no registry left populated', async () => {
+    const { host, byKind } = makeHost();
+    host.registerStatic(everyKindPlugin);
+    await host.unload('every-kind');
+    for (const kind of REGISTRY_KINDS) {
+      expect(byKind[kind.kind]!.list().length, `${kind.kind} should be empty after unload`).toBe(0);
+    }
+  });
+});

package/src/plugins/registry-kinds.ts

@@ -0,0 +1,210 @@
+import type {
+  AgentDef,
+  CacheStrategyDef,
+  ChannelDef,
+  CommandDef,
+  CompactorDef,
+  ModeDef,
+  Plugin,
+  ProviderDef,
+  SurfaceDef,
+  ToolDef,
+  TranscriberDef,
+  SynthesizerDef,
+  EmbedderDef,
+  Isolator,
+  ViewRendererDef,
+  TunnelProviderDef,
+  WorkflowExecutorDef,
+} from '@moxxy/sdk';
+import type { PluginHostOptions } from './host-options.js';
+
+/**
+ * The per-registry record of the names a loaded plugin contributed. Keyed by
+ * the {@link LoadedRecord} field each kind writes to. PluginHost stores one
+ * `LoadedRecord` per loaded plugin so `unload` knows exactly which names to
+ * unregister from each registry.
+ */
+export interface RegistryNameRecord {
+  readonly toolNames: ReadonlyArray<string>;
+  readonly providerNames: ReadonlyArray<string>;
+  readonly modeNames: ReadonlyArray<string>;
+  readonly compactorNames: ReadonlyArray<string>;
+  readonly cacheStrategyNames: ReadonlyArray<string>;
+  readonly viewRendererNames: ReadonlyArray<string>;
+  readonly tunnelProviderNames: ReadonlyArray<string>;
+  readonly channelNames: ReadonlyArray<string>;
+  readonly surfaceNames: ReadonlyArray<string>;
+  readonly agentNames: ReadonlyArray<string>;
+  readonly commandNames: ReadonlyArray<string>;
+  readonly transcriberNames: ReadonlyArray<string>;
+  readonly synthesizerNames: ReadonlyArray<string>;
+  readonly embedderNames: ReadonlyArray<string>;
+  readonly isolatorNames: ReadonlyArray<string>;
+  readonly workflowExecutorNames: ReadonlyArray<string>;
+}
+
+/**
+ * A single contribution kind, mapping a plugin field + registry to the
+ * register / unregister / name-extraction operations PluginHost performs for
+ * it. Driving register and unregister from this one table keeps the two sides
+ * in lockstep — adding a registry kind is one entry, not edits to two parallel
+ * 16-line lists.
+ *
+ * `TDef` is the contribution def type for this kind. The table is declared with
+ * heterogeneous defs, so it is widened to `RegistryKind<any>` for iteration;
+ * each entry's closures stay individually type-checked against their own def.
+ */
+export interface RegistryKind<TDef> {
+  /** Stable identifier for the kind (used by tests/diagnostics). */
+  readonly kind: string;
+  /** {@link RegistryNameRecord} field this kind writes its names to. */
+  readonly recordField: keyof RegistryNameRecord;
+  /** The defs this plugin contributes for this kind. */
+  readonly defs: (plugin: Plugin) => ReadonlyArray<TDef>;
+  /** Extract the registry key from a def (mostly `.name`; surfaces use `.kind`). */
+  readonly nameOf: (def: TDef) => string;
+  /** Register a single def into its registry (uses `register` or `replace`). */
+  readonly register: (opts: PluginHostOptions, def: TDef) => void;
+  /** Remove a previously-registered name from its registry. */
+  readonly unregister: (opts: PluginHostOptions, name: string) => void;
+}
+
+/**
+ * The authoritative ordered list of contribution kinds. The ORDER here is the
+ * exact register order `applyPlugin` used and the exact unregister order
+ * `unload` used; preserve it when editing.
+ */
+export const REGISTRY_KINDS: ReadonlyArray<RegistryKind<unknown>> = [
+  {
+    kind: 'tool',
+    recordField: 'toolNames',
+    defs: (p) => p.tools ?? [],
+    nameOf: (t: ToolDef) => t.name,
+    register: (o, t: ToolDef) => o.tools.register(t),
+    unregister: (o, n) => o.tools.unregister(n),
+  } satisfies RegistryKind<ToolDef>,
+  {
+    kind: 'provider',
+    recordField: 'providerNames',
+    defs: (p) => p.providers ?? [],
+    nameOf: (d: ProviderDef) => d.name,
+    register: (o, d: ProviderDef) => o.providers.register(d),
+    unregister: (o, n) => o.providers.unregister(n),
+  } satisfies RegistryKind<ProviderDef>,
+  {
+    kind: 'mode',
+    recordField: 'modeNames',
+    defs: (p) => p.modes ?? [],
+    nameOf: (m: ModeDef) => m.name,
+    register: (o, m: ModeDef) => o.modes.register(m),
+    unregister: (o, n) => o.modes.unregister(n),
+  } satisfies RegistryKind<ModeDef>,
+  {
+    kind: 'compactor',
+    recordField: 'compactorNames',
+    defs: (p) => p.compactors ?? [],
+    nameOf: (c: CompactorDef) => c.name,
+    register: (o, c: CompactorDef) => o.compactors.register(c),
+    unregister: (o, n) => o.compactors.unregister(n),
+  } satisfies RegistryKind<CompactorDef>,
+  {
+    kind: 'cacheStrategy',
+    recordField: 'cacheStrategyNames',
+    defs: (p) => p.cacheStrategies ?? [],
+    nameOf: (c: CacheStrategyDef) => c.name,
+    register: (o, c: CacheStrategyDef) => o.cacheStrategies.register(c),
+    unregister: (o, n) => o.cacheStrategies.unregister(n),
+  } satisfies RegistryKind<CacheStrategyDef>,
+  {
+    kind: 'viewRenderer',
+    recordField: 'viewRendererNames',
+    defs: (p) => p.viewRenderers ?? [],
+    nameOf: (v: ViewRendererDef) => v.name,
+    // viewRenderers use `replace` (override-allowed) on the register side.
+    register: (o, v: ViewRendererDef) => o.viewRenderers.replace(v),
+    unregister: (o, n) => o.viewRenderers.unregister(n),
+  } satisfies RegistryKind<ViewRendererDef>,
+  {
+    kind: 'tunnelProvider',
+    recordField: 'tunnelProviderNames',
+    defs: (p) => p.tunnelProviders ?? [],
+    nameOf: (t: TunnelProviderDef) => t.name,
+    // tunnelProviders use `replace` (override-allowed) on the register side.
+    register: (o, t: TunnelProviderDef) => o.tunnelProviders.replace(t),
+    unregister: (o, n) => o.tunnelProviders.unregister(n),
+  } satisfies RegistryKind<TunnelProviderDef>,
+  {
+    kind: 'channel',
+    recordField: 'channelNames',
+    defs: (p) => p.channels ?? [],
+    nameOf: (c: ChannelDef) => c.name,
+    register: (o, c: ChannelDef) => o.channels.register(c),
+    unregister: (o, n) => o.channels.unregister(n),
+  } satisfies RegistryKind<ChannelDef>,
+  {
+    kind: 'surface',
+    recordField: 'surfaceNames',
+    defs: (p) => p.surfaces ?? [],
+    // surfaces are keyed by `.kind`, not `.name`.
+    nameOf: (s: SurfaceDef) => s.kind,
+    register: (o, s: SurfaceDef) => o.surfaces.register(s),
+    unregister: (o, n) => o.surfaces.unregister(n),
+  } satisfies RegistryKind<SurfaceDef>,
+  {
+    kind: 'agent',
+    recordField: 'agentNames',
+    defs: (p) => p.agents ?? [],
+    nameOf: (a: AgentDef) => a.name,
+    register: (o, a: AgentDef) => o.agents.register(a),
+    unregister: (o, n) => o.agents.unregister(n),
+  } satisfies RegistryKind<AgentDef>,
+  {
+    kind: 'command',
+    recordField: 'commandNames',
+    defs: (p) => p.commands ?? [],
+    nameOf: (c: CommandDef) => c.name,
+    register: (o, c: CommandDef) => o.commands.register(c),
+    unregister: (o, n) => o.commands.unregister(n),
+  } satisfies RegistryKind<CommandDef>,
+  {
+    kind: 'transcriber',
+    recordField: 'transcriberNames',
+    defs: (p) => p.transcribers ?? [],
+    nameOf: (t: TranscriberDef) => t.name,
+    register: (o, t: TranscriberDef) => o.transcribers.register(t),
+    unregister: (o, n) => o.transcribers.unregister(n),
+  } satisfies RegistryKind<TranscriberDef>,
+  {
+    kind: 'synthesizer',
+    recordField: 'synthesizerNames',
+    defs: (p) => p.synthesizers ?? [],
+    nameOf: (s: SynthesizerDef) => s.name,
+    register: (o, s: SynthesizerDef) => o.synthesizers.register(s),
+    unregister: (o, n) => o.synthesizers.unregister(n),
+  } satisfies RegistryKind<SynthesizerDef>,
+  {
+    kind: 'embedder',
+    recordField: 'embedderNames',
+    defs: (p) => p.embedders ?? [],
+    nameOf: (e: EmbedderDef) => e.name,
+    register: (o, e: EmbedderDef) => o.embedders.register(e),
+    unregister: (o, n) => o.embedders.unregister(n),
+  } satisfies RegistryKind<EmbedderDef>,
+  {
+    kind: 'isolator',
+    recordField: 'isolatorNames',
+    defs: (p) => p.isolators ?? [],
+    nameOf: (i: Isolator) => i.name,
+    register: (o, i: Isolator) => o.isolators.register(i),
+    unregister: (o, n) => o.isolators.unregister(n),
+  } satisfies RegistryKind<Isolator>,
+  {
+    kind: 'workflowExecutor',
+    recordField: 'workflowExecutorNames',
+    defs: (p) => p.workflowExecutors ?? [],
+    nameOf: (w: WorkflowExecutorDef) => w.name,
+    register: (o, w: WorkflowExecutorDef) => o.workflowExecutors.register(w),
+    unregister: (o, n) => o.workflowExecutors.unregister(n),
+  } satisfies RegistryKind<WorkflowExecutorDef>,
+] as ReadonlyArray<RegistryKind<unknown>>;

package/src/plugins/toposort.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import type { ResolvedPluginManifest } from '@moxxy/sdk';
+import { PluginCycleError, toposortPluginManifests } from './toposort.js';
+
+const m = (
+  packageName: string,
+  deps: ReadonlyArray<string> = [],
+  extras: ReadonlyArray<{ kind: 'runtime' | 'provider'; name: string }> = [],
+): ResolvedPluginManifest => ({
+  entry: './dist/index.js',
+  packageName,
+  packageVersion: '0.0.0',
+  packagePath: `/tmp/${packageName}`,
+  requirements: [
+    ...deps.map((d) => ({ kind: 'plugin' as const, name: d })),
+    ...extras,
+  ],
+});
+
+describe('toposortPluginManifests', () => {
+  it('orders dependencies before dependents', () => {
+    const ordered = toposortPluginManifests([
+      m('dependent', ['base']),
+      m('base'),
+    ]);
+
+    expect(ordered.map((p) => p.packageName)).toEqual(['base', 'dependent']);
+  });
+
+  it('handles a longer chain', () => {
+    const ordered = toposortPluginManifests([
+      m('c', ['b']),
+      m('a'),
+      m('b', ['a']),
+    ]);
+
+    expect(ordered.map((p) => p.packageName)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('ignores non-plugin requirement kinds', () => {
+    const ordered = toposortPluginManifests([
+      m('only-runtime', [], [{ kind: 'runtime', name: 'auth:ready' }]),
+      m('only-provider', [], [{ kind: 'provider', name: 'openai-codex' }]),
+    ]);
+
+    expect(ordered.map((p) => p.packageName).sort()).toEqual(['only-provider', 'only-runtime']);
+  });
+
+  it('leaves unknown plugin dependencies in place for the readiness gate to reject later', () => {
+    const ordered = toposortPluginManifests([
+      m('dependent', ['unknown']),
+      m('other'),
+    ]);
+
+    expect(ordered.map((p) => p.packageName).sort()).toEqual(['dependent', 'other']);
+  });
+
+  it('throws PluginCycleError on a cycle', () => {
+    expect(() =>
+      toposortPluginManifests([
+        m('a', ['b']),
+        m('b', ['a']),
+      ]),
+    ).toThrow(PluginCycleError);
+  });
+});

package/src/plugins/toposort.ts

@@ -0,0 +1,69 @@
+import type { MoxxyRequirement, ResolvedPluginManifest } from '@moxxy/sdk';
+
+/**
+ * Topological sort of discovered plugin manifests by their static
+ * `requirements` (from `package.json#moxxy.requirements`). Only
+ * `kind: 'plugin'` requirements participate; everything else (runtime,
+ * provider-state, etc.) is irrelevant to load order.
+ *
+ * Behavior:
+ * - A manifest whose required plugin name doesn't appear in `manifests`
+ *   is left in place — the readiness check in PluginHost will reject it
+ *   later. Toposort doesn't pre-judge.
+ * - Optional requirements (`optional: true`) are treated as soft edges:
+ *   if the target is present we order around it; if not, we skip the
+ *   edge silently.
+ * - Cycles throw `PluginCycleError` with the participating plugin names
+ *   so the caller can surface a useful diagnostic instead of silently
+ *   loading in an arbitrary order.
+ */
+export class PluginCycleError extends Error {
+  constructor(readonly cycle: ReadonlyArray<string>) {
+    super(`Plugin requirement cycle detected: ${cycle.join(' -> ')}`);
+    this.name = 'PluginCycleError';
+  }
+}
+
+export function toposortPluginManifests(
+  manifests: ReadonlyArray<ResolvedPluginManifest>,
+): ReadonlyArray<ResolvedPluginManifest> {
+  const byPackage = new Map<string, ResolvedPluginManifest>();
+  for (const m of manifests) byPackage.set(m.packageName, m);
+
+  const order: ResolvedPluginManifest[] = [];
+  const visited = new Set<string>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+
+  const visit = (name: string): void => {
+    if (visited.has(name)) return;
+    if (onStack.has(name)) {
+      const startIdx = stack.indexOf(name);
+      throw new PluginCycleError(stack.slice(startIdx).concat(name));
+    }
+    const manifest = byPackage.get(name);
+    if (!manifest) return; // unknown dep — leave for readiness gate
+
+    onStack.add(name);
+    stack.push(name);
+    for (const dep of pluginDeps(manifest.requirements)) visit(dep);
+    onStack.delete(name);
+    stack.pop();
+    visited.add(name);
+    order.push(manifest);
+  };
+
+  for (const m of manifests) visit(m.packageName);
+  return order;
+}
+
+function pluginDeps(
+  requirements: ReadonlyArray<MoxxyRequirement> | undefined,
+): ReadonlyArray<string> {
+  if (!requirements) return [];
+  const out: string[] = [];
+  for (const req of requirements) {
+    if (req.kind === 'plugin') out.push(req.name);
+  }
+  return out;
+}