@sage-protocol/cli 0.4.0 → 0.4.1

package/dist/cli/services/mcp/env-loader.js

@@ -55,6 +55,8 @@ function hydrateEnvFromSageConfig(options = {}) {
       SUBDAO_FACTORY_ADDRESS: addresses.SUBDAO_FACTORY_ADDRESS || addresses.SUBDAO_FACTORY,
       LIBRARY_REGISTRY_ADDRESS: addresses.LIBRARY_REGISTRY_ADDRESS || addresses.LIBRARY_REGISTRY,
       SXXX_TOKEN_ADDRESS: addresses.SXXX_TOKEN_ADDRESS || addresses.SXXX,
+      SUBGRAPH_URL: addresses.SAGE_SUBGRAPH_URL || addresses.SUBGRAPH_URL,
+      SAGE_SUBGRAPH_URL: addresses.SAGE_SUBGRAPH_URL,
     };
     for (const [key, value] of Object.entries(mapping)) {
       if (value && typeof value === 'string' && !process.env[key]) {

package/dist/cli/services/mcp/quick-start.js

@@ -60,13 +60,12 @@ function createQuickStart({
         // Since LibraryManager doesn't expose "addPrompt", we'll implement it here for now
         // In a real refactor, we should move this to LibraryManager
 
-        const libDir = libraryManager.ensureLibrariesDir();
-        const manifestPath = path.join(libDir, `${targetLib.cid}.json`);
-
         // Create prompt file
         // We'll store it in a 'prompts' subdirectory next to the manifest if possible, 
         // but for local libraries, they are flat in ~/.sage/libraries/
         // Let's create a prompts directory inside ~/.sage/libraries/prompts/
+        const libDir = libraryManager.ensureLibrariesDir();
+        const manifestPath = libraryManager.getManifestPath(targetLib.cid);
         const promptsDir = path.join(libDir, 'prompts');
         if (!fs.existsSync(promptsDir)) {
             fs.mkdirSync(promptsDir, { recursive: true });
@@ -114,7 +113,7 @@ function createQuickStart({
             cid: '' // Local prompt
         });
 
-        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+        libraryManager.writeManifest(targetLib.cid, manifest);
 
         return {
             success: true,
@@ -129,19 +128,18 @@ function createQuickStart({
         if (!key) throw new Error('Key is required');
 
         // Find the prompt
-        const pinned = libraryManager.listPinned();
+            const pinned = libraryManager.listPinned();
         let found = null;
         let foundLib = null;
 
         for (const lib of pinned) {
-            const { manifest } = libraryManager.loadPinned(lib.cid);
-            const prompt = manifest.prompts?.find(p => p.key === key);
-            if (prompt) {
-                found = prompt;
-                const libDir = libraryManager.ensureLibrariesDir();
-                foundLib = { ...lib, manifest, manifestPath: path.join(libDir, `${lib.cid}.json`) };
-                break;
-            }
+                const { manifest } = libraryManager.loadPinned(lib.cid);
+                const prompt = manifest.prompts?.find(p => p.key === key);
+                if (prompt) {
+                    found = prompt;
+                    foundLib = { ...lib, manifest };
+                    break;
+                }
         }
 
         if (!found) {
@@ -150,13 +148,13 @@ function createQuickStart({
 
         // Update content if provided
         if (content) {
-            const libDir = libraryManager.ensureLibrariesDir();
             let promptFilePath;
 
             if (found.files && found.files.length > 0) {
                 // Use existing file
                 const relativePath = found.files[0];
                 // Handle potential path issues
+                const libDir = libraryManager.ensureLibrariesDir();
                 promptFilePath = path.join(libDir, relativePath);
 
                 // Backup existing
@@ -166,6 +164,7 @@ function createQuickStart({
                 }
             } else {
                 // Create new file if none existed (legacy/imported)
+                const libDir = libraryManager.ensureLibrariesDir();
                 const promptsDir = path.join(libDir, 'prompts');
                 if (!fs.existsSync(promptsDir)) fs.mkdirSync(promptsDir, { recursive: true });
                 const promptFileName = `${foundLib.cid}_${key}.md`;
@@ -210,7 +209,7 @@ function createQuickStart({
         }
 
         // Save manifest
-        fs.writeFileSync(foundLib.manifestPath, JSON.stringify(foundLib.manifest, null, 2), 'utf8');
+        libraryManager.writeManifest(foundLib.cid, foundLib.manifest);
 
         return {
             success: true,

package/dist/cli/services/mcp/sage-tool-registry.js

@@ -0,0 +1,330 @@
+// Central registry of core Sage MCP tools grouped by capability.
+// This is used by suggest_sage_tools to provide lightweight routing
+// and avoids hard-coding tool metadata in multiple places.
+//
+// Weight philosophy:
+// - 1.0: Standard tools (general purpose)
+// - 0.9: Primarily "list/browse" tools (lower-action, exploratory)
+// - 1.1–1.2: High-value "action" tools that accomplish concrete tasks
+
+const TOOL_REGISTRY = {
+  // ───────────── Prompt workspace tools ─────────────
+  search_prompts: {
+    category: 'prompt_workspace',
+    keywords: ['search', 'find', 'prompt', 'query', 'look', 'locate', 'discover'],
+    negativeKeywords: ['create', 'new', 'publish', 'delete'],
+    description: 'Search prompts across local workspace and on-chain libraries.',
+    whenToUse: 'Use when you need to find existing prompts by keyword, tag, or content.',
+    requiredParams: ['query'],
+    optionalParams: ['source', 'subdao', 'tags', 'includeContent'],
+    weight: 1.0,
+  },
+  list_prompts: {
+    category: 'prompt_workspace',
+    keywords: ['list', 'browse', 'prompt', 'workspace'],
+    negativeKeywords: ['search', 'publish'],
+    description: 'List prompts from local workspace and/or on-chain libraries.',
+    whenToUse: 'Use when you want a browseable list of prompts without a specific search query.',
+    requiredParams: [],
+    optionalParams: ['source', 'library', 'limit'],
+    weight: 0.9,
+  },
+  get_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['get', 'inspect', 'view', 'prompt', 'details'],
+    negativeKeywords: ['search', 'list'],
+    description: 'Retrieve a specific prompt by key, including its content.',
+    whenToUse: 'Use when you already know the prompt key and want full details for editing or reuse.',
+    requiredParams: ['key'],
+    optionalParams: ['library'],
+    weight: 1.0,
+  },
+  quick_create_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['create', 'new', 'write', 'add', 'draft', 'prompt'],
+    negativeKeywords: ['find', 'search', 'list'],
+    description: 'Create a new prompt with automatic library handling.',
+    whenToUse: 'Use when starting fresh with a new prompt idea.',
+    requiredParams: ['name', 'content'],
+    optionalParams: ['library', 'description', 'tags'],
+    weight: 1.2,
+  },
+  quick_iterate_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['edit', 'update', 'improve', 'iterate', 'refine'],
+    negativeKeywords: ['create', 'search'],
+    description: 'Modify an existing prompt in-place, keeping history in the workspace.',
+    whenToUse: 'Use when you want to refine or adjust an existing prompt.',
+    requiredParams: ['key', 'content'],
+    optionalParams: ['library', 'description'],
+    weight: 1.1,
+  },
+  test_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['test', 'render', 'evaluate', 'prompt', 'variables'],
+    negativeKeywords: ['search', 'list'],
+    description: 'Test a prompt by filling in ${variable} placeholders and viewing the rendered result.',
+    whenToUse: 'Use when you want to verify prompt behavior and variable substitution.',
+    requiredParams: ['key'],
+    optionalParams: ['library', 'variables'],
+    weight: 1.0,
+  },
+  quick_test_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['test', 'quick', 'run', 'prompt', 'variables'],
+    negativeKeywords: ['search', 'list'],
+    description: 'Alias for test_prompt. Quickly test a prompt with variables.',
+    whenToUse: 'Use when you want a shortcut to test_prompt for fast validation.',
+    requiredParams: ['key'],
+    optionalParams: ['variables'],
+    weight: 1.0,
+  },
+  list_workspace_skills: {
+    category: 'prompt_workspace',
+    keywords: ['skill', 'persona', 'workspace', 'list', 'browse'],
+    negativeKeywords: ['governance', 'publish'],
+    description: 'List skills/personas defined in the current project workspace.',
+    whenToUse: 'Use when you want to see available personas/skills for this project.',
+    requiredParams: [],
+    optionalParams: ['promptsDir'],
+    weight: 1.0,
+  },
+  improve_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['improve', 'refine', 'quality', 'analyze', 'prompt'],
+    negativeKeywords: ['create', 'publish'],
+    description: 'Analyze an existing prompt and suggest improvement areas and interview questions.',
+    whenToUse: 'Use when you have a working prompt and want structured suggestions for improvement.',
+    requiredParams: ['key'],
+    optionalParams: ['library', 'depth', 'focus'],
+    weight: 1.0,
+  },
+  rename_prompt: {
+    category: 'prompt_workspace',
+    keywords: ['rename', 'key', 'name', 'prompt'],
+    negativeKeywords: ['search'],
+    description: 'Rename a prompt key and/or display name while preserving content.',
+    whenToUse: 'Use when you need to change the identifier or display name of an existing prompt.',
+    requiredParams: ['key'],
+    optionalParams: ['newKey', 'name'],
+    weight: 0.9,
+  },
+  get_workspace_skill: {
+    category: 'prompt_workspace',
+    keywords: ['skill', 'persona', 'workspace', 'get', 'inspect'],
+    negativeKeywords: ['search'],
+    description: 'Load a specific workspace skill by path or key.',
+    whenToUse: 'Use when you know which skill you want to inspect or pass into an agent.',
+    requiredParams: ['path'],
+    optionalParams: [],
+    weight: 1.0,
+  },
+
+  // ───────────── Persona / metaprompt tools ─────────────
+  list_persona_templates: {
+    category: 'persona',
+    keywords: ['persona', 'template', 'list', 'browse', 'metaprompt'],
+    negativeKeywords: [],
+    description: 'List available persona templates (coding assistant, governance helper, etc.).',
+    whenToUse: 'Use when you are deciding what kind of assistant/persona to design.',
+    requiredParams: [],
+    optionalParams: [],
+    weight: 1.0,
+  },
+  run_persona_interview: {
+    category: 'persona',
+    keywords: ['persona', 'interview', 'one-shot', 'create', 'system prompt'],
+    negativeKeywords: ['stepwise', 'stateful'],
+    description: 'Build a persona/system prompt in one shot from provided answers.',
+    whenToUse: 'Use when you already have answers for the persona slots and just need a system prompt.',
+    requiredParams: ['template', 'answers'],
+    optionalParams: ['save', 'saveKey'],
+    weight: 1.2,
+  },
+  persona_interview_step: {
+    category: 'persona',
+    keywords: ['persona', 'interview', 'step', 'slot', 'stateful'],
+    negativeKeywords: ['one-shot'],
+    description: 'Advance a stateful persona interview by one step, returning slot metadata.',
+    whenToUse: 'Use when you want the host LLM to run a multi-turn interview over persona slots.',
+    requiredParams: [],
+    optionalParams: ['template', 'stateToken', 'answer'],
+    weight: 1.1,
+  },
+  save_metaprompt: {
+    category: 'persona',
+    keywords: ['metaprompt', 'save', 'store', 'persona'],
+    negativeKeywords: [],
+    description: 'Save a metaprompt/persona definition into the Sage workspace.',
+    whenToUse: 'Use when you want to persist a finalized persona or system prompt.',
+    requiredParams: ['title', 'body'],
+    optionalParams: ['summary', 'tags', 'appendAgentsFile'],
+    weight: 1.0,
+  },
+  get_metaprompt: {
+    category: 'persona',
+    keywords: ['metaprompt', 'persona', 'load', 'get'],
+    negativeKeywords: [],
+    description: 'Load an existing metaprompt/persona by slug.',
+    whenToUse: 'Use when you want to reuse or inspect a previously saved persona.',
+    requiredParams: ['slug'],
+    optionalParams: [],
+    weight: 1.0,
+  },
+
+  // ───────────── Library / manifest tools ─────────────
+  list_libraries: {
+    category: 'libraries',
+    keywords: ['library', 'libraries', 'list', 'browse', 'manifest'],
+    negativeKeywords: [],
+    description: 'List available prompt libraries from local workspace or on-chain.',
+    whenToUse: 'Use when you want to see which libraries/manifests are available.',
+    requiredParams: [],
+    optionalParams: ['source', 'subdao', 'limit'],
+    weight: 1.0,
+  },
+  get_prompts_from_manifest: {
+    category: 'libraries',
+    keywords: ['manifest', 'library', 'prompt', 'list', 'get'],
+    negativeKeywords: [],
+    description: 'Get all prompts from a specific manifest by CID.',
+    whenToUse: 'Use when you have a manifest CID and want to inspect its prompts.',
+    requiredParams: ['manifestCid'],
+    optionalParams: ['includeContent'],
+    weight: 1.0,
+  },
+  list_templates: {
+    category: 'libraries',
+    keywords: ['template', 'list', 'browse', 'prompt'],
+    negativeKeywords: [],
+    description: 'List available prompt templates for quick creation.',
+    whenToUse: 'Use when you want to see reusable prompt templates (not personas).',
+    requiredParams: [],
+    optionalParams: ['category', 'search'],
+    weight: 0.9,
+  },
+  create_from_template: {
+    category: 'libraries',
+    keywords: ['template', 'create', 'new', 'prompt'],
+    negativeKeywords: [],
+    description: 'Create a new prompt from a template and save into a library.',
+    whenToUse: 'Use when you want to quickly scaffold a prompt from an existing template.',
+    requiredParams: ['template', 'customize'],
+    optionalParams: ['library', 'name'],
+    weight: 1.1,
+  },
+  get_prompt_content: {
+    category: 'libraries',
+    keywords: ['get', 'prompt', 'content', 'ipfs', 'cid'],
+    negativeKeywords: ['search'],
+    description: 'Fetch full prompt content from IPFS by CID.',
+    whenToUse: 'Use when you have an IPFS CID and need the underlying prompt content.',
+    requiredParams: ['cid'],
+    optionalParams: [],
+    weight: 1.0,
+  },
+
+  // ───────────── Governance tools ─────────────
+  publish_manifest_flow: {
+    category: 'governance',
+    keywords: ['publish', 'manifest', 'dao', 'subdao', 'governance'],
+    negativeKeywords: [],
+    description: 'Prepare a manifest for on-chain publishing and generate CLI commands.',
+    whenToUse: 'Use when you are ready to publish a library/manifest to a SubDAO.',
+    requiredParams: ['manifest'],
+    optionalParams: ['subdao', 'description', 'dry_run'],
+    weight: 1.2,
+  },
+  list_proposals: {
+    category: 'governance',
+    keywords: ['proposal', 'governance', 'list', 'dao', 'subdao'],
+    negativeKeywords: [],
+    description: 'List active proposals for a specific SubDAO.',
+    whenToUse: 'Use when you want to inspect or track current governance proposals.',
+    requiredParams: [],
+    optionalParams: ['state', 'subdao', 'limit'],
+    weight: 1.0,
+  },
+  suggest_subdaos_for_library: {
+    category: 'governance',
+    keywords: ['subdao', 'suggest', 'library', 'publish', 'dao'],
+    negativeKeywords: [],
+    description: 'Suggest suitable SubDAOs for publishing a given library manifest.',
+    whenToUse: 'Use when you have a library and want advice on where to publish it.',
+    requiredParams: ['library'],
+    optionalParams: ['limit'],
+    weight: 1.0,
+  },
+  generate_publishing_commands: {
+    category: 'governance',
+    keywords: ['publish', 'commands', 'cli', 'dao', 'subdao'],
+    negativeKeywords: [],
+    description: 'Generate CLI commands for validating, uploading, and proposing a manifest.',
+    whenToUse: 'Use after selecting a SubDAO to get concrete CLI commands for publishing.',
+    requiredParams: ['library'],
+    optionalParams: ['target'],
+    weight: 1.0,
+  },
+
+  // ───────────── Treasury / SubDAO tools ─────────────
+  list_subdaos: {
+    category: 'treasury',
+    keywords: ['subdao', 'dao', 'list', 'treasury', 'governance'],
+    negativeKeywords: [],
+    description: 'List all available SubDAOs in the Sage Protocol.',
+    whenToUse: 'Use when you want an overview of existing SubDAOs/treasuries.',
+    requiredParams: [],
+    optionalParams: ['limit'],
+    weight: 0.9,
+  },
+  list_subdao_libraries: {
+    category: 'treasury',
+    keywords: ['subdao', 'library', 'libraries', 'list'],
+    negativeKeywords: [],
+    description: 'List libraries associated with a specific SubDAO.',
+    whenToUse: 'Use when you want to see what libraries a SubDAO currently governs.',
+    requiredParams: ['subdao'],
+    optionalParams: [],
+    weight: 1.0,
+  },
+
+  // ───────────── Discovery / helper tools ─────────────
+  trending_prompts: {
+    category: 'discovery',
+    keywords: ['trending', 'popular', 'recent', 'discover', 'prompt'],
+    negativeKeywords: ['create'],
+    description: 'List trending prompts from recent LibraryRegistry updates.',
+    whenToUse: 'Use when you want to discover popular or recently active prompts.',
+    requiredParams: [],
+    optionalParams: ['decayMinutes', 'limit'],
+    weight: 0.9,
+  },
+  help: {
+    category: 'discovery',
+    keywords: ['help', 'usage', 'docs', 'explain'],
+    negativeKeywords: [],
+    description: 'Get help on how to use Sage MCP tools and workflows.',
+    whenToUse: 'Use when you need guidance on which Sage tools to use or how to call them.',
+    requiredParams: [],
+    optionalParams: ['topic'],
+    weight: 0.9,
+  },
+};
+
+function getToolsForCategory(category) {
+  return Object.entries(TOOL_REGISTRY)
+    .filter(([, meta]) => meta.category === category)
+    .map(([name, meta]) => ({ name, ...meta }));
+}
+
+function getToolMeta(name) {
+  const meta = TOOL_REGISTRY[name];
+  if (!meta) return null;
+  return { name, ...meta };
+}
+
+module.exports = {
+  TOOL_REGISTRY,
+  getToolsForCategory,
+  getToolMeta,
+};

package/dist/cli/services/mcp/tool-args-validator.js

@@ -5,6 +5,24 @@ function createToolArgsValidator({ zodModule } = {}) {
   }
 
   const schemas = {
+    suggest_sage_tools: Z.object({
+      goal: Z.string().min(1).max(1000),
+      stage: Z.enum([
+        'prompt_workspace',
+        'persona',
+        'libraries',
+        'governance',
+        'treasury',
+        'discovery',
+      ]).optional(),
+      context: Z.object({
+        hasWorkspace: Z.boolean().optional(),
+        hasWallet: Z.boolean().optional(),
+        currentTask: Z.string().max(200).optional(),
+      }).optional(),
+      limit: Z.number().int().min(1).max(10).optional().default(5),
+      includeAlternatives: Z.boolean().optional().default(false),
+    }),
     search_prompts: Z.object({
       query: Z.string().max(256).optional().default(''),
       source: Z.enum(['local', 'onchain', 'all']).optional().default('all'),
@@ -38,6 +56,19 @@ function createToolArgsValidator({ zodModule } = {}) {
       model: Z.string().max(100).optional(),
       interviewStyle: Z.string().max(200).optional(),
     }),
+    list_persona_templates: Z.object({}),
+    run_persona_interview: Z.object({
+      template: Z.string().min(1).max(200),
+      answers: Z.record(Z.any()),
+      save: Z.boolean().optional().default(false),
+      saveKey: Z.string().min(1).max(200).optional(),
+    }),
+    persona_interview_step: Z.object({
+      // template is required on first call, optional when stateToken is provided
+      template: Z.string().min(1).max(200).optional().default('custom'),
+      stateToken: Z.string().max(16000).optional(), // increased for slots + answers
+      answer: Z.string().max(8000).optional(),
+    }),
     save_metaprompt: Z.object({
       title: Z.string().min(1).max(200),
       summary: Z.string().max(500).optional().default(''),

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

@@ -0,0 +1,87 @@
+let Anthropic;
+try {
+  // Lazy / guarded require so OpenAI-only setups don't crash on import
+  // eslint-disable-next-line global-require
+  Anthropic = require('@anthropic-ai/sdk');
+} catch (err) {
+  // Defer error until someone actually tries to construct the client
+  Anthropic = null;
+}
+
+/**
+ * Client for interacting with Anthropic's Claude API.
+ * Follows the ModelClient interface.
+ */
+class AnthropicClient {
+  /**
+   * @param {object} config
+   * @param {string} config.apiKey
+   * @param {string} [config.model]
+   * @param {number} [config.temperature]
+   */
+  constructor({ apiKey, model, temperature }) {
+    if (!Anthropic) {
+      throw new Error('Anthropic SDK not installed. Please add @anthropic-ai/sdk or configure a different provider.');
+    }
+    this.apiKey = apiKey;
+    this.model = model || 'claude-sonnet-4-20250514';
+    this.temperature = temperature ?? 0.7;
+    
+    this.client = new Anthropic({
+      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) {
+    // Convert 'developer' role to 'system' property, as Anthropic handles system prompts separately
+    const systemMessage = messages.find(m => m.role === 'system' || m.role === 'developer');
+    const userAssistantMessages = messages.filter(m => m.role !== 'system' && m.role !== 'developer');
+
+    const stream = await this.client.messages.create({
+      model: this.model,
+      system: systemMessage ? systemMessage.content : undefined,
+      messages: userAssistantMessages,
+      max_tokens: 4096,
+      temperature: this.temperature,
+      stream: true,
+    });
+
+    let fullText = '';
+    for await (const chunk of stream) {
+      if (chunk.type === 'content_block_delta' && chunk.delta.type === 'text_delta') {
+        const content = chunk.delta.text;
+        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 systemMessage = messages.find(m => m.role === 'system' || m.role === 'developer');
+    const userAssistantMessages = messages.filter(m => m.role !== 'system' && m.role !== 'developer');
+
+    const response = await this.client.messages.create({
+      model: this.model,
+      system: systemMessage ? systemMessage.content : undefined,
+      messages: userAssistantMessages,
+      max_tokens: 4096,
+      temperature: this.temperature,
+    });
+
+    return response.content[0].text || '';
+  }
+}
+
+module.exports = AnthropicClient;