@north-light/crouter 0.3.186 → 0.3.188

package/dist/core/config.js

@@ -5,6 +5,7 @@ import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
 import { profileRoot } from './profiles/manifest.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
@@ -264,42 +265,20 @@ function mergeSpawnEnv(raw, base = []) {
     }
     return { allow: [...new Set([...base, ...extra])] };
 }
-/** Validate one raw `kinds.<name>` entry into a `KindConfig`, or drop it
- *  (return null) rather than throwing — an invalid kind entry in config.json
- *  must not break config parsing for every other kind. `whenToUse` is the
- *  only required field. */
-function normalizeKindEntry(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return null;
-    const r = raw;
-    if (typeof r.whenToUse !== 'string' || r.whenToUse.trim() === '')
-        return null;
-    const out = { whenToUse: r.whenToUse };
-    if (typeof r.model === 'string' && r.model.trim() !== '')
-        out.model = r.model;
-    if (typeof r.orchestratorModel === 'string' && r.orchestratorModel.trim() !== '')
-        out.orchestratorModel = r.orchestratorModel;
-    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
-    if (isStringArray(r.tools))
-        out.tools = r.tools;
-    if (isStringArray(r.extensions))
-        out.extensions = r.extensions;
-    if (isStringArray(r.availableTo))
-        out.availableTo = r.availableTo;
-    return out;
-}
-/** Validate one raw `kinds.<name>` entry as a sparse PATCH — an entry with no
- *  `whenToUse` that overrides individual launch knobs (model/orchestratorModel/
- *  tools/extensions/availableTo) of a kind some lower-precedence scope already
- *  defines. This is what lets a scope (e.g. a profile) persist ONLY
- *  `{ "model": "ultra" }` for a kind instead of freezing a full registry
- *  snapshot to disk (the same staleness trap `sparseModelLaddersToPersist`
- *  exists to avoid). Returns null when no valid field is present. */
-function normalizeKindPatch(raw) {
+/** Collect the valid `KindConfig` fields of one raw `kinds.<name>` entry —
+ *  every field is optional here, `whenToUse` included; mistyped fields are
+ *  dropped, never thrown (an invalid field in config.json must not break
+ *  config parsing for every other kind — the loud gate is install time, see
+ *  `invalidPluginKindsReasons`). Returns null when no valid field is present.
+ *  Whether `whenToUse` is REQUIRED is `mergeKinds`'s call: only an entry that
+ *  introduces a kind no lower layer defines needs one. */
+function normalizeKindFields(raw) {
     if (raw === null || typeof raw !== 'object')
         return null;
     const r = raw;
     const out = {};
+    if (typeof r.whenToUse === 'string' && r.whenToUse.trim() !== '')
+        out.whenToUse = r.whenToUse;
     if (typeof r.model === 'string' && r.model.trim() !== '')
         out.model = r.model;
     if (typeof r.orchestratorModel === 'string' && r.orchestratorModel.trim() !== '')
@@ -314,35 +293,102 @@ function normalizeKindPatch(raw) {
     return Object.keys(out).length > 0 ? out : null;
 }
 /** Merge a raw `kinds` block over `base` (defaulting to the builtin registry):
- *  each valid entry adds or shadows a kind by name; invalid entries are
- *  dropped, never thrown. Mirrors `mergeModelLadders`'s layer-over-defaults
- *  shape so a user/project config.json can add or override a single kind
- *  without restating the whole registry. Two entry shapes:
- *   - FULL (has `whenToUse`): defines or wholly replaces the kind, as before.
- *   - PATCH (no `whenToUse`, ≥1 valid launch field): field-merges over the
- *     kind the layers below already define (dropped when they don't) — the
- *     sparse-override shape `persistDefaultKindModel` writes. */
+ *  invalid entries are dropped, never thrown. Mirrors `mergeModelLadders`'s
+ *  layer-over-defaults shape so a config layer can add or override a single
+ *  kind without restating the whole registry. One rule, no entry shapes:
+ *   - A kind some lower layer already defines: the entry FIELD-MERGES over it
+ *     — any subset of fields, `whenToUse` included, so overriding just the
+ *     spawn-menu guidance of a builtin kind never strips its model tier
+ *     (the sparse-override shape `persistDefaultKindModel` writes).
+ *   - A NEW kind: the entry defines it and must carry `whenToUse` (a kind
+ *     with no spawn-menu gloss is meaningless); dropped otherwise.
+ *  Deliberately NOT expressible: wholly replacing a lower layer's kind — a
+ *  field can be overridden but never removed by omission. */
 function mergeKinds(raw, base = defaultKindsConfig()) {
     const out = { ...base };
     if (raw !== null && typeof raw === 'object') {
         for (const [kind, value] of Object.entries(raw)) {
-            const normalized = normalizeKindEntry(value);
-            if (normalized !== null) {
-                out[kind] = normalized;
+            const fields = normalizeKindFields(value);
+            if (fields === null)
                 continue;
-            }
             const existing = out[kind];
-            if (existing === undefined)
-                continue;
-            const patch = normalizeKindPatch(value);
-            if (patch !== null)
-                out[kind] = { ...existing, ...patch };
+            if (existing !== undefined) {
+                out[kind] = { ...existing, ...fields };
+            }
+            else if (fields.whenToUse !== undefined) {
+                out[kind] = fields;
+            }
         }
     }
     return out;
 }
+/** Layer the `kinds` contributions of every ENABLED plugin installed under
+ *  `scopeRootPath` over `base`, plugin name-sorted for determinism (directory
+ *  listing order is filesystem-dependent). Each plugin's block goes through
+ *  the same `mergeKinds` a scope `config.json` does — full entries add or
+ *  shadow, patches field-merge, invalid entries drop. Called by
+ *  `readMergedLaunchConfig` BELOW the host scope's own raw `kinds`, so the
+ *  scope's config.json always overrides its plugins. */
+function layerPluginKinds(scope, scopeRootPath, base) {
+    if (scopeRootPath === null)
+        return base;
+    const plugins = listInstalledPluginsInRoot(scope, scopeRootPath)
+        .filter((p) => p.enabled && p.manifest.kinds !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    let out = base;
+    for (const plugin of plugins)
+        out = mergeKinds(plugin.manifest.kinds, out);
+    return out;
+}
+const KIND_CONFIG_KEYS = new Set(['whenToUse', 'model', 'orchestratorModel', 'tools', 'extensions', 'availableTo']);
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export function invalidPluginKindsReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['kinds must be a JSON object keyed by kind name'];
+    }
+    const reasons = [];
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    for (const [kind, value] of Object.entries(raw)) {
+        if (kind.trim() === '') {
+            reasons.push('kinds contains an empty kind name');
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push(`kinds.${kind} must be a JSON object`);
+            continue;
+        }
+        const entry = value;
+        for (const key of Object.keys(entry)) {
+            if (!KIND_CONFIG_KEYS.has(key))
+                reasons.push(`kinds.${kind}.${key} is not a KindConfig field (expected one of: ${[...KIND_CONFIG_KEYS].join(', ')})`);
+        }
+        if (entry['whenToUse'] !== undefined && (typeof entry['whenToUse'] !== 'string' || entry['whenToUse'].trim() === '')) {
+            reasons.push(`kinds.${kind}.whenToUse must be a non-empty string`);
+        }
+        for (const field of ['model', 'orchestratorModel']) {
+            if (entry[field] !== undefined && (typeof entry[field] !== 'string' || entry[field].trim() === '')) {
+                reasons.push(`kinds.${kind}.${field} must be a non-empty string`);
+            }
+        }
+        for (const field of ['tools', 'extensions', 'availableTo']) {
+            if (entry[field] !== undefined && !isStringArray(entry[field])) {
+                reasons.push(`kinds.${kind}.${field} must be an array of strings`);
+            }
+        }
+        if (normalizeKindFields(value) === null) {
+            reasons.push(`kinds.${kind} has no valid KindConfig field — an entry must set at least one of: ${[...KIND_CONFIG_KEYS].join(', ')} (whenToUse is required when the kind exists in no lower layer)`);
+        }
+    }
+    return reasons;
+}
 /** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
- *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
+ *  null) rather than throwing — same rule `normalizeKindFields` follows. A
  *  valid entry needs a non-empty `previewEndpoint` and `relayTokenRef`; the
  *  token itself is never stored here (see `RemoteCanvasTarget`). */
 function normalizeRemoteCanvasTarget(raw) {
@@ -492,17 +538,16 @@ function readRawProfileConfig(profileId) {
 function readRawProjectScopeConfigs(targetCwd, targetProfileId) {
     const nearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
     const farthestFirst = [...nearestFirst].reverse();
-    const out = [];
-    for (const root of farthestFirst) {
-        const raw = readJsonIfExists(configPathFor(root));
-        if (raw !== null)
-            out.push(raw);
-    }
-    return out;
+    // A root with no config.json still contributes: its installed plugins may
+    // declare kinds, so the ROOT rides along and `raw` stays null.
+    return farthestFirst.map((root) => ({ root, raw: readJsonIfExists(configPathFor(root)) }));
 }
 /** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
  *  project stack > profile > user > builtin precedence — the same precedence
- *  order used for memory resolution. A kind or ladder cell declared at a
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. A kind or ladder cell declared at a
  *  more-specific scope shadows the same key from a less-specific scope; the
  *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
  *  widened by a selected profile's `projects`) layers nearest-root-strongest;
@@ -533,8 +578,13 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     const defaults = defaultScopeConfig();
     const userRaw = readRawScopeConfig('user');
     const profileRaw = readRawProfileConfig(targetProfileId);
-    const projectRawsFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
-    let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
+    const projectLayersFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
+    // Kinds layer per scope as: that scope's enabled PLUGINS first, then the
+    // scope's own raw config — so a plugin can add or shadow a kind (registry
+    // entry in its manifest + gated persona docs in its memory tree) and the
+    // scope's config.json still overrides its plugins. Other launch knobs
+    // (ladders/routes/spawnEnv) have no plugin channel.
+    let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
     let modelRoutes = mergeModelRoutes(userRaw?.modelRoutes);
     let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
@@ -546,8 +596,10 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
         modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
     }
-    for (const raw of projectRawsFarthestFirst) {
-        kinds = mergeKinds(raw.kinds, kinds);
+    for (const { root, raw } of projectLayersFarthestFirst) {
+        kinds = mergeKinds(raw?.kinds, layerPluginKinds('project', root, kinds));
+        if (raw === null)
+            continue;
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
         modelRoutes = mergeModelRoutes(raw.modelRoutes, modelRoutes);
         modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);

package/dist/core/installed-plugins.d.ts

@@ -0,0 +1,2 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];

package/dist/core/installed-plugins.js

@@ -0,0 +1,42 @@
+// installed-plugins.ts — the LEAF-LEVEL installed-plugin reader: list the
+// plugin packages physically present under one scope root, with their
+// manifests and enabled-state from that root's config.json `plugins` block.
+//
+// This lives below resolver.ts (which re-exports it for its existing callers)
+// so that config.ts can layer plugin-declared launch config (`kinds`) into
+// `readMergedLaunchConfig` without an import cycle: resolver.ts imports
+// config.ts, so config.ts can never import resolver.ts. Imports here stay
+// leaf-safe: types, fs-utils, manifest only.
+import { join } from 'node:path';
+import { CONFIG_FILE } from '../types.js';
+import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
+import { readPluginManifest } from './manifest.js';
+function pluginConfigForRoot(root) {
+    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
+    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
+}
+export function listInstalledPluginsInRoot(scope, scopeRootPath) {
+    const dir = join(scopeRootPath, 'plugins');
+    if (!pathExists(dir))
+        return [];
+    const cfg = pluginConfigForRoot(scopeRootPath);
+    const out = [];
+    for (const name of listDirs(dir)) {
+        const root = join(dir, name);
+        const manifest = readPluginManifest(root);
+        if (!manifest)
+            continue;
+        const entry = cfg[name];
+        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
+        out.push({
+            name,
+            scope,
+            root,
+            manifest,
+            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
+            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
+            version,
+        });
+    }
+    return out;
+}

package/dist/core/resolver.d.ts

@@ -1,5 +1,5 @@
 import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
-export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
 export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
 export declare function listAllPlugins(): InstalledPlugin[];
 export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;

package/dist/core/resolver.js

@@ -1,39 +1,14 @@
 import { join } from 'node:path';
-import { CONFIG_FILE } from '../types.js';
 import { readConfig } from './config.js';
-import { listDirs, pathExists, readJsonIfExists } from './fs-utils.js';
-import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
+import { listDirs, pathExists } from './fs-utils.js';
+import { readMarketplaceManifest } from './manifest.js';
 import { InputError } from './io.js';
 import { marketplacesDir, projectScopeRoot, scopeRoot, userScopeRoot, } from './scope.js';
-function pluginConfigForRoot(root) {
-    const cfg = readJsonIfExists(join(root, CONFIG_FILE));
-    return cfg && cfg.plugins && typeof cfg.plugins === 'object' ? cfg.plugins : {};
-}
-export function listInstalledPluginsInRoot(scope, scopeRootPath) {
-    const dir = join(scopeRootPath, 'plugins');
-    if (!pathExists(dir))
-        return [];
-    const cfg = pluginConfigForRoot(scopeRootPath);
-    const out = [];
-    for (const name of listDirs(dir)) {
-        const root = join(dir, name);
-        const manifest = readPluginManifest(root);
-        if (!manifest)
-            continue;
-        const entry = cfg[name];
-        const version = typeof entry?.version === 'string' ? entry.version : manifest.version;
-        out.push({
-            name,
-            scope,
-            root,
-            manifest,
-            enabled: typeof entry?.enabled === 'boolean' ? entry.enabled : true,
-            sourceMarketplace: typeof entry?.source_marketplace === 'string' ? entry.source_marketplace : undefined,
-            version,
-        });
-    }
-    return out;
-}
+// Moved to installed-plugins.ts (a leaf module below config.ts) so
+// `readMergedLaunchConfig` can layer plugin-declared kinds without an import
+// cycle; re-exported here for this module's existing callers.
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
 export function listInstalledPlugins(scope) {
     // The builtin scope has no scopeRoot, so this returns [] — builtin content is
     // the memory substrate, not plugins.

package/dist/types.d.ts

@@ -33,7 +33,20 @@ export interface PluginManifest {
     description?: string;
     source?: string;
     owner?: OwnerRef;
-    kinds?: string[];
+    /** Kind-registry contributions, keyed by full kind string (top-level e.g.
+     *  `applet-builder`, or sub-kind e.g. `plan/reviewers/security`). Each entry
+     *  is any subset of `KindConfig` fields: it FIELD-MERGES over a kind a lower
+     *  layer already defines (`whenToUse` included — overriding just the spawn
+     *  guidance never strips the kind's model tier), and defines a NEW kind when
+     *  none does (then `whenToUse` is required) — the same rule a scope
+     *  `config.json` `kinds` block follows.
+     *  `readMergedLaunchConfig` layers an enabled plugin's entries directly
+     *  above the builtin registry and below its host scope's own `config.json`,
+     *  so a plugin can ship a persona kind (registry entry here + gated persona
+     *  memory docs in its `memory/` tree) and the user still overrides it.
+     *  Archive plugins declare this in `bundle.json`; the installer copies the
+     *  validated block into this synthesized manifest. */
+    kinds?: Record<string, Partial<KindConfig>>;
     /** Plugin-root-relative path to one declarative command manifest
      *  (`commands.json`). When present on an installed, enabled plugin, that
      *  manifest contributes top-level command branches to the `crtr` tree —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.186",
+  "version": "0.3.188",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.186",
+  "version": "0.3.188",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.186",
+      "version": "0.3.188",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {