@sage-protocol/cli 0.4.0 → 0.4.2

package/dist/cli/services/metaprompt/openai-client.js

@@ -0,0 +1,67 @@
+const OpenAI = require('openai');
+
+/**
+ * Client for interacting with OpenAI's chat API.
+ * Follows the ModelClient interface:
+ * - streamChat(messages, onToken): Promise<fullText>
+ * - complete(messages): Promise<fullText>
+ */
+class OpenAIClient {
+  /**
+   * @param {object} config
+   * @param {string} config.apiKey
+   * @param {string} [config.model]
+   * @param {number} [config.temperature]
+   */
+  constructor({ apiKey, model, temperature }) {
+    this.apiKey = apiKey;
+    this.model = model || 'gpt-4o';
+    this.temperature = temperature ?? 0.7;
+    
+    this.client = new OpenAI({
+      apiKey: this.apiKey,
+    });
+  }
+
+  /**
+   * Stream chat completion.
+   * @param {Array<{role:string, content:string}>} messages
+   * @param {(token:string) => void} [onToken] Callback for each token
+   * @returns {Promise<string>} Full response text
+   */
+  async streamChat(messages, onToken) {
+    const stream = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      temperature: this.temperature,
+      stream: true,
+    });
+
+    let fullText = '';
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content || '';
+      if (content) {
+        fullText += content;
+        if (onToken) onToken(content);
+      }
+    }
+    return fullText;
+  }
+
+  /**
+   * Non-streaming chat completion.
+   * @param {Array<{role:string, content:string}>} messages
+   * @returns {Promise<string>} Full response text
+   */
+  async complete(messages) {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      temperature: this.temperature,
+    });
+    return completion.choices[0]?.message?.content || '';
+  }
+}
+
+module.exports = OpenAIClient;
+

package/dist/cli/services/metaprompt/persistence.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+const path = require('path');
+
+class MetapromptPersistence {
+  constructor(config) {
+    this.config = config;
+    this.projectDir = config.getProjectDir();
+  }
+
+  getPaths(slug) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return {
+      metaprompt: path.join(this.projectDir, '.sage', 'metaprompts', `${slug}.md`),
+      skill: path.join(this.projectDir, 'prompts', 'skills', `${slug}.md`),
+      history: path.join(this.projectDir, '.sage', 'metaprompts', 'history', `${slug}-${timestamp}.json`),
+    };
+  }
+
+  saveMetaprompt(slug, data) {
+    const paths = this.getPaths(slug);
+    
+    // Ensure dirs
+    fs.mkdirSync(path.dirname(paths.metaprompt), { recursive: true });
+    fs.mkdirSync(path.dirname(paths.history), { recursive: true });
+
+    // 1. Save history JSON (The "Metaprompt Artifact")
+    fs.writeFileSync(paths.history, JSON.stringify(data, null, 2));
+
+    // 2. Save readable Markdown Metaprompt (Source of Truth)
+    const mdContent = `---
+slug: ${slug}
+template: ${data.templateKey}
+date: ${new Date().toISOString()}
+---
+
+# Metaprompt Session: ${slug}
+
+## Transcript
+${data.transcript.map(t => `**${t.role.toUpperCase()}**: ${t.content}`).join('\n\n')}
+
+## Filled Slots
+\`\`\`json
+${JSON.stringify(data.answers, null, 2)}
+\`\`\`
+`;
+    fs.writeFileSync(paths.metaprompt, mdContent);
+    
+    return paths;
+  }
+
+  saveSkill(slug, systemPrompt) {
+    const paths = this.getPaths(slug);
+    fs.mkdirSync(path.dirname(paths.skill), { recursive: true });
+
+    const content = `---
+title: ${slug} (Generated Agent)
+description: Generated via sage interview
+---
+
+${systemPrompt}
+`;
+    fs.writeFileSync(paths.skill, content);
+    return paths.skill;
+  }
+
+  appendToAgentsList(slug) {
+    const agentsPath = path.join(this.projectDir, 'prompts', 'agents.md');
+    const dir = path.dirname(agentsPath);
+    if (!fs.existsSync(dir)) return;
+
+    const entry = `- [${slug}](./skills/${slug}.md)`;
+    let existing = '';
+    if (fs.existsSync(agentsPath)) {
+      try {
+        existing = fs.readFileSync(agentsPath, 'utf8');
+        if (existing.includes(entry)) return; // avoid duplicates
+      } catch (_) {
+        existing = '';
+      }
+    }
+    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(agentsPath, `${prefix}${entry}\n`);
+  }
+}
+
+module.exports = MetapromptPersistence;

