create-yonderclaw 1.0.0

package/installer/modules/swarm/swarm/types.ts.txt

@@ -0,0 +1,51 @@
+/**
+ * MetaClaw Swarm — Shared Types
+ * QIS-inspired bucket system for intelligence sharing
+ */
+
+export interface OutcomePacket {
+  v: 1;
+  bucket: string;                    // canonical problem path e.g. "outreach.email.cold.response_rate_low"
+  bucket_id: string;                 // SHA-256 hash of bucket path (first 16 hex chars)
+  ts: number;                        // Unix timestamp
+  agent_id: string;                  // anonymized, e.g. "mc_anon_7f3a"
+  outcome: {
+    signal: "positive" | "negative" | "neutral";
+    confidence: number;              // 0-1
+    insight: string;                 // the actual knowledge
+    context: Record<string, any>;    // structured metadata for filtering
+    metrics?: {
+      sample_size?: number;
+      effect_size?: number;
+      stat_sig?: boolean;
+    };
+  };
+  sig?: string;                      // Ed25519 signature (future)
+}
+
+export interface BucketMeta {
+  bucket_id: string;
+  path: string;                      // canonical problem path
+  domain: string;                    // first segment e.g. "outreach"
+  title: string;                     // human-readable
+  description: string;
+  conditions: string[];              // when this bucket applies
+  exclusions: string[];              // when it does NOT apply
+  packet_count: number;
+  last_updated: string;
+  confidence_avg: number;
+}
+
+export interface BucketIndex {
+  version: number;
+  updated_at: string;
+  buckets: BucketMeta[];
+}
+
+export interface SwarmConfig {
+  relay_url: string;
+  agent_id: string;
+  enabled: boolean;
+  publish: boolean;                  // contribute insights to meta swarm
+  subscribe: boolean;                // pull insights from meta swarm
+}

package/installer/modules/voice/metaclaw-module.json

@@ -0,0 +1,16 @@
+{
+  "name": "voice",
+  "displayName": "Voice — Push-to-Talk & TTS",
+  "version": "1.0.0",
+  "description": "Browser-based voice I/O: push-to-talk, always-on listening, Microsoft Jenny neural TTS",
+  "category": "ui",
+  "alwaysInstall": true,
+  "engines": { "metaclaw": ">=3.3.0" },
+  "requires": { "modules": ["dashboard"] },
+  "contributes": {
+    "dashboard": {
+      "inject": "voice"
+    },
+    "claudeMd": ["voice"]
+  }
+}

package/installer/questionnaire.ts

