@pulsemcp/air-core 0.0.3 → 0.0.5

package/dist/config.d.ts

@@ -24,7 +24,29 @@ export interface ResolveOptions {
 export declare function resolveArtifacts(airJsonPath: string, options?: ResolveOptions): Promise<ResolvedArtifacts>;
 /**
  * Merge two resolved artifact sets. Override wins for matching IDs.
+ * Composite plugins are re-expanded after merging so that newly
+ * added plugins that reference existing ones are fully resolved.
  */
 export declare function mergeArtifacts(base: ResolvedArtifacts, override: ResolvedArtifacts): ResolvedArtifacts;
+/**
+ * Recursively expand plugin references.
+ *
+ * Each plugin may declare a `plugins` array referencing other plugins by ID.
+ * This function resolves those references recursively, merging child plugins'
+ * primitives (skills, mcp_servers, hooks) into the parent. The result is a
+ * flat set of primitive IDs on each plugin — nesting is author convenience,
+ * not a runtime concept.
+ *
+ * Semantics:
+ * - Child plugins are expanded depth-first in declaration order
+ * - Parent's direct declarations override children (later wins via dedup)
+ * - Circular references are rejected with a clear error message
+ * - Plugins without a `plugins` field are returned unchanged
+ * - The `plugins` array on each entry is preserved as metadata (e.g., for
+ *   UI display of the dependency graph) even though primitives are inlined
+ *
+ * Returns a new ResolvedArtifacts object; the input is not mutated.
+ */
+export declare function expandPlugins(artifacts: ResolvedArtifacts): ResolvedArtifacts;
 export declare function emptyArtifacts(): ResolvedArtifacts;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAmGpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAqC5B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CASnB;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAmGpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAuC5B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CASnB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAiF7E;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}

package/dist/config.js