package/dist/cli/services/metaprompt/prompt-builder.js

@@ -0,0 +1,186 @@
+const templates = require('./templates.json');
+
+/**
+ * Mapping of slot groups to section names and order.
+ * This normalizes the various group names used in templates.
+ */
+const GROUP_MAPPINGS = {
+  // Identity-related
+  'identity': 'identity',
+  'role': 'identity',
+
+  // Goals-related
+  'goals': 'goals',
+  'goal': 'goals',
+
+  // Context-related
+  'context': 'context',
+  'stack': 'context',
+
+  // Constraints-related
+  'constraints': 'constraints',
+  'guidelines': 'constraints',
+
+  // Tools-related
+  'tools': 'tools',
+
+  // Output-related
+  'output': 'output',
+  'format': 'output',
+};
+
+/**
+ * Tool definitions for inject_tools feature.
+ * Maps tool names to descriptions.
+ */
+const TOOL_DEFINITIONS = {
+  'sage prompts': '`sage prompts`: Workspace-first prompt and skill management (init, list, diff, publish).',
+  'sage project': '`sage project`: Manifest management, IPFS publishing, and governance proposal helpers.',
+  'sage governance': '`sage governance`: Governance commands for viewing proposals, voting, and managing SubDAOs.',
+  'sage gov': '`sage gov`: Alias for sage governance - proposal management and voting.',
+  'sage treasury': '`sage treasury`: Treasury inspection, withdrawals, boosts, and bond operations.',
+  'sage ipfs': '`sage ipfs`: IPFS operations including pinning, fetching, and gateway management.',
+  'sage dev': '`sage dev`: Development commands for building, testing, and deploying.',
+  'sage config': '`sage config`: Configuration management for RPC, wallets, and AI providers.',
+  'sage mcp': '`sage mcp`: MCP server management for agent integrations.',
+};
+
+class PromptBuilder {
+  constructor() {
+    // Could be extended to load custom tool definitions
+  }
+
+  /**
+   * Builds the final system prompt string from the filled slots.
+   * @param {string} templateKey
+   * @param {Array} slots - Definition of slots
+   * @param {Object} answers - Key-value pairs of filled answers
+   * @returns {string} The final XML-structured system prompt
+   */
+  buildSystemPrompt(templateKey, slots, answers) {
+    const template = templates[templateKey] || templates['custom'];
+
+    // Build sections in order
+    const sections = [];
+
+    // 1. Role/Identity section
+    const identityContent = this.#buildGroupSection(slots, answers, 'identity');
+    const roleContent = this.#getAnswer(answers, 'role') || identityContent || template.description;
+    if (roleContent) {
+      sections.push(this.#buildSection('role', roleContent));
+    }
+
+    // 2. Goals section
+    const goalsContent = this.#buildGroupSection(slots, answers, 'goals');
+    const goalContent = this.#getAnswer(answers, 'goal') || goalsContent || template.default_goal;
+    if (goalContent) {
+      sections.push(this.#buildSection('goals', goalContent));
+    }
+
+    // 3. Context section (tech stack, data sources, etc.)
+    const contextSection = this.#buildGroupSection(slots, answers, 'context');
+    if (contextSection) {
+      sections.push(this.#buildSection('context', contextSection));
+    }
+
+    // 4. Constraints section
+    const constraintsSection = this.#buildGroupSection(slots, answers, 'constraints');
+    if (constraintsSection) {
+      sections.push(this.#buildSection('constraints', constraintsSection));
+    }
+
+    // 5. Tools section
+    const toolsSection = this.#buildToolsSection(template.inject_tools, answers, slots);
+    if (toolsSection) {
+      sections.push(toolsSection);
+    }
+
+    // 6. Output format section
+    const outputSection = this.#buildGroupSection(slots, answers, 'output');
+    if (outputSection) {
+      sections.push(this.#buildSection('output_format', outputSection));
+    }
+
+    // 7. Final reminder
+    sections.push(`Remember: You are ${template.name}. Stay in character and follow your constraints.`);
+
+    return sections.filter(Boolean).join('\n\n');
+  }
+
+  #getAnswer(answers, key) {
+    return answers[key] || '';
+  }
+
+  #buildSection(title, content) {
+    if (!content) return '';
+    const tag = this.#sanitizeTag(title);
+    return `<${tag}>\n${content}\n</${tag}>`;
+  }
+
+  #sanitizeTag(title) {
+    // Remove special chars, replace spaces with underscores, lowercase
+    return title.toLowerCase().replace(/[^a-z0-9_]/g, '_').replace(/_+/g, '_');
+  }
+
+  /**
+   * Build a section from all slots matching a normalized group.
+   */
+  #buildGroupSection(slots, answers, normalizedGroup) {
+    // Find slots matching this group (handling group name variations)
+    const groupSlots = slots.filter(slot => {
+      const slotGroup = (slot.group || '').toLowerCase();
+      const mapped = GROUP_MAPPINGS[slotGroup] || slotGroup;
+      return mapped === normalizedGroup;
+    });
+
+    if (!groupSlots.length) return '';
+
+    const lines = groupSlots.map(slot => {
+      const ans = answers[slot.key];
+      if (!ans) return null;
+      return `- **${slot.label}**: ${ans}`;
+    }).filter(Boolean);
+
+    return lines.length ? lines.join('\n') : '';
+  }
+
+  #buildToolsSection(injectedTools = [], answers, slots) {
+    const definitions = [];
+
+    // Add injected tools from template
+    for (const tool of injectedTools) {
+      const def = TOOL_DEFINITIONS[tool];
+      if (def) {
+        definitions.push(`- ${def}`);
+      } else {
+        // Unknown tool - add a generic entry
+        definitions.push(`- \`${tool}\`: Available tool (see documentation).`);
+      }
+    }
+
+    // Add tools from slots with 'tools' group
+    const toolSlots = slots.filter(s => GROUP_MAPPINGS[s.group] === 'tools');
+    for (const slot of toolSlots) {
+      const ans = answers[slot.key];
+      if (ans && !definitions.some(d => d.includes(ans))) {
+        definitions.push(`- ${ans}`);
+      }
+    }
+
+    // Add generic tool answer if provided
+    if (answers.tools && !definitions.some(d => d.includes(answers.tools))) {
+      definitions.push(`- ${answers.tools}`);
+    }
+
+    if (!definitions.length) return '';
+
+    return `<tools>
+You have access to the following tools and capabilities:
+${definitions.join('\n')}
+
+Use these tools when appropriate to fulfill the user's request.
+</tools>`;
+  }
+}
+
+module.exports = PromptBuilder;