@@ -0,0 +1,277 @@
+/**
+ * MetaClaw Questionnaire — Claude-powered needs assessment
+ *
+ * Asks the user what they need, then uses Claude to research
+ * best practices and generate an optimal agent configuration.
+ */
+
+import * as clack from "@clack/prompts";
+import chalk from "chalk";
+import { brand, purple, muted, accent, sectionHeader } from "./brand.js";
+import type { SystemInfo } from "./detect.js";
+
+export type ClawTemplate = {
+  id: string;
+  name: string;
+  description: string;
+  hint: string;
+  icon: string;
+  requiredTools: string[];
+  optionalTools: string[];
+  questions: Array<{
+    key: string;
+    message: string;
+    type: "text" | "select" | "confirm";
+    options?: Array<{ value: string; label: string; hint?: string }>;
+    placeholder?: string;
+    default?: string;
+  }>;
+};
+
+// --- Claw Templates ---
+export const CLAW_TEMPLATES: ClawTemplate[] = [
+  {
+    id: "outreach",
+    name: "Outreach Claw",
+    description: "Email prospecting, follow-ups, auto-reply, AI detection gate",
+    hint: "sales, partnerships, networking",
+    icon: "📧",
+    requiredTools: ["gmail_smtp", "gmail_imap"],
+    optionalTools: ["linkedin", "slack", "gptzero"],
+    questions: [
+      { key: "senderName", message: "Your name (appears in From field)", type: "text", placeholder: "Jane Doe" },
+      { key: "senderEmail", message: "Email address to send FROM (create a separate one for outreach — never your personal email. Gmail, Outlook, any provider)", type: "text", placeholder: "yourname.outreach@gmail.com" },
+      { key: "targetAudience", message: "Who are you reaching out to?", type: "text", placeholder: "CTOs at Series A startups" },
+      { key: "purpose", message: "What's the goal of your outreach?", type: "text", placeholder: "Introduce QIS Protocol for fleet intelligence" },
+      { key: "tone", message: "Email tone", type: "select", options: [
+        { value: "casual", label: "Casual", hint: "peer-to-peer, like texting a colleague" },
+        { value: "professional", label: "Professional", hint: "respectful but direct" },
+        { value: "technical", label: "Technical", hint: "engineer-to-engineer, show depth" },
+      ]},
+      { key: "dailyLimit", message: "Max emails per day", type: "text", default: "50", placeholder: "50" },
+    ],
+  },
+  {
+    id: "research",
+    name: "Research Claw",
+    description: "Deep web research, competitive analysis, synthesized reports",
+    hint: "market research, due diligence, monitoring",
+    icon: "🔍",
+    requiredTools: ["web_search", "web_fetch"],
+    optionalTools: ["pdf_reader", "notion", "google_docs"],
+    questions: [
+      { key: "researchDomain", message: "What domain are you researching?", type: "text", placeholder: "AI agent frameworks, competitor analysis" },
+      { key: "outputFormat", message: "How do you want results?", type: "select", options: [
+        { value: "markdown", label: "Markdown reports", hint: "saved to files" },
+        { value: "email", label: "Email digest", hint: "daily/weekly summary to your inbox" },
+        { value: "notion", label: "Notion pages", hint: "auto-create in your workspace" },
+      ]},
+      { key: "frequency", message: "How often should it run?", type: "select", options: [
+        { value: "once", label: "One-time deep dive" },
+        { value: "daily", label: "Daily monitoring" },
+        { value: "weekly", label: "Weekly roundup" },
+      ]},
+    ],
+  },
+  {
+    id: "support",
+    name: "Support Claw",
+    description: "Inbox monitoring, auto-triage, draft responses, escalation",
+    hint: "customer support, helpdesk, email management",
+    icon: "🎧",
+    requiredTools: ["gmail_smtp", "gmail_imap"],
+    optionalTools: ["slack", "zendesk", "intercom"],
+    questions: [
+      { key: "supportEmail", message: "Support inbox email", type: "text", placeholder: "support@yourdomain.com" },
+      { key: "escalationEmail", message: "Escalation email (urgent issues)", type: "text", placeholder: "you@yourdomain.com" },
+      { key: "autoReply", message: "Auto-reply to common questions?", type: "confirm" },
+      { key: "categories", message: "What types of requests do you get?", type: "text", placeholder: "billing, technical, feature requests, bugs" },
+    ],
+  },
+  {
+    id: "social",
+    name: "Social Claw",
+    description: "Content creation, scheduling, engagement monitoring",
+    hint: "twitter/X, LinkedIn, content marketing",
+    icon: "📱",
+    requiredTools: ["web_search"],
+    optionalTools: ["twitter_api", "linkedin_api", "buffer"],
+    questions: [
+      { key: "platforms", message: "Which platforms?", type: "text", placeholder: "Twitter/X, LinkedIn" },
+      { key: "contentType", message: "What kind of content?", type: "select", options: [
+        { value: "thought_leadership", label: "Thought leadership", hint: "original insights, opinions" },
+        { value: "engagement", label: "Engagement", hint: "reply to others, build community" },
+        { value: "promotion", label: "Promotion", hint: "share product updates, launches" },
+        { value: "curation", label: "Curation", hint: "share relevant industry content" },
+      ]},
+      { key: "postsPerDay", message: "Target posts per day", type: "text", default: "3", placeholder: "3" },
+    ],
+  },
+  {
+    id: "custom",
+    name: "Custom Claw",
+    description: "Describe what you need — Claude configures it from scratch",
+    hint: "anything else, blank slate",
+    icon: "⚡",
+    requiredTools: [],
+    optionalTools: [],
+    questions: [
+      { key: "description", message: "Describe what you want the agent to do (be specific)", type: "text", placeholder: "Monitor Hacker News for QIS-related posts and draft thoughtful replies..." },
+      { key: "schedule", message: "How often should it run?", type: "select", options: [
+        { value: "continuous", label: "Continuously", hint: "always running" },
+        { value: "hourly", label: "Every hour" },
+        { value: "daily", label: "Once a day" },
+        { value: "weekly", label: "Once a week" },
+        { value: "manual", label: "Only when triggered" },
+      ]},
+      { key: "outputMethod", message: "How should it deliver results?", type: "select", options: [
+        { value: "email", label: "Email" },
+        { value: "file", label: "Save to files" },
+        { value: "slack", label: "Slack message" },
+        { value: "console", label: "Terminal output" },
+      ]},
+    ],
+  },
+];
+
+export type QuestionnaireResult = {
+  template: ClawTemplate;
+  answers: Record<string, string | boolean>;
+  projectName: string;
+};
+
+/**
+ * Run the interactive questionnaire.
+ */
+export async function runQuestionnaire(systemInfo: SystemInfo): Promise<QuestionnaireResult | null> {
+  console.log(sectionHeader("What do you want to build?"));
+  console.log("");
+
+  // Step 1: Choose template
+  const templateId = await clack.select({
+    message: "Select an agent type",
+    options: CLAW_TEMPLATES.map((t) => ({
+      value: t.id,
+      label: `${t.icon}  ${t.name}`,
+      hint: t.hint,
+    })),
+  });
+
+  if (clack.isCancel(templateId)) return null;
+
+  const template = CLAW_TEMPLATES.find((t) => t.id === templateId)!;
+
+  console.log("");
+  console.log(
+    muted(`  ${template.icon}  ${template.name}: ${template.description}`)
+  );
+  console.log("");
+
+  // Step 2: Project name
+  const projectName = await clack.text({
+    message: "Project name",
+    placeholder: `my-${template.id}-agent`,
+    defaultValue: `my-${template.id}-agent`,
+  });
+
+  if (clack.isCancel(projectName)) return null;
+
+  // Step 3: Template-specific questions
+  const answers: Record<string, string | boolean> = {};
+
+  for (const q of template.questions) {
+    let answer: string | boolean | symbol;
+
+    if (q.type === "text") {
+      answer = await clack.text({
+        message: q.message,
+        placeholder: q.placeholder,
+        defaultValue: q.default,
+      });
+    } else if (q.type === "select" && q.options) {
+      answer = await clack.select({
+        message: q.message,
+        options: q.options,
+      });
+    } else if (q.type === "confirm") {
+      answer = await clack.confirm({ message: q.message });
+    } else {
+      continue;
+    }
+
+    if (clack.isCancel(answer)) return null;
+    answers[q.key] = answer as string | boolean;
+  }
+
+  // Step 4: Universal deep-dive (every Claw gets these)
+  console.log("");
+  console.log(muted("  Now let's go deeper so the board can build your perfect agent."));
+  console.log("");
+
+  const taskDescription = await clack.text({
+    message: "Describe in detail what you want this agent to do day-to-day",
+    placeholder: "Find potential partners, research them, send personalized emails, follow up, track responses...",
+  });
+  if (clack.isCancel(taskDescription)) return null;
+  answers.taskDescription = taskDescription as string;
+
+  const toolsUsed = await clack.text({
+    message: "What tools/platforms do you currently use? (email, CRM, Slack, etc.)",
+    placeholder: "Gmail, Slack, HubSpot, LinkedIn, Google Sheets...",
+  });
+  if (clack.isCancel(toolsUsed)) return null;
+  answers.toolsUsed = toolsUsed as string;
+
+  const autonomyLevel = await clack.select({
+    message: "How autonomous should the agent be?",
+    options: [
+      { value: "supervised", label: "Suggest & wait for approval", hint: "safest — you review everything" },
+      { value: "semi", label: "Act on routine tasks, ask on important ones", hint: "recommended" },
+      { value: "full", label: "Fully autonomous", hint: "agent handles everything, alerts on issues only" },
+    ],
+  });
+  if (clack.isCancel(autonomyLevel)) return null;
+  answers.autonomyLevel = autonomyLevel as string;
+
+  const volume = await clack.text({
+    message: "Expected daily volume? (emails, tasks, posts, etc.)",
+    placeholder: "20-50 emails per day",
+  });
+  if (clack.isCancel(volume)) return null;
+  answers.volume = volume as string;
+
+  const specialInstructions = await clack.text({
+    message: "Anything else the agent should know? (special rules, tone, avoid certain things, etc.)",
+    placeholder: "Never contact competitors. Always be casual. Include a link to our site...",
+    defaultValue: "",
+  });
+  if (clack.isCancel(specialInstructions)) return null;
+  if (specialInstructions) answers.specialInstructions = specialInstructions as string;
+
+  // Step 5: Shortcut preferences
+  const addDesktopShortcut = await clack.confirm({
+    message: "Add a shortcut to your Desktop?",
+    initialValue: true,
+  });
+  if (clack.isCancel(addDesktopShortcut)) return null;
+  answers.addDesktopShortcut = addDesktopShortcut as boolean;
+
+  // Step 6: Self-update interval
+  const updateInterval = await clack.select({
+    message: "How often should the agent self-optimize?",
+    options: [
+      { value: "1", label: "Every hour", hint: "aggressive learning" },
+      { value: "6", label: "Every 6 hours", hint: "recommended" },
+      { value: "24", label: "Once a day", hint: "conservative" },
+      { value: "168", label: "Once a week", hint: "minimal" },
+    ],
+  });
+  if (clack.isCancel(updateInterval)) return null;
+  answers.selfUpdateIntervalHours = updateInterval as string;
+
+  return {
+    template,
+    answers,
+    projectName: projectName as string,
+  };
+}

package/installer/research.ts

@@ -0,0 +1,258 @@
+/**
+ * MetaClaw Research Phase — Claude-powered best practices research
+ *
+ * Uses the Agent SDK to:
+ * 1. Research best practices for the user's specific agent type
+ * 2. Generate optimal configuration
+ * 3. Validate the configuration
+ *
+ * Auth: reads ~/.claude/.credentials.json (from Claude login)
+ * No CLI needs to be open — the SDK uses the stored OAuth token.
+ */
+
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKResultMessage, SDKResultSuccess, SDKAssistantMessage, Options } from "@anthropic-ai/claude-agent-sdk";
+import ora from "ora";
+import { brand, muted, success, sectionHeader, status } from "./brand.js";
+import type { SystemInfo } from "./detect.js";
+import type { QuestionnaireResult } from "./questionnaire.js";
+
+export type ClawConfig = {
+  name: string;
+  template: string;
+  systemPrompt: string;
+  tools: string[];
+  safety: Record<string, unknown>;
+  schedule: { cron: string; description: string };
+  selfImprovement: {
+    enabled: boolean;
+    reflectionFrequency: string;
+    metricsToTrack: string[];
+  };
+  rawResearch: string;
+};
+
+/**
+ * Build the meta-prompt that instructs Claude to research and configure.
+ */
+function buildMetaPrompt(result: QuestionnaireResult, systemInfo: SystemInfo): string {
+  const { template, answers } = result;
+
+  return `You are MetaClaw, an autonomous AI agent configuration engine by Yonder Zenith LLC.
+
+## YOUR MISSION
+Research and generate the OPTIMAL agent configuration for this user's needs. Be opinionated — choose the best approach, don't offer multiple options.
+
+## SYSTEM CONTEXT
+- OS: ${systemInfo.os.platform} ${systemInfo.os.release} (${systemInfo.os.arch})
+- Hardware: ${systemInfo.hardware.cpus} CPUs, ${systemInfo.hardware.ram} RAM, GPU: ${systemInfo.hardware.gpu}
+- User: ${systemInfo.user.username}
+- Workspace: ${systemInfo.paths.workspace}
+- Available: Node.js ${systemInfo.node.version}${systemInfo.docker.installed ? ", Docker " + systemInfo.docker.version : ""}${systemInfo.python.installed ? ", Python " + systemInfo.python.version : ""}
+
+## AGENT REQUEST
+- Template: ${template.name} (${template.id})
+- Description: ${template.description}
+- Project: ${result.projectName}
+
+## USER'S DETAILED REQUIREMENTS
+- Day-to-day tasks: ${answers.taskDescription || "Not specified"}
+- Tools/platforms they use: ${answers.toolsUsed || "Not specified"}
+- Autonomy level: ${answers.autonomyLevel || "semi"}
+- Expected daily volume: ${answers.volume || "Not specified"}
+- Special instructions: ${answers.specialInstructions || "None"}
+
+## TEMPLATE-SPECIFIC CONFIG
+${Object.entries(answers).filter(([k]) => !["taskDescription", "toolsUsed", "autonomyLevel", "volume", "specialInstructions", "selfUpdateIntervalHours"].includes(k)).map(([k, v]) => `- ${k}: ${v}`).join("\n")}
+
+## PROTOCOL (follow this exactly)
+
+### STEP 1: RESEARCH (use WebSearch)
+Search for and synthesize:
+- What are the absolute best practices for a ${template.name} in 2026?
+- What tools/MCP servers are proven for this use case?
+- What are common failure modes and how to prevent them?
+- What compliance/safety requirements exist?
+- What makes world-class agents of this type vs mediocre ones?
+Do at least 3 web searches. Be thorough.
+
+### STEP 2: DESIGN
+Based on research, design the agent:
+- System prompt (comprehensive, with anti-AI-detection rules if sending emails)
+- Tool list (specific MCP servers and built-in tools)
+- Safety rules (rate limits, circuit breakers, compliance)
+- Self-improvement strategy
+- Schedule
+
+### STEP 3: OUTPUT
+Output a JSON block with this exact structure:
+\`\`\`json
+{
+  "name": "${result.projectName}",
+  "template": "${template.id}",
+  "systemPrompt": "the full system prompt",
+  "tools": ["tool1", "tool2"],
+  "safety": {
+    "maxActionsPerDay": 50,
+    "maxActionsPerHour": 10,
+    "circuitBreakerThreshold": 0.05
+  },
+  "schedule": {
+    "cron": "*/30 * * * *",
+    "description": "every 30 minutes"
+  },
+  "selfImprovement": {
+    "enabled": true,
+    "reflectionFrequency": "daily",
+    "metricsToTrack": ["success_rate", "response_quality"]
+  }
+}
+\`\`\`
+
+### STEP 4: VALIDATE
+Before outputting, check:
+- Is every field populated? (no empty strings or missing keys)
+- Is the system prompt specific to this use case? (not generic)
+- Are safety limits reasonable? (not too loose, not too restrictive)
+- Will this actually work on ${systemInfo.os.platform} with the available tools?
+If anything scores below 8/10, revise it.`;
+}
+
+/**
+ * Run the AI research phase — calls Claude Agent SDK to research and configure.
+ */
+export async function runResearch(
+  result: QuestionnaireResult,
+  systemInfo: SystemInfo
+): Promise<ClawConfig | null> {
+  console.log(sectionHeader("MetaClaw Board Convening"));
+  console.log("");
+  console.log(brand("  Board members are researching for your ultimate custom setup."));
+  console.log(muted("  Analyzing your requirements, researching best practices,"));
+  console.log(muted("  and designing the optimal configuration for " + result.template.name + "..."));
+  console.log("");
+
+  const spinner = ora({
+    text: "Board convening — analyzing requirements...",
+    color: "magenta",
+    spinner: "dots12",
+  }).start();
+
+  const metaPrompt = buildMetaPrompt(result, systemInfo);
+
+  try {
+    let fullResponse = "";
+    let currentPhase = "Researching...";
+
+    const options: Options = {
+      systemPrompt: "You are MetaClaw, an expert AI agent configuration engine. You research best practices using web search, then generate optimal agent configurations. Always output valid JSON in your final response.",
+      allowedTools: ["WebSearch", "WebFetch"],
+      maxTurns: 20,
+      model: "claude-sonnet-4-6",
+    };
+
+    const stream = query({ prompt: metaPrompt, options });
+
+    for await (const message of stream) {
+      if (message.type === "assistant") {
+        const msg = message as SDKAssistantMessage;
+        if (msg.message?.content) {
+          for (const block of msg.message.content) {
+            if (block.type === "text" && "text" in block) {
+              const text = (block as { type: "text"; text: string }).text;
+              fullResponse += text;
+
+              // Update spinner with board-style messaging
+              if (text.includes("search") || text.includes("Search")) {
+                spinner.text = "Board researching industry best practices...";
+              } else if (text.includes("design") || text.includes("Design")) {
+                spinner.text = "Board designing your agent architecture...";
+              } else if (text.includes("json") || text.includes("JSON")) {
+                spinner.text = "Board generating your custom configuration...";
+              } else if (text.includes("validat") || text.includes("Validat")) {
+                spinner.text = "Board reviewing and stress-testing...";
+              }
+            }
+          }
+        }
+      }
+
+      if (message.type === "result") {
+        const res = message as SDKResultMessage;
+        if (res.subtype === "success") {
+          const s = res as SDKResultSuccess;
+          spinner.succeed(`Board consensus reached — configuration finalized ($${s.total_cost_usd.toFixed(2)})`);
+        } else {
+          spinner.fail("Research failed: " + res.subtype);
+          return null;
+        }
+      }
+    }
+
+    // Extract JSON from response
+    const config = extractConfig(fullResponse, result);
+    if (config) {
+      console.log("");
+      console.log(status.ok("Agent configuration generated"));
+      console.log(status.ok(`System prompt: ${config.systemPrompt.length} characters`));
+      console.log(status.ok(`Tools: ${config.tools.join(", ")}`));
+      console.log(status.ok(`Schedule: ${config.schedule.description}`));
+      console.log(status.ok(`Self-improvement: ${config.selfImprovement.enabled ? "enabled" : "disabled"}`));
+    }
+
+    return config;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    spinner.fail(`Research failed: ${msg}`);
+    return null;
+  }
+}
+
+/**
+ * Extract JSON config from Claude's response.
+ */
+function extractConfig(response: string, result: QuestionnaireResult): ClawConfig | null {
+  // Try to find JSON block in response
+  const jsonMatch = response.match(/```json\s*([\s\S]*?)```/);
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1]);
+      return {
+        ...parsed,
+        rawResearch: response,
+      };
+    } catch {
+      // JSON parse failed
+    }
+  }
+
+  // Try to find raw JSON object
+  const braceMatch = response.match(/\{[\s\S]*"name"[\s\S]*"systemPrompt"[\s\S]*\}/);
+  if (braceMatch) {
+    try {
+      const parsed = JSON.parse(braceMatch[0]);
+      return {
+        ...parsed,
+        rawResearch: response,
+      };
+    } catch {
+      // JSON parse failed
+    }
+  }
+
+  // Fallback — return minimal config
+  return {
+    name: result.projectName,
+    template: result.template.id,
+    systemPrompt: `You are a ${result.template.name}. ${result.template.description}`,
+    tools: result.template.requiredTools,
+    safety: { maxActionsPerDay: 50, maxActionsPerHour: 10 },
+    schedule: { cron: "*/30 * * * *", description: "every 30 minutes" },
+    selfImprovement: {
+      enabled: true,
+      reflectionFrequency: "daily",
+      metricsToTrack: ["success_rate"],
+    },
+    rawResearch: response,
+  };
+}