@@ -108,7 +108,7 @@ export async function resolveArtifacts(airJsonPath, options) {
     const airConfig = loadAirConfig(airJsonPath);
     const baseDir = dirname(resolve(airJsonPath));
     const providers = options?.providers || [];
-    return {
+    const resolved = {
         skills: await loadAndMerge(airConfig.skills || [], baseDir, providers),
         references: await loadAndMerge(airConfig.references || [], baseDir, providers),
         mcp: await loadAndMerge(airConfig.mcp || [], baseDir, providers),
@@ -116,18 +116,127 @@ export async function resolveArtifacts(airJsonPath, options) {
         roots: await loadAndMerge(airConfig.roots || [], baseDir, providers),
         hooks: await loadAndMerge(airConfig.hooks || [], baseDir, providers),
     };
+    return expandPlugins(resolved);
 }
 /**
  * Merge two resolved artifact sets. Override wins for matching IDs.
+ * Composite plugins are re-expanded after merging so that newly
+ * added plugins that reference existing ones are fully resolved.
  */
 export function mergeArtifacts(base, override) {
-    return {
+    return expandPlugins({
         skills: { ...base.skills, ...override.skills },
         references: { ...base.references, ...override.references },
         mcp: { ...base.mcp, ...override.mcp },
         plugins: { ...base.plugins, ...override.plugins },
         roots: { ...base.roots, ...override.roots },
         hooks: { ...base.hooks, ...override.hooks },
+    });
+}
+/**
+ * Deduplicate an array of strings, keeping the last occurrence of each value.
+ * This ensures parent declarations take precedence over child plugin declarations
+ * when arrays are concatenated as [...childIds, ...parentIds].
+ */
+function deduplicateIds(arr) {
+    const seen = new Set();
+    const result = [];
+    for (let i = arr.length - 1; i >= 0; i--) {
+        if (!seen.has(arr[i])) {
+            seen.add(arr[i]);
+            result.unshift(arr[i]);
+        }
+    }
+    return result;
+}
+/**
+ * Recursively expand plugin references.
+ *
+ * Each plugin may declare a `plugins` array referencing other plugins by ID.
+ * This function resolves those references recursively, merging child plugins'
+ * primitives (skills, mcp_servers, hooks) into the parent. The result is a
+ * flat set of primitive IDs on each plugin — nesting is author convenience,
+ * not a runtime concept.
+ *
+ * Semantics:
+ * - Child plugins are expanded depth-first in declaration order
+ * - Parent's direct declarations override children (later wins via dedup)
+ * - Circular references are rejected with a clear error message
+ * - Plugins without a `plugins` field are returned unchanged
+ * - The `plugins` array on each entry is preserved as metadata (e.g., for
+ *   UI display of the dependency graph) even though primitives are inlined
+ *
+ * Returns a new ResolvedArtifacts object; the input is not mutated.
+ */
+export function expandPlugins(artifacts) {
+    const plugins = artifacts.plugins;
+    const expanded = new Map();
+    function expand(pluginId, ancestors) {
+        if (expanded.has(pluginId)) {
+            return expanded.get(pluginId);
+        }
+        const plugin = plugins[pluginId];
+        if (!plugin) {
+            throw new Error(`Plugin "${pluginId}" referenced by "${ancestors[ancestors.length - 1]}" not found in resolved artifacts`);
+        }
+        // Cycle detection
+        const cycleIndex = ancestors.indexOf(pluginId);
+        if (cycleIndex !== -1) {
+            const cycle = [...ancestors.slice(cycleIndex), pluginId].join(" → ");
+            throw new Error(`Circular plugin dependency detected: ${cycle}`);
+        }
+        // No child plugins — return as-is
+        if (!plugin.plugins || plugin.plugins.length === 0) {
+            expanded.set(pluginId, plugin);
+            return plugin;
+        }
+        // Recursively expand child plugins and collect their primitives
+        const childSkills = [];
+        const childMcpServers = [];
+        const childHooks = [];
+        for (const childId of plugin.plugins) {
+            const child = expand(childId, [...ancestors, pluginId]);
+            if (child.skills)
+                childSkills.push(...child.skills);
+            if (child.mcp_servers)
+                childMcpServers.push(...child.mcp_servers);
+            if (child.hooks)
+                childHooks.push(...child.hooks);
+        }
+        // Merge: children first, then parent's direct declarations (parent wins via dedup)
+        const mergedSkills = deduplicateIds([
+            ...childSkills,
+            ...(plugin.skills || []),
+        ]);
+        const mergedMcpServers = deduplicateIds([
+            ...childMcpServers,
+            ...(plugin.mcp_servers || []),
+        ]);
+        const mergedHooks = deduplicateIds([
+            ...childHooks,
+            ...(plugin.hooks || []),
+        ]);
+        const expandedPlugin = {
+            ...plugin,
+            skills: mergedSkills.length > 0 ? mergedSkills : undefined,
+            mcp_servers: mergedMcpServers.length > 0 ? mergedMcpServers : undefined,
+            hooks: mergedHooks.length > 0 ? mergedHooks : undefined,
+        };
+        expanded.set(pluginId, expandedPlugin);
+        return expandedPlugin;
+    }
+    // Expand all plugins
+    for (const pluginId of Object.keys(plugins)) {
+        expand(pluginId, []);
+    }
+    // Build the new plugins record preserving insertion order
+    const expandedPlugins = {};
+    for (const pluginId of Object.keys(plugins)) {
+        expandedPlugins[pluginId] = expanded.get(pluginId);
+    }
+    return {
+        ...artifacts,
+        plugins: expandedPlugins,
     };
 }
 export function emptyArtifacts() {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAaxC,SAAS,YAAY,CAAC,QAAgB;IACpC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,WAAW,CAClB,IAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACtC,+DAA+D;IAC/D,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CACxB,OAA0B,EAC1B,SAAiB;IAEjB,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QAEzB,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,IAAc,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,IAAc,CAAC,CAAC;QACtD,CAAC;QAED,QAAQ,CAAC,GAAG,CAAC,GAAG,OAAY,CAAC;IAC/B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,YAAY,CACzB,KAAe,EACf,OAAe,EACf,SAA4B;IAE5B,IAAI,MAAM,GAAsB,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,IAA6B,CAAC;QAClC,IAAI,SAAiB,CAAC;QAEtB,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;YAClE,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CACb,8CAA8C,MAAM,eAAe,CAAC,KAAK;oBACvE,gDAAgD,CACnD,CAAC;YACJ,CAAC;YACD,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAC1C,+EAA+E;YAC/E,SAAS,GAAG,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACzC,IAAI,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;YAClC,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAsB,CAAC;QACvD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACvD,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC;IACtC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,OAAO,CACZ,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,EAClD,MAAM,EACN,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,qBAAqB,EAAE,CAAC;IAC/D,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACxC,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,OAAwB;IAExB,MAAM,SAAS,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAE3C,OAAO;QACL,MAAM,EAAE,MAAM,YAAY,CACxB,SAAS,CAAC,MAAM,IAAI,EAAE,EACtB,OAAO,EACP,SAAS,CACV;QACD,UAAU,EAAE,MAAM,YAAY,CAC5B,SAAS,CAAC,UAAU,IAAI,EAAE,EAC1B,OAAO,EACP,SAAS,CACV;QACD,GAAG,EAAE,MAAM,YAAY,CACrB,SAAS,CAAC,GAAG,IAAI,EAAE,EACnB,OAAO,EACP,SAAS,CACV;QACD,OAAO,EAAE,MAAM,YAAY,CACzB,SAAS,CAAC,OAAO,IAAI,EAAE,EACvB,OAAO,EACP,SAAS,CACV;QACD,KAAK,EAAE,MAAM,YAAY,CACvB,SAAS,CAAC,KAAK,IAAI,EAAE,EACrB,OAAO,EACP,SAAS,CACV;QACD,KAAK,EAAE,MAAM,YAAY,CACvB,SAAS,CAAC,KAAK,IAAI,EAAE,EACrB,OAAO,EACP,SAAS,CACV;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,QAA2B;IAE3B,OAAO;QACL,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE;QAC9C,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC,UAAU,EAAE;QAC1D,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE;QACrC,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE;QACjD,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;QAC3C,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,MAAM,EAAE,EAAE;QACV,UAAU,EAAE,EAAE;QACd,GAAG,EAAE,EAAE;QACP,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,EAAE;QACT,KAAK,EAAE,EAAE;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { AirConfig, ResolvedArtifacts, SkillEntry, ReferenceEntry, McpOAuthConfig, McpServerEntry, PluginEntry, RootEntry, HookEntry, } from "./types.js";
+export type { AirConfig, ResolvedArtifacts, SkillEntry, ReferenceEntry, McpOAuthConfig, McpServerEntry, PluginAuthor, PluginEntry, RootEntry, HookEntry, } from "./types.js";
 export type { AgentAdapter, CatalogProvider, SecretResolver, AirExtension, AgentSessionConfig, StartCommand, PrepareSessionOptions, PreparedSession, } from "./types.js";
-export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, emptyArtifacts, } from "./config.js";
+export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, expandPlugins, emptyArtifacts, } from "./config.js";
 export type { ResolveOptions } from "./config.js";
 export { validateJson } from "./validator.js";
 export type { ValidationResult, ValidationError } from "./validator.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 // Config resolution
-export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, emptyArtifacts, } from "./config.js";
+export { loadAirConfig, getDefaultAirJsonPath, getAirJsonPath, resolveArtifacts, mergeArtifacts, expandPlugins, emptyArtifacts, } from "./config.js";
 // Validation
 export { validateJson } from "./validator.js";
 // Schemas

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,UAAU;AACV,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,UAAU;AACV,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -45,15 +45,26 @@ export interface McpServerEntry {
     headers?: Record<string, string>;
     oauth?: McpOAuthConfig;
 }
+export interface PluginAuthor {
+    name?: string;
+    email?: string;
+    url?: string;
+}
 export interface PluginEntry {
     id: string;
     title?: string;
     description: string;
-    type: "command";
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-    timeout_seconds?: number;
+    version?: string;
+    skills?: string[];
+    mcp_servers?: string[];
+    hooks?: string[];
+    plugins?: string[];
+    author?: PluginAuthor;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    logo?: string;
+    keywords?: string[];
 }
 export interface RootEntry {
     name: string;
@@ -66,6 +77,7 @@ export interface RootEntry {
     default_skills?: string[];
     default_plugins?: string[];
     default_hooks?: string[];
+    default_subagent_roots?: string[];
     user_invocable?: boolean;
     default_stop_condition?: string;
 }
@@ -120,6 +132,13 @@ export interface PrepareSessionOptions {
      * When set, this replaces root.default_mcp_servers entirely.
      */
     mcpServerOverrides?: string[];
+    /**
+     * Skip merging subagent roots' artifacts into the parent session.
+     * When true, default_subagent_roots is ignored during preparation.
+     * Orchestrators that manage subagent composition externally (e.g., via
+     * an MCP server) should set this to true.
+     */
+    skipSubagentMerge?: boolean;
 }
 export interface PreparedSession {
     /** Paths to config files written (e.g., ".mcp.json") */
@@ -128,6 +147,12 @@ export interface PreparedSession {
     skillPaths: string[];
     /** The command to start the agent in the prepared directory */
     startCommand: StartCommand;
+    /**
+     * System prompt content describing subagent root dependencies.
+     * Present when the root has default_subagent_roots and skipSubagentMerge is false.
+     * Adapters write this to a file and/or include it in the start command.
+     */
+    subagentContext?: string;
 }
 /**
  * Catalog Provider — resolves remote artifact index URIs.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,iBAAiB,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,0EAA0E;IAC1E,cAAc,CACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,CAAC,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,kBAAkB,CAAC;IACtB,iDAAiD;IACjD,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAAC;IAE5D;;;;;OAKG;IACH,cAAc,CACZ,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,yCAAyC;IACzC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACpD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,iBAAiB,CAAC;IACjD,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAMD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsemcp/air-core",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "publishConfig": {
     "access": "public"
   },

package/schemas/plugins.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/plugins.schema.json",
   "title": "AIR Plugins Index",
-  "description": "Index of agent plugins available in this AIR configuration. Plugins extend agent capabilities beyond what MCP servers and skills provide. AIR plugins are agent-agnostic and translated to agent-specific formats at session start time.",
+  "description": "Index of agent plugins available in this AIR configuration. A plugin is a named grouping of AIR primitives (skills, MCP servers, hooks) — a compositional unit for bundling and distributing related capabilities. Plugins do not define new artifacts inline; they reference existing artifacts by ID from the corresponding index files.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -20,7 +20,7 @@
   "$defs": {
     "Plugin": {
       "type": "object",
-      "description": "An agent plugin that extends capabilities via external commands.",
+      "description": "A plugin — a named grouping of AIR primitives (skills, MCP servers, hooks) for bundling and distribution. All referenced artifacts must be defined in their respective index files.",
       "properties": {
         "id": {
           "type": "string",
@@ -38,38 +38,88 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 500,
-          "description": "Concise description of what this plugin does."
+          "description": "Concise description of what this plugin provides."
         },
-        "type": {
+        "version": {
           "type": "string",
-          "enum": ["command"],
-          "description": "Plugin type. Currently only 'command' is supported."
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9._-]+)?$",
+          "description": "Semantic version of the plugin (e.g., '1.0.0')."
         },
-        "command": {
-          "type": "string",
-          "description": "Executable command to run for this plugin."
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of skills bundled by this plugin. Must reference skill IDs defined in skills.json indexes."
         },
-        "args": {
+        "mcp_servers": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Command-line arguments for the plugin command."
+          "description": "IDs of MCP servers bundled by this plugin. Must reference server IDs defined in mcp.json indexes."
         },
-        "env": {
-          "type": "object",
-          "additionalProperties": {
+        "hooks": {
+          "type": "array",
+          "items": {
             "type": "string"
           },
-          "description": "Environment variables for the plugin process. Values support ${ENV_VAR} interpolation."
+          "description": "IDs of hooks bundled by this plugin. Must reference hook IDs defined in hooks.json indexes."
+        },
+        "plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other plugins to compose into this plugin. Referenced plugins' primitives (skills, mcp_servers, hooks) are recursively expanded and merged with this plugin's direct declarations. Circular references are rejected at resolution time."
+        },
+        "author": {
+          "type": "object",
+          "description": "Plugin author information.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Author's name."
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Author's email address."
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Author's website or profile URL."
+            }
+          },
+          "additionalProperties": false
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the plugin's homepage or documentation."
+        },
+        "repository": {
+          "type": "string",
+          "description": "URL or identifier for the plugin's source repository."
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier (e.g., 'MIT', 'Apache-2.0')."
+        },
+        "logo": {
+          "type": "string",
+          "description": "Path or URL to the plugin's logo image."
         },
-        "timeout_seconds": {
-          "type": "number",
-          "minimum": 1,
-          "description": "Maximum execution time in seconds before the plugin is killed."
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Keywords for discovery and categorization."
         }
       },
-      "required": ["id", "description", "type", "command"],
+      "required": ["id", "description"],
       "additionalProperties": false
     }
   }

package/schemas/roots.schema.json

@@ -80,6 +80,13 @@
           },
           "description": "IDs of hooks to activate by default for sessions using this root."
         },
+        "default_subagent_roots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other roots that this root depends on as subagents. The default CLI behavior merges subagent roots' skills and MCP servers into the parent session and appends subagent metadata to the system prompt. Orchestrators that manage subagent composition externally (e.g., via an MCP server) can opt out with --no-subagent-merge."
+        },
         "user_invocable": {
           "type": "boolean",
           "description": "Whether this root can be directly invoked by users to start a session.",

package/schemas/schemas/plugins.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/pulsemcp/air/main/schemas/plugins.schema.json",
   "title": "AIR Plugins Index",
-  "description": "Index of agent plugins available in this AIR configuration. Plugins extend agent capabilities beyond what MCP servers and skills provide. AIR plugins are agent-agnostic and translated to agent-specific formats at session start time.",
+  "description": "Index of agent plugins available in this AIR configuration. A plugin is a named grouping of AIR primitives (skills, MCP servers, hooks) — a compositional unit for bundling and distributing related capabilities. Plugins do not define new artifacts inline; they reference existing artifacts by ID from the corresponding index files.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -20,7 +20,7 @@
   "$defs": {
     "Plugin": {
       "type": "object",
-      "description": "An agent plugin that extends capabilities via external commands.",
+      "description": "A plugin — a named grouping of AIR primitives (skills, MCP servers, hooks) for bundling and distribution. All referenced artifacts must be defined in their respective index files.",
       "properties": {
         "id": {
           "type": "string",
@@ -38,38 +38,88 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 500,
-          "description": "Concise description of what this plugin does."
+          "description": "Concise description of what this plugin provides."
         },
-        "type": {
+        "version": {
           "type": "string",
-          "enum": ["command"],
-          "description": "Plugin type. Currently only 'command' is supported."
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([-+][a-zA-Z0-9._-]+)?$",
+          "description": "Semantic version of the plugin (e.g., '1.0.0')."
         },
-        "command": {
-          "type": "string",
-          "description": "Executable command to run for this plugin."
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of skills bundled by this plugin. Must reference skill IDs defined in skills.json indexes."
         },
-        "args": {
+        "mcp_servers": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Command-line arguments for the plugin command."
+          "description": "IDs of MCP servers bundled by this plugin. Must reference server IDs defined in mcp.json indexes."
         },
-        "env": {
-          "type": "object",
-          "additionalProperties": {
+        "hooks": {
+          "type": "array",
+          "items": {
             "type": "string"
           },
-          "description": "Environment variables for the plugin process. Values support ${ENV_VAR} interpolation."
+          "description": "IDs of hooks bundled by this plugin. Must reference hook IDs defined in hooks.json indexes."
+        },
+        "plugins": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other plugins to compose into this plugin. Referenced plugins' primitives (skills, mcp_servers, hooks) are recursively expanded and merged with this plugin's direct declarations. Circular references are rejected at resolution time."
+        },
+        "author": {
+          "type": "object",
+          "description": "Plugin author information.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Author's name."
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Author's email address."
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Author's website or profile URL."
+            }
+          },
+          "additionalProperties": false
+        },
+        "homepage": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to the plugin's homepage or documentation."
+        },
+        "repository": {
+          "type": "string",
+          "description": "URL or identifier for the plugin's source repository."
+        },
+        "license": {
+          "type": "string",
+          "description": "SPDX license identifier (e.g., 'MIT', 'Apache-2.0')."
+        },
+        "logo": {
+          "type": "string",
+          "description": "Path or URL to the plugin's logo image."
         },
-        "timeout_seconds": {
-          "type": "number",
-          "minimum": 1,
-          "description": "Maximum execution time in seconds before the plugin is killed."
+        "keywords": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Keywords for discovery and categorization."
         }
       },
-      "required": ["id", "description", "type", "command"],
+      "required": ["id", "description"],
       "additionalProperties": false
     }
   }

package/schemas/schemas/roots.schema.json

@@ -80,6 +80,13 @@
           },
           "description": "IDs of hooks to activate by default for sessions using this root."
         },
+        "default_subagent_roots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "IDs of other roots that this root depends on as subagents. The default CLI behavior merges subagent roots' skills and MCP servers into the parent session and appends subagent metadata to the system prompt. Orchestrators that manage subagent composition externally (e.g., via an MCP server) can opt out with --no-subagent-merge."
+        },
         "user_invocable": {
           "type": "boolean",
           "description": "Whether this root can be directly invoked by users to start a session.",