package/dist/cli/services/metaprompt/session.js

@@ -1,32 +1,33 @@
+const { createModelClient } = require('./model-client');
+
 class MetapromptSession {
   constructor(options = {}) {
     const {
       title,
       goal,
-      targetModel = 'gpt-5',
       interviewStyle = 'one-question-at-a-time',
-      apiKey,
       temperature = 0.7,
-      axios,
-      process,
-      env,
-      openAiModel = (env || process?.env || global.process.env).SAGE_METAPROMPT_MODEL || 'gpt-4o-mini',
+      process: proc,
+      config, // injected config dependency
+      provider, // optional override
+      model,    // optional override
+      apiKey,   // optional override
     } = options;
 
-    this.axios = axios || require('axios');
-    this.process = process || global.process;
-    this.env = env || this.process.env;
+    this.process = proc || global.process;
+    this.config = config || require('../../config'); // fallback to global require if not passed
 
-    if (!apiKey) {
-      throw new Error('Missing OpenAI API key. Configure one with `sage config ai set --provider openai --key sk-...` or set OPENAI_API_KEY.');
+    // Initialize the ModelClient using the factory
+    try {
+      this.client = createModelClient(this.config, { provider, model, apiKey });
+    } catch (error) {
+      // If createModelClient fails (no keys), re-throw with the helpful message
+      throw error;
     }
 
     this.title = title || 'Untitled Metaprompt';
     this.goal = goal || 'Design a high quality system prompt.';
-    this.targetModel = targetModel;
-    this.openAiModel = openAiModel;
     this.interviewStyle = interviewStyle;
-    this.apiKey = apiKey;
     this.temperature = temperature;
 
     this.messages = [
@@ -48,7 +49,6 @@ class MetapromptSession {
       'Before emitting FINAL_PROMPT, summarise the agreed requirements and confirm readiness.',
       'If the user types `/finish` or explicitly asks you to finalise, produce the FINAL_PROMPT immediately.',
       `Primary goal: ${this.goal}.`,
-      `Target downstream model: ${this.targetModel}.`,
       `Interview cadence preference: ${this.interviewStyle}.`,
       'Guardrails: capture constraints, desired behaviours, failure modes, tone, tooling, fallback defaults, and evaluation hooks.',
       'When providing FINAL_PROMPT, include only the polished system prompt inside the fenced block (no commentary).',
@@ -66,55 +66,6 @@ class MetapromptSession {
     this.transcript.push({ role, content, timestamp: new Date().toISOString() });
   }
 
-  async requestAssistantMessage(onToken) {
-    const response = await this.axios.post(
-      'https://api.openai.com/v1/chat/completions',
-      {
-        model: this.openAiModel,
-        messages: this.messages,
-        temperature: this.temperature,
-        stream: true,
-      },
-      {
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          'Content-Type': 'application/json',
-        },
-        responseType: 'stream',
-      }
-    );
-
-    return new Promise((resolve, reject) => {
-      let buffer = '';
-      let fullText = '';
-      response.data.on('data', (chunk) => {
-        buffer += chunk.toString('utf8');
-        const lines = buffer.split('\n');
-        buffer = lines.pop() || '';
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed.startsWith('data:')) continue;
-          const payload = trimmed.slice(5).trim();
-          if (!payload || payload === '[DONE]') continue;
-          try {
-            const parsed = JSON.parse(payload);
-            const delta = parsed.choices?.[0]?.delta || {};
-            if (typeof delta.content === 'string' && delta.content.length) {
-              fullText += delta.content;
-              if (typeof onToken === 'function') onToken(delta.content);
-            }
-            if (delta.role === 'assistant' && typeof onToken === 'function') {
-              onToken('');
-            }
-          } catch (_) {}
-        }
-      });
-
-      response.data.on('end', () => resolve(fullText.trim()));
-      response.data.on('error', (error) => reject(error));
-    });
-  }
-
   extractFinalPrompt(text) {
     if (!text) return null;
     const match = /FINAL_PROMPT\s*```(?:[a-zA-Z0-9_-]+\n)?([\s\S]*?)```/i.exec(text);
@@ -131,24 +82,13 @@ class MetapromptSession {
     this.#appendTranscript('user', this.messages[1].content);
 
     while (!this.finalPrompt) {
-      let assistantMessage;
+      let assistantMessage = '';
       try {
-        assistantMessage = await this.requestAssistantMessage((token) => {
+        assistantMessage = await this.client.streamChat(this.messages, (token) => {
           if (token) printAssistant(token);
         });
       } catch (error) {
-        const status = error?.response?.status;
-        let detail = error?.response?.data?.error?.message;
-        if (!detail && error?.response?.data) {
-          try {
-            detail = JSON.stringify(error.response.data);
-          } catch (_) {}
-        }
-        if (!detail) detail = error.message;
-        const hint = detail && detail.includes('model')
-          ? ' (hint: set SAGE_METAPROMPT_MODEL or choose a supported OpenAI model)'
-          : '';
-        throw new Error(status ? `OpenAI error (${status}): ${detail}${hint}` : `OpenAI error: ${detail}${hint}`);
+        throw new Error(`AI Model error: ${error.message}`);
       }
 
       if (assistantMessage) {
@@ -192,8 +132,6 @@ class MetapromptSession {
       finalAssistantMessage: this.finalAssistantMessage,
       transcript: this.transcript,
       messages: this.messages,
-      targetModel: this.targetModel,
-      openAiModel: this.openAiModel,
     };
   }
 }

package/dist/cli/services/metaprompt/slot-planner.js

@@ -0,0 +1,115 @@
+const { createModelClient } = require('./model-client');
+const templates = require('./templates.json');
+
+class SlotPlanner {
+  /**
+   * @param {object} config CLI config object
+   * @param {object} [options]
+   * @param {object} [options.client] optional shared ModelClient instance
+   * @param {string} [options.provider]
+   * @param {string} [options.model]
+   * @param {string} [options.apiKey]
+   */
+  constructor(config, options = {}) {
+    this.config = config;
+    this.overrides = {
+      provider: options.provider,
+      model: options.model,
+      apiKey: options.apiKey,
+    };
+    this.client = options.client || null;
+  }
+
+  /**
+   * Generates a plan of slots (information requirements) for the persona.
+   * @param {string} templateKey - The key of the template (e.g., 'coding-assistant').
+   * @param {string} initialDescription - The user's initial input/goal.
+   * @param {string[]} [contextTags] - Optional tags to guide planning.
+   * @returns {Promise<Array>} Array of slot objects.
+   */
+  async planSlots(templateKey, initialDescription, contextTags = []) {
+    const template = templates[templateKey] || templates['custom'];
+    const recommended = template.recommended_slots || [];
+
+    // For standard personas, default to static recommended slots to avoid unnecessary LLM calls.
+    // Use the planner primarily for the "custom" template (or when explicitly configured).
+    if (templateKey !== 'custom') {
+      return recommended.slice().sort((a, b) => a.priority - b.priority);
+    }
+
+    // System prompt for the planner LLM
+    const systemPrompt = `
+You are an expert Metaprompt Architect. Your goal is to design a structured "Slot Plan" for a new AI Persona.
+A "Slot" is a specific piece of information we need to collect from the user to build a high-quality system prompt.
+
+Template Context: ${template.name} - ${template.description}
+Planner Instructions: ${template.planner_instructions}
+
+Existing Recommended Slots:
+${JSON.stringify(recommended, null, 2)}
+
+User's Initial Description: "${initialDescription}"
+Context Tags: ${contextTags.join(', ')}
+
+Your Task:
+1. Analyze the User's Description and the Template Instructions.
+2. Determine if the Recommended Slots are sufficient, or if new custom slots are needed.
+3. If the user has *already* provided information for a slot in their description, you should still list the slot but mark it as potentially filled (this logic happens later, just define the schema now).
+4. Return a JSON array of Slot objects.
+
+Slot Schema:
+{
+  "key": "snake_case_key",
+  "label": "Human Readable Label",
+  "description": "Question/Prompt to ask the user to fill this slot",
+  "required": boolean,
+  "priority": number (1=Critical, 5=Nice to have),
+  "group": "identity" | "context" | "constraints" | "tools" | "output"
+}
+
+CRITICAL: Return ONLY the JSON array. No markdown formatting, no code blocks.
+`;
+
+    const messages = [
+      { role: 'system', content: systemPrompt.trim() },
+      { role: 'user', content: 'Generate the slot plan.' }
+    ];
+
+    try {
+      if (!this.client) {
+        this.client = createModelClient(this.config, this.overrides);
+      }
+      const response = await this.client.complete(messages);
+      let plan = [];
+      
+      // clean potential markdown blocks
+      const cleanJson = response.replace(/```json/g, '').replace(/```/g, '').trim();
+      
+      try {
+        plan = JSON.parse(cleanJson);
+      } catch (e) {
+        // Fallback: if JSON parse fails, just use recommended slots
+        console.warn('SlotPlanner: Failed to parse LLM response, using defaults.', e.message);
+        return recommended;
+      }
+
+      // Merge recommended slots if they aren't present (or if LLM hallucinated them away)
+      // Ideally the LLM includes them, but let's ensure critical ones exist.
+      for (const rec of recommended) {
+        if (!plan.find(p => p.key === rec.key)) {
+          plan.push(rec);
+        }
+      }
+
+      // Sort by priority
+      return plan.sort((a, b) => a.priority - b.priority);
+
+    } catch (error) {
+      console.error('SlotPlanner Error:', error);
+      // Fallback to recommended
+      return recommended;
+    }
+  }
+}
+
+module.exports = SlotPlanner;