@mistralys/persona-builder 2.3.0 → 2.4.1

package/dist/index.d.cts

@@ -22,7 +22,12 @@
  *
  * @param text       - Template string potentially containing {{> name}} markers
  * @param partialsMap - Map of partial name → partial content
- * @param depth      - Current recursion depth (callers should omit; defaults to 0)
+ * @param depth      - **Internal recursion counter — callers must always omit this
+ *                     parameter.** It exists solely so the function can track its own
+ *                     nesting level across recursive calls. Passing a non-zero value
+ *                     bypasses the depth guard (e.g. `resolvePartials(text, map, 5)`
+ *                     expands nothing). This parameter will be removed from the public
+ *                     signature and marked `@internal` in a future release.
  * @returns          The template string with partial markers replaced
  */
 declare function resolvePartials(text: string, partialsMap: Record<string, string>, depth?: number): string;
@@ -251,6 +256,14 @@ interface PersonaMetadata {
     version?: string;
     /** Ordered list of tool identifiers */
     tools?: string[];
+    /**
+     * Optional list of persona slugs this persona delegates to as sub-agents.
+     *
+     * Each entry is a kebab-case slug referencing another persona in any
+     * configured suite. Validated during build against the cross-suite agent
+     * map — an unknown slug produces an error-severity `ValidationResult`.
+     */
+    subagents?: string[];
     /** Free-form context variables available during template rendering */
     [key: string]: unknown;
 }
@@ -315,6 +328,26 @@ interface SuiteConfig {
     metaSubdir?: string;
     /** Sub-directory within srcDir that contains content Markdown files. Default: 'content' */
     contentSubdir?: string;
+    /**
+     * Optional map of suite-level template variables.
+     *
+     * These form the **second-lowest** layer (layer 2 of 7) in the merge chain
+     * used by `buildContext()`:
+     *
+     *   1. `BuildConfig.variables`   — global defaults (lowest priority)
+     *   2. `SuiteConfig.variables`   ← this field
+     *   3. `_shared.yaml` fields     — shared metadata
+     *   4. Per-persona YAML fields   — per-persona metadata
+     *   5. Derived fields            — version fallback, tools serialisation, etc.
+     *   6. Cross-suite agent map     — `agent_<slug>` entries
+     *   7. Target flags              — `target_<name>` booleans (highest priority)
+     *
+     * Suite variables override any same-named entry in `BuildConfig.variables`,
+     * but are themselves overridden by `_shared.yaml` fields and per-persona
+     * YAML metadata. Use this field to inject suite-scoped defaults that apply
+     * to every persona in the suite without modifying shared YAML files.
+     */
+    variables?: Record<string, unknown>;
 }
 /**
  * A single validation outcome returned by a plugin's `onValidate` hook.
@@ -333,10 +366,12 @@ interface ValidationResult {
  * identification.
  *
  * Hook invocation order (per persona):
- *   1. onSuiteInit   — once per suite, before any persona is built
- *   2. onBuildContext — per persona, before template rendering
- *   3. onPostRender   — per persona, after body rendering
- *   4. onValidate     — per persona, during the validation phase
+ *   1. onSuiteInit      — once per suite, before any persona is built
+ *   2. onPartials       — once per suite, after partials are loaded
+ *   3. onBuildContext   — per persona, before template rendering
+ *   4. onPersonaPartials — per persona, before template rendering (after onBuildContext)
+ *   5. onPostRender     — per persona, after body rendering
+ *   6. onValidate       — per persona, during the validation phase
  */
 interface PersonaBuildPlugin {
     /**
@@ -353,6 +388,21 @@ interface PersonaBuildPlugin {
      * @param sharedMeta Shared metadata merged from `_shared.yaml` (mutate in place if needed)
      */
     onSuiteInit?(suite: SuiteConfig, sharedMeta: Record<string, unknown>): void;
+    /**
+     * Called once per suite after partials are loaded from disk (and after any
+     * `BuildConfig.partials` inline map has been applied), but before any persona
+     * is rendered.
+     *
+     * Plugins are chained: each plugin receives the accumulated partials map
+     * returned by the previous plugin. Return the (possibly mutated or extended)
+     * map to pass it to the next plugin.
+     *
+     * @param partialsMap The current map of partial name → partial content
+     * @param suiteName   The identifier of the current suite
+     * @param suite       The suite configuration object
+     * @returns           Updated partials map (must include all original keys)
+     */
+    onPartials?(partialsMap: Record<string, string>, suiteName: string, suite: SuiteConfig): Record<string, string>;
     /**
      * Called for each persona before template rendering.
      *
@@ -366,6 +416,34 @@ interface PersonaBuildPlugin {
      * @returns        Updated rendering context (must include all original keys)
      */
     onBuildContext?(context: Record<string, unknown>, persona: PersonaMetadata, suite: SuiteConfig, target?: TargetType): Record<string, unknown>;
+    /**
+     * Called for each persona (and target) after `onBuildContext`, before
+     * template rendering.
+     *
+     * Allows plugins to inject or override partials on a per-persona basis.
+     * Plugins are chained: each plugin receives the accumulated partials map
+     * returned by the previous plugin. Return the (possibly mutated or extended)
+     * map to pass it to the next plugin.
+     *
+     * **Isolation guarantee:** The builder creates a shallow copy of the
+     * suite-level partials map before invoking the first plugin in the chain.
+     * The `partialsMap` argument you receive is already persona-scoped — changes
+     * to it (or to the map you return) are invisible to other personas in the
+     * same suite.  Do **not** mutate `partialsMap` in place; instead, return a
+     * new map (e.g. `{ ...partialsMap, myPartial: '...' }`) so that each plugin
+     * in the chain receives an independent copy of the previous plugin's output.
+     *
+     * @param partialsMap The current persona-scoped map of partial name → content
+     *                    (a shallow copy of the suite-level map, isolated per persona)
+     * @param persona     Typed metadata for the persona being built
+     * @param context     The post-`onBuildContext` rendering context; persona
+     *                    metadata and any context keys injected by `onBuildContext`
+     *                    plugins are accessible here
+     * @param suite       The suite configuration object
+     * @param target      The current build target (optional)
+     * @returns           Updated partials map (must include all original keys)
+     */
+    onPersonaPartials?(partialsMap: Record<string, string>, persona: PersonaMetadata, context: Record<string, unknown>, suite: SuiteConfig, target?: TargetType): Record<string, string>;
     /**
      * Called for each persona after body rendering.
      *
@@ -495,8 +573,9 @@ declare function loadContent(mdPath: string): Promise<string>;
  * PersonaBuildPlugin. The runner:
  *   - Skips plugins that do not implement the requested hook (hook is optional)
  *   - Invokes hooks in the order plugins are registered (first-in first-called)
- *   - For accumulating hooks (onBuildContext, onPostRender), each plugin
- *     receives the output of the previous plugin as its first argument
+ *   - For accumulating hooks (onBuildContext, onPartials, onPersonaPartials,
+ *     onPostRender), each plugin receives the output of the previous plugin
+ *     as its first argument
  *   - For collecting hooks (onValidate), results are concatenated into a
  *     flat array
  *
@@ -547,6 +626,44 @@ declare function runBuildContext(plugins: PersonaBuildPlugin[], ctx: Record<stri
  * @returns        Final output string after all plugins have run
  */
 declare function runPostRender(plugins: PersonaBuildPlugin[], rendered: string, persona: PersonaMetadata, target: TargetType): string;
+/**
+ * Invoke the `onPartials` hook on every registered plugin, accumulating
+ * partials map mutations sequentially.
+ *
+ * Each plugin receives the partials map returned by the previous plugin. If a
+ * plugin does not implement `onPartials`, the map passes through unchanged.
+ * The final accumulated map is returned.
+ *
+ * Called once per suite after partials are loaded from disk, before any
+ * persona is rendered.
+ *
+ * @param plugins     Ordered list of registered plugins
+ * @param partialsMap Initial map of partial name → partial content
+ * @param suiteName   The identifier of the current suite
+ * @param suite       The suite configuration object
+ * @returns           Accumulated partials map after all plugins have run
+ */
+declare function runPartials(plugins: PersonaBuildPlugin[], partialsMap: Record<string, string>, suiteName: string, suite: SuiteConfig): Record<string, string>;
+/**
+ * Invoke the `onPersonaPartials` hook on every registered plugin, accumulating
+ * partials map mutations sequentially.
+ *
+ * Each plugin receives the partials map returned by the previous plugin. If a
+ * plugin does not implement `onPersonaPartials`, the map passes through
+ * unchanged. The final accumulated map is returned.
+ *
+ * Called for each persona (and target) after `onBuildContext`, before
+ * template rendering.
+ *
+ * @param plugins     Ordered list of registered plugins
+ * @param partialsMap Initial map of partial name → partial content
+ * @param persona     Typed metadata for the persona being built
+ * @param context     The rendering context built by `onBuildContext`
+ * @param suite       The suite configuration object
+ * @param target      The current build target (optional)
+ * @returns           Accumulated partials map after all plugins have run
+ */
+declare function runPersonaPartials(plugins: PersonaBuildPlugin[], partialsMap: Record<string, string>, persona: PersonaMetadata, context: Record<string, unknown>, suite: SuiteConfig, target?: TargetType): Record<string, string>;
 /**
  * Invoke the `onValidate` hook on every registered plugin and collect all
  * returned ValidationResult objects into a single flat array.
@@ -745,9 +862,19 @@ interface BuildConfig {
      */
     suites: Record<string, SuiteConfig>;
     /**
-     * Absolute path to the shared partials directory. When provided, partials
-     * from this directory are loaded as the base layer before suite-local
-     * partials are overlaid. Optional.
+     * Absolute path to the shared partials directory.
+     *
+     * When provided, partials from this directory form the **second** layer in
+     * the five-layer partials resolution order:
+     *
+     *   1. `BuildConfig.partials`  — lowest precedence (inline map)
+     *   2. `sharedPartialsDir`     — overlaid on top of inline partials (this field)
+     *   3. Suite-local partials    — overlaid on top of shared partials
+     *   4. `onPartials` hooks      — suite-level plugin-injected partials
+     *   5. `onPersonaPartials`     — per-persona overrides (highest precedence)
+     *
+     * Later layers overlay earlier ones; a key present in multiple layers uses
+     * the value from the highest-precedence layer.
      */
     sharedPartialsDir?: string;
     /**
@@ -794,6 +921,43 @@ interface BuildConfig {
      * `TargetDefinition.defaultFrontmatter` are used.
      */
     frontmatter?: Record<string, string>;
+    /**
+     * Optional map of global template variables made available to every persona
+     * during rendering.
+     *
+     * These form the **lowest-priority** layer (layer 1 of 7) in the merge chain
+     * used by `buildContext()`:
+     *
+     *   1. `BuildConfig.variables`   ← this field (lowest priority)
+     *   2. `SuiteConfig.variables`   — suite-level overrides
+     *   3. `_shared.yaml` fields     — shared metadata
+     *   4. Per-persona YAML fields   — per-persona metadata
+     *   5. Derived fields            — version fallback, tools serialisation, etc.
+     *   6. Cross-suite agent map     — `agent_<slug>` entries
+     *   7. Target flags              — `target_<name>` booleans (highest priority)
+     *
+     * Any key set here that also appears in a higher-priority layer will be
+     * overridden. Use this field for project-wide defaults that individual suites
+     * or personas can selectively override via `SuiteConfig.variables` or their
+     * own YAML metadata.
+     */
+    variables?: Record<string, unknown>;
+    /**
+     * Optional map of inline partials, keyed by partial name.
+     *
+     * These form the **lowest** layer in the five-layer partials resolution
+     * order:
+     *
+     *   1. `BuildConfig.partials`  — lowest precedence (this field)
+     *   2. `sharedPartialsDir`     — overlaid on top of inline partials
+     *   3. Suite-local partials    — overlaid on top of shared partials
+     *   4. `onPartials` hooks      — suite-level plugin-injected partials
+     *   5. `onPersonaPartials`     — per-persona overrides (highest precedence)
+     *
+     * Later layers overlay earlier ones; a key present in multiple layers uses
+     * the value from the highest-precedence layer.
+     */
+    partials?: Record<string, string>;
     /**
      * Optional target registry to use for this build.
      *
@@ -915,6 +1079,21 @@ declare function renderFrontmatter(template: string, context: Record<string, unk
  *       agent name map, then iterates all suites × targets, calls
  *       buildSuite() for each combination, and returns a BuildSummary.
  *       Respects --check (no writes) and --strict (fail on warnings/errors).
+ *
+ * Template variable injection (7-layer merge order, later layers win):
+ *
+ *  1. BuildConfig.variables    — global defaults; available to every suite
+ *  2. SuiteConfig.variables    — suite-level overrides
+ *  3. _shared.yaml fields      — shared metadata for the suite
+ *  4. Per-persona YAML fields  — per-persona metadata
+ *  5. Derived fields           — version fallback, tools serialisation, etc.
+ *  6. Cross-suite agent map    — agent_<slug> / agent_slug_<slug> entries
+ *  7. Target flags             — target_<name> booleans; always highest precedence
+ *
+ * Callers inject global or suite-scoped variables via `BuildConfig.variables`
+ * and `SuiteConfig.variables` respectively. Both fields are forwarded by
+ * buildPersona() to the internal buildContext() function as the two
+ * lowest-priority layers in the merge chain.
  */
 
 /**
@@ -924,22 +1103,39 @@ declare function renderFrontmatter(template: string, context: Record<string, unk
  *   1. Load sharedMeta + personaMeta (callers supply pre-loaded values)
  *   2. Build merged context
  *   3. Run onBuildContext plugin hooks (context accumulation)
- *   4. Resolve frontmatter template → render frontmatter
- *   5. Load content template
- *   6. Render body: partials → conditionals → variables → post-process
- *   7. Assemble final output (frontmatter + body)
- *   8. Run onPostRender plugin hooks (output chain)
- *   9. Run onValidate plugin hooks (validation collection)
- *  10. Determine output file path
- *  11. Write output file (unless check mode)
- *  12. Return BuildResult
+ *   4. Run onPersonaPartials plugin hooks (shallow-copy partials map, persona-scoped)
+ *   5. Render frontmatter template → render frontmatter
+ *   6. Load content template
+ *   7. Render body: partials → conditionals → variables → post-process
+ *   8. Assemble final output (frontmatter + body)
+ *   9. Run onPostRender plugin hooks (output chain)
+ *  10. Run onValidate plugin hooks (validation collection)
+ *  11. Determine output file path
+ *  12. Write output file (unless check mode)
+ *  13. Return BuildResult
  *
  * @param personaYamlPath  Absolute path to the persona YAML source file
  * @param suiteName        Identifier for the suite this persona belongs to
- * @param suiteConfig      Suite configuration object
+ * @param suiteConfig      Suite configuration object. `suiteConfig.variables`
+ *                         is forwarded to `buildContext()` as the
+ *                         `suiteVariables` layer (layer 2 of 7) — these values
+ *                         override any `config.variables` but are themselves
+ *                         overridden by `_shared.yaml` and per-persona fields.
  * @param sharedMeta       Pre-loaded `_shared.yaml` contents
- * @param partialsMap      Pre-loaded partials map (shared + suite-local merged)
- * @param config           Top-level BuildConfig
+ * @param partialsMap      Pre-loaded partials map (shared + suite-local merged).
+ *                         This map is **not** passed directly to rendering.
+ *                         Instead, a shallow copy (`{ ...partialsMap }`) is
+ *                         created at step 3b and passed to the `onPersonaPartials`
+ *                         plugin hooks — the hooks' accumulated output map is what
+ *                         reaches `resolvePartials`, not `partialsMap` itself.
+ *                         This ensures that persona-level overrides or injections
+ *                         do not leak back into the caller's reference or into
+ *                         subsequent personas in the same suite.
+ * @param config           Top-level BuildConfig. `config.variables` is
+ *                         forwarded to `buildContext()` as the
+ *                         `configVariables` layer (layer 1 of 7, lowest
+ *                         priority) — global defaults available to every
+ *                         persona across all suites.
  * @param plugins          Registered plugins
  * @param target           Target output format
  * @param agentMap         Pre-built cross-suite agent name map
@@ -958,10 +1154,11 @@ declare function buildPersona(personaYamlPath: string, suiteName: string, suiteC
  *
  * Pipeline:
  *   1. Load `_shared.yaml` for the suite
- *   2. Load merged partials (shared → suite-local)
+ *   2. Load merged partials (config.partials → shared → suite-local)
  *   3. Run `onSuiteInit` on all plugins
- *   4. Discover all persona YAML files
- *   5. Call `buildPersona()` for each
+ *   4. Run `onPartials` on all plugins (highest priority: may override any file-based partial)
+ *   5. Discover all persona YAML files
+ *   6. Call `buildPersona()` for each
  *
  * @param suiteName    Identifier for this suite
  * @param suiteConfig  Suite configuration
@@ -1119,4 +1316,4 @@ declare const defaultRegistry: TargetRegistry;
 
 declare const VERSION: string;
 
-export { type BuildConfig, type BuildResult, type BuildSummary, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsList, validateFileName, validateStrictMarkers };
+export { type BuildConfig, type BuildResult, type BuildSummary, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsList, validateFileName, validateStrictMarkers };