dna-sdk 0.1.0

package/dist/kernel/prompt-builder.js

@@ -0,0 +1,237 @@
+/**
+ * PromptBuilder — namespace class extracting prompt-related logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.prompt.build()` — equivalent to `mi.buildPrompt()`.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved; both APIs
+ * return identical results.
+ */
+import Mustache from "mustache";
+import { stripPromptBlock } from "./_text.js";
+// ---------------------------------------------------------------------------
+// PromptBuilder
+// ---------------------------------------------------------------------------
+export class PromptBuilder {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Build the final prompt string for the given (or default) agent.
+     * Equivalent to `mi.buildPrompt(opts)`.
+     */
+    async build(opts) {
+        const agentOpt = opts?.agent;
+        const extra = opts?.context;
+        // Resolve agent name
+        let agentName = agentOpt ?? null;
+        if (!agentName) {
+            const root = this.host.root;
+            if (root) {
+                const kp = this.host._kinds.get(`${root.apiVersion}\0${root.kind}`);
+                if (kp) {
+                    agentName = kp.getDefaultAgentName(root);
+                }
+            }
+        }
+        const agentDoc = agentName ? this._findAgent(agentName) : null;
+        if (!agentDoc) {
+            return `Agent '${agentName}' not found`;
+        }
+        // Build context — merge backwards-compat params into enabledSlots
+        const enabledSlots = { ...(opts?.enabledSlots ?? {}) };
+        if (opts?.enabledSkills && !enabledSlots.skills)
+            enabledSlots.skills = opts.enabledSkills;
+        if (opts?.enabledGuardrails && !enabledSlots.guardrails)
+            enabledSlots.guardrails = opts.enabledGuardrails;
+        let ctx = await this._buildContext(agentDoc, extra, enabledSlots);
+        // Hook: pre_build_prompt — middleware can modify context
+        const kernel = this.host._kernel;
+        if (kernel?.hooks?.has("pre_build_prompt")) {
+            const hookCtx = {
+                scope: this.host.scope,
+                agent: agentName ?? undefined,
+                data: { context: ctx },
+            };
+            const result = kernel.hooks.runMiddleware("pre_build_prompt", hookCtx);
+            ctx = result.data.context ?? ctx;
+        }
+        // Render via template cascade
+        const prompt = await this._renderPrompt(ctx, agentDoc);
+        // Hook: post_build_prompt — event notification
+        if (kernel?.hooks?.has("post_build_prompt")) {
+            kernel.hooks.emit("post_build_prompt", {
+                scope: this.host.scope,
+                agent: agentName ?? undefined,
+                prompt,
+                data: {},
+            });
+        }
+        return prompt;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    _findAgent(name) {
+        let best = null;
+        let bestPriority = -1;
+        const kinds = this.host._kinds;
+        for (const d of this.host.documents) {
+            const kp = kinds.get(`${d.apiVersion}\0${d.kind}`);
+            if (kp?.isPromptTarget && d.name === name) {
+                const priority = kp.promptTargetPriority ?? 0;
+                if (priority > bestPriority) {
+                    best = d;
+                    bestPriority = priority;
+                }
+            }
+        }
+        return best;
+    }
+    async _buildContext(agentDoc, extra, enabledSlots) {
+        const ctx = {};
+        const kinds = this.host._kinds;
+        // Root metadata + spec
+        const root = this.host.root;
+        if (root) {
+            ctx.metadata = { ...root.metadata };
+            ctx.spec = { ...root.spec };
+        }
+        // Agent entry
+        const agentSpec = agentDoc.spec;
+        const instructionRef = agentSpec.instruction ?? "";
+        ctx.agent = {
+            name: agentDoc.name,
+            description: PromptBuilder._getDescription(agentDoc),
+            // stripPromptBlock: composition-only trailing-whitespace
+            // normalization (i-013) — storage stays byte-faithful.
+            instruction: instructionRef
+                ? stripPromptBlock(await this.host.ref(instructionRef))
+                : "",
+        };
+        ctx.agentId = agentDoc.name;
+        // All documents grouped by alias (for Mustache sections)
+        for (const doc of this.host.documents) {
+            const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+            if (!kp)
+                continue;
+            const alias = kp.alias;
+            if (!ctx[alias])
+                ctx[alias] = [];
+            const entry = {
+                name: doc.name,
+                description: PromptBuilder._getDescription(doc),
+            };
+            const spec = doc.spec;
+            for (const [k, v] of Object.entries(spec)) {
+                if (k.startsWith("_") || v == null)
+                    continue;
+                entry[k] = typeof v === "string" ? await this.host.ref(v) : v;
+            }
+            ctx[alias].push(entry);
+        }
+        // Dep filtering: agent's dep_filters restrict which docs appear per alias
+        const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        if (agentKp) {
+            const filters = agentKp.depFilters();
+            if (filters) {
+                for (const [specField, targetAlias] of Object.entries(filters)) {
+                    if (!(targetAlias in ctx))
+                        continue;
+                    const declared = agentSpec[specField];
+                    if (declared == null || declared === "") {
+                        // Field not declared or empty -> filter to empty
+                        ctx[targetAlias] = [];
+                        continue;
+                    }
+                    if (typeof declared === "string") {
+                        ctx[targetAlias] = ctx[targetAlias].filter((e) => e.name === declared);
+                    }
+                    else if (Array.isArray(declared)) {
+                        if (declared.length === 0) {
+                            ctx[targetAlias] = [];
+                        }
+                        else {
+                            ctx[targetAlias] = ctx[targetAlias].filter((e) => declared.includes(e.name));
+                        }
+                    }
+                }
+            }
+        }
+        // Generic slot filtering: caller restricts which docs appear per slot.
+        if (agentKp && enabledSlots && Object.keys(enabledSlots).length > 0) {
+            const filters = agentKp.depFilters();
+            if (filters) {
+                for (const [slotName, enabledNames] of Object.entries(enabledSlots)) {
+                    const alias = filters[slotName];
+                    if (alias && alias in ctx) {
+                        ctx[alias] = ctx[alias]
+                            .filter((e) => enabledNames.includes(e.name));
+                    }
+                }
+            }
+        }
+        // Flatten: kinds with flattenInContext have their spec entries merged into ctx.
+        // String values (soul_content, agents_content, ...) get trailing
+        // whitespace normalized — the template supplies the joiners (i-013).
+        for (const doc of this.host.documents) {
+            const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+            if (!kp?.flattenInContext)
+                continue;
+            const spec = doc.spec;
+            for (const [k, v] of Object.entries(spec)) {
+                if (k.startsWith("_") || v == null)
+                    continue;
+                ctx[k] =
+                    typeof v === "string"
+                        ? stripPromptBlock(await this.host.ref(v))
+                        : v;
+            }
+        }
+        // Extra context from caller
+        if (extra) {
+            Object.assign(ctx, extra);
+        }
+        return ctx;
+    }
+    async _renderPrompt(ctx, agentDoc) {
+        const agentSpec = agentDoc.spec;
+        const kinds = this.host._kinds;
+        // 1. Agent-level template override
+        const agentTemplate = agentSpec.promptTemplate ??
+            agentSpec.prompt_template ??
+            null;
+        if (agentTemplate) {
+            return await this._mustacheRender(agentTemplate, ctx);
+        }
+        // 2. Kind default template
+        const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        if (agentKp) {
+            const kindTemplate = agentKp.promptTemplate();
+            if (kindTemplate) {
+                return await this._mustacheRender(kindTemplate, ctx);
+            }
+        }
+        // 3. Fallback: agent instruction as plain text
+        const agent = ctx.agent;
+        return agent?.instruction ?? "";
+    }
+    async _mustacheRender(template, ctx) {
+        // Resolve template if it's a file reference
+        let tmpl = template;
+        if (tmpl.includes("/") ||
+            tmpl.endsWith(".mustache") ||
+            tmpl.endsWith(".md")) {
+            tmpl = await this.host.ref(tmpl);
+        }
+        // Double render: first pass resolves Mustache tags, second pass resolves
+        // any tags that were inside resolved content.
+        const firstPass = Mustache.render(tmpl, ctx);
+        return Mustache.render(firstPass, ctx);
+    }
+    static _getDescription(doc) {
+        return doc.metadata.description ?? "";
+    }
+}