@spilno/herald-mcp 1.1.3 → 1.3.0

package/README.md

@@ -2,62 +2,121 @@
 
 Herald MCP - AI-native interface to [CEDA](https://getceda.com) (Cognitive Event-Driven Architecture).
 
-## Installation
+**Dual-mode**: Natural chat for humans, MCP for AI agents.
 
-```bash
-# Run directly (no install)
-npx @spilno/herald-mcp
+## Quick Start
 
-# Or install globally
+```bash
 npm install -g @spilno/herald-mcp
-herald-mcp
+
+export HERALD_API_URL=https://getceda.com
+
+herald-mcp chat
+```
+
+That's it. Chat mode works out of the box.
+
+## Chat Mode (Natural Conversation)
+
+```bash
+herald-mcp chat
+```
+
+```
+You: I need a safety assessment module for construction sites
+Herald: I've designed a Safety Assessment module with 4 sections...
+
+You: Add OSHA compliance fields
+Herald: Done. Added compliance checklist to Risk Evaluation...
+
+You: Looks good, let's use it
+Herald: Great! Module accepted and saved.
 ```
 
-## Configuration
+## Command Mode (Structured)
+
+```bash
+herald-mcp predict "create safety assessment"
+herald-mcp refine "add OSHA compliance"
+herald-mcp resume
+herald-mcp observe yes
+herald-mcp new
+herald-mcp health
+herald-mcp stats
+```
 
-Set environment variables:
+## Session Persistence
+
+Sessions saved to `~/.herald/session` - resume anytime:
+
+```bash
+# Start today
+herald-mcp predict "create incident report module"
+
+# Continue tomorrow
+herald-mcp resume
+herald-mcp refine "add witness statements section"
+```
+
+## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `HERALD_API_URL` | Yes | CEDA server URL (e.g., `https://getceda.com`) |
-| `HERALD_API_TOKEN` | No | Bearer token for authentication |
-| `HERALD_API_USER` | No | Basic auth username (alternative to token) |
-| `HERALD_API_PASS` | No | Basic auth password (alternative to token) |
+| `HERALD_API_URL` | Yes | CEDA server URL |
+| `HERALD_API_TOKEN` | No | Bearer token for auth |
+| `HERALD_COMPANY` | No | Multi-tenant company context |
+| `HERALD_PROJECT` | No | Multi-tenant project context |
+| `HERALD_VAULT` | No | Offspring vault ID (spilno, goprint, disrupt) |
+| `HERALD_OFFSPRING_CLOUD` | No | Set to "true" for cloud mode |
+| `AEGIS_OFFSPRING_PATH` | No | Local path to offspring status files |
 
-## Tools
+## Herald Context Sync (v1.3.0+)
 
-Herald exposes 6 MCP tools:
+Herald instances can communicate across contexts, sharing insights and synchronizing status:
 
-| Tool | Description |
-|------|-------------|
-| `herald_health` | Check CEDA system status |
-| `herald_stats` | Get server statistics and loaded patterns |
-| `herald_predict` | Generate prediction from natural language input |
-| `herald_refine` | Refine existing prediction with additional requirements |
-| `herald_session` | Get session history and state |
-| `herald_observe` | Record prediction feedback for learning |
+### Tools
 
-## Usage with Claude Code
+| Tool | Purpose |
+|------|---------|
+| `herald_context_status` | Read status from Herald contexts across domains |
+| `herald_share_insight` | Share a pattern insight with another context |
+| `herald_query_insights` | Query accumulated insights on a topic |
 
-Add to `~/.claude.json`:
+### Local Mode (Default)
 
-```json
-{
-  "mcpServers": {
-    "herald": {
-      "command": "npx",
-      "args": ["@spilno/herald-mcp"],
-      "env": {
-        "HERALD_API_URL": "https://getceda.com"
-      }
-    }
-  }
-}
+```bash
+# Context files in local directory
+export AEGIS_OFFSPRING_PATH=~/Documents/aegis_ceda/_offspring
+export HERALD_VAULT=spilno  # Which context this Herald serves
+
+herald-mcp  # MCP mode uses local files
+```
+
+### Cloud Mode
+
+```bash
+# Use CEDA API for context synchronization
+export HERALD_API_URL=https://getceda.com
+export HERALD_OFFSPRING_CLOUD=true
+export HERALD_VAULT=spilno
+
+herald-mcp  # MCP mode calls CEDA API
+```
+
+### Herald-to-Herald Protocol
+
+```
+POST /api/herald/heartbeat    # Herald reports its context status
+GET  /api/herald/contexts     # Herald discovers sibling contexts
+POST /api/herald/insight      # Herald shares an insight
+GET  /api/herald/insights     # Herald queries shared insights
 ```
 
-## Usage with Claude Desktop
+## MCP Mode (for AI Agents)
 
-Add to `claude_desktop_config.json`:
+When piped, Herald speaks JSON-RPC for Claude, Devin, and other AI agents.
+
+### Claude Code (~/.claude.json)
 
 ```json
 {
@@ -73,34 +132,17 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-## Usage with Devin
+### Devin MCP Marketplace
 
-In Devin MCP marketplace:
 - **Server Name**: Herald-CEDA
-- **Transport**: STDIO
-- **Command**: `npx`
-- **Arguments**: `@spilno/herald-mcp`
+- **Command**: `npx @spilno/herald-mcp`
 - **Environment**: `HERALD_API_URL=https://getceda.com`
 
-## Multi-turn Conversations
-
-Herald supports session-based conversations for iterative refinement:
+## Architecture
 
 ```
-1. herald_predict("create assessment module")
-   → Returns sessionId + initial prediction
-
-2. herald_refine(sessionId, "add OSHA compliance fields")
-   → Returns refined prediction
-
-3. herald_refine(sessionId, "include corrective actions workflow")
-   → Returns further refined prediction
-
-4. herald_session(sessionId)
-   → Returns full history of all turns
-
-5. herald_observe(sessionId, accepted=true)
-   → Records feedback for learning
+Human ←→ Herald (Claude voice) ←→ CEDA (cognition)
+Agent ←→ Herald (JSON-RPC)     ←→ CEDA
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 /**
- * Herald MCP - Diplomatic interface to CEDA ecosystem
+ * Herald MCP - AI-native interface to CEDA ecosystem
  *
- * Herald speaks CEDA. Cognition stays sovereign.
+ * Dual-mode:
+ * - CLI mode (TTY): Natural commands for humans
+ * - MCP mode (piped): JSON-RPC for AI agents
  */
 export {};

package/dist/index.js

@@ -1,18 +1,219 @@
 #!/usr/bin/env node
 /**
- * Herald MCP - Diplomatic interface to CEDA ecosystem
+ * Herald MCP - AI-native interface to CEDA ecosystem
  *
- * Herald speaks CEDA. Cognition stays sovereign.
+ * Dual-mode:
+ * - CLI mode (TTY): Natural commands for humans
+ * - MCP mode (piped): JSON-RPC for AI agents
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 // Configuration - all sensitive values from environment only
 const CEDA_API_URL = process.env.HERALD_API_URL;
-const CEDA_API_TOKEN = process.env.HERALD_API_TOKEN; // Bearer token (optional for demo)
-const CEDA_API_USER = process.env.HERALD_API_USER; // Basic auth user (optional)
-const CEDA_API_PASS = process.env.HERALD_API_PASS; // Basic auth pass (optional)
-const DEFAULT_CONTEXT_ID = process.env.HERALD_CONTEXT_ID || "ctx_default";
+const CEDA_API_TOKEN = process.env.HERALD_API_TOKEN;
+const CEDA_API_USER = process.env.HERALD_API_USER;
+const CEDA_API_PASS = process.env.HERALD_API_PASS;
+// Multi-tenant context
+const HERALD_COMPANY = process.env.HERALD_COMPANY || "default";
+const HERALD_PROJECT = process.env.HERALD_PROJECT || "default";
+const HERALD_USER = process.env.HERALD_USER || "default";
+// Offspring vault context (for Avatar mode)
+const HERALD_VAULT = process.env.HERALD_VAULT || ""; // e.g., "spilno", "goprint", "disrupt"
+const AEGIS_OFFSPRING_PATH = process.env.AEGIS_OFFSPRING_PATH || join(homedir(), "Documents", "aegis_ceda", "_offspring");
+// Cloud mode: Use CEDA API for offspring communication instead of local files
+const OFFSPRING_CLOUD_MODE = process.env.HERALD_OFFSPRING_CLOUD === "true";
+const VERSION = "1.3.0";
+// Claude for Herald's voice - bundled key with limits, users can override
+const HERALD_VOICE_KEY = "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";
+const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || HERALD_VOICE_KEY;
+// Session persistence - context-isolated paths
+// ~/.herald/{company}/{project}/{user}/session
+function getHeraldDir() {
+    return join(homedir(), ".herald", HERALD_COMPANY, HERALD_PROJECT, HERALD_USER);
+}
+function getSessionFile() {
+    return join(getHeraldDir(), "session");
+}
+function ensureHeraldDir() {
+    const dir = getHeraldDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function saveSession(sessionId) {
+    ensureHeraldDir();
+    writeFileSync(getSessionFile(), sessionId, "utf-8");
+}
+function loadSession() {
+    const sessionFile = getSessionFile();
+    if (existsSync(sessionFile)) {
+        return readFileSync(sessionFile, "utf-8").trim();
+    }
+    return null;
+}
+function clearSession() {
+    const sessionFile = getSessionFile();
+    if (existsSync(sessionFile)) {
+        unlinkSync(sessionFile);
+    }
+}
+// Context info for display
+function getContextString() {
+    return `${HERALD_COMPANY}:${HERALD_PROJECT}:${HERALD_USER}`;
+}
+const HERALD_SYSTEM_PROMPT = `You are Herald, the voice of CEDA (Cognitive Event-Driven Architecture).
+You help humans design module structures through natural conversation.
+
+You have access to CEDA's cognitive capabilities:
+- Predict: Generate structure predictions from requirements
+- Refine: Improve predictions with additional requirements
+- Session: Track conversation history
+
+When users describe what they want, you:
+1. Call CEDA to generate/refine predictions
+2. Explain the results in natural language
+3. Ask clarifying questions when needed
+
+Keep responses concise and focused. You're a helpful assistant, not verbose.
+When showing module structures, summarize the key sections and fields.`;
+async function callClaude(systemPrompt, messages) {
+    // Convert to Anthropic format (separate system from messages)
+    const anthropicMessages = messages
+        .filter(m => m.role !== "system")
+        .map(m => ({ role: m.role, content: m.content }));
+    // Combine all system messages
+    const systemContent = messages
+        .filter(m => m.role === "system")
+        .map(m => m.content)
+        .join("\n\n");
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": ANTHROPIC_API_KEY,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model: "claude-sonnet-4-20250514",
+            max_tokens: 1000,
+            system: systemPrompt + (systemContent ? "\n\n" + systemContent : ""),
+            messages: anthropicMessages.length > 0 ? anthropicMessages : [{ role: "user", content: "Hello" }],
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        return `Claude error: ${error}`;
+    }
+    const data = await response.json();
+    return data.content[0]?.text || "No response from Claude";
+}
+async function translateAndExecute(userInput, conversationHistory) {
+    const sessionId = loadSession();
+    // First, ask Claude to interpret the user's intent
+    const interpretSystemPrompt = `You interpret user requests for CEDA.
+Respond with JSON only: {"action": "predict"|"refine"|"info"|"accept"|"reject", "input": "the user's requirement"}
+- predict: User wants to create something new
+- refine: User wants to modify/add to current design (requires active session)
+- info: User is asking a question
+- accept: User approves the current design
+- reject: User rejects/wants to start over
+
+Current session: ${sessionId || "none"}`;
+    const interpretation = await callClaude(interpretSystemPrompt, [
+        { role: "user", content: userInput }
+    ]);
+    let cedaResult = null;
+    let action = "info";
+    try {
+        const parsed = JSON.parse(interpretation);
+        action = parsed.action;
+        const input = parsed.input;
+        if (action === "predict") {
+            cedaResult = await callCedaAPI("/api/predict", "POST", {
+                input,
+                config: { enableAutoFix: true, maxAutoFixAttempts: 3 },
+            });
+            if (cedaResult.sessionId) {
+                saveSession(cedaResult.sessionId);
+            }
+        }
+        else if (action === "refine" && sessionId) {
+            cedaResult = await callCedaAPI("/api/refine", "POST", {
+                sessionId,
+                refinement: input,
+            });
+        }
+        else if (action === "accept" && sessionId) {
+            cedaResult = await callCedaAPI("/api/feedback", "POST", {
+                sessionId,
+                accepted: true,
+            });
+            clearSession();
+        }
+        else if (action === "reject") {
+            clearSession();
+            cedaResult = { success: true, status: "Session cleared" };
+        }
+    }
+    catch {
+        // Claude didn't return valid JSON, treat as info request
+    }
+    // Build response context
+    let responseContext = "";
+    if (cedaResult) {
+        responseContext = `\n\nCEDA ${action} result:\n${JSON.stringify(cedaResult, null, 2)}\n\nSummarize this naturally for the user.`;
+    }
+    // Ask Claude to formulate a natural response
+    const responseMessages = [
+        ...conversationHistory,
+        { role: "user", content: userInput },
+    ];
+    return await callClaude(HERALD_SYSTEM_PROMPT + responseContext, responseMessages);
+}
+import * as readline from "readline";
+async function runChatMode() {
+    // Key is bundled - chat works out of the box
+    const contextStr = getContextString();
+    console.log(`
+Herald v${VERSION} - Chat Mode
+Context: ${contextStr}
+Type your requirements in natural language. Type 'exit' to quit.
+──────────────────────────────────────────────────────────────
+`);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const conversationHistory = [];
+    const currentSession = loadSession();
+    if (currentSession) {
+        console.log(`Resuming session: ${currentSession}\n`);
+    }
+    const prompt = () => {
+        rl.question("You: ", async (input) => {
+            const trimmed = input.trim();
+            if (trimmed.toLowerCase() === "exit" || trimmed.toLowerCase() === "quit") {
+                console.log("\nGoodbye!");
+                rl.close();
+                return;
+            }
+            if (!trimmed) {
+                prompt();
+                return;
+            }
+            conversationHistory.push({ role: "user", content: trimmed });
+            const response = await translateAndExecute(trimmed, conversationHistory);
+            conversationHistory.push({ role: "assistant", content: response });
+            console.log(`\nHerald: ${response}\n`);
+            prompt();
+        });
+    };
+    prompt();
+}
 // Auth strategy: prefer Bearer token, fallback to Basic auth, allow none for demo
 function getAuthHeader() {
     if (CEDA_API_TOKEN) {
@@ -22,30 +223,43 @@ function getAuthHeader() {
         const basicAuth = Buffer.from(`${CEDA_API_USER}:${CEDA_API_PASS}`).toString("base64");
         return `Basic ${basicAuth}`;
     }
-    return null; // No auth - acceptable for local demo
+    return null;
 }
 async function callCedaAPI(endpoint, method = "GET", body) {
-    // Validate configuration
     if (!CEDA_API_URL) {
         return {
             success: false,
-            error: "HERALD_API_URL not configured. Set environment variable."
+            error: "HERALD_API_URL not configured. Run: export HERALD_API_URL=https://getceda.com"
         };
     }
-    const url = `${CEDA_API_URL}${endpoint}`;
+    // Add context params to URL for GET requests (except /health)
+    let url = `${CEDA_API_URL}${endpoint}`;
+    if (method === "GET" && endpoint.startsWith("/api/")) {
+        const separator = endpoint.includes("?") ? "&" : "?";
+        url += `${separator}company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}`;
+    }
     const headers = {
         "Content-Type": "application/json",
     };
-    // Add auth header if configured (optional for demo)
     const authHeader = getAuthHeader();
     if (authHeader) {
         headers["Authorization"] = authHeader;
     }
+    // Add context to POST body
+    let enrichedBody = body;
+    if (method === "POST" && body && typeof body === "object") {
+        enrichedBody = {
+            ...body,
+            company: HERALD_COMPANY,
+            project: HERALD_PROJECT,
+            user: HERALD_USER,
+        };
+    }
     try {
         const response = await fetch(url, {
             method,
             headers,
-            body: body ? JSON.stringify(body) : undefined,
+            body: enrichedBody ? JSON.stringify(enrichedBody) : undefined,
         });
         if (!response.ok) {
             return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
@@ -56,32 +270,181 @@ async function callCedaAPI(endpoint, method = "GET", body) {
         return { success: false, error: `Connection failed: ${error}` };
     }
 }
-// Create MCP server
-const server = new Server({
-    name: "herald",
-    version: "1.0.0",
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-// Tool definitions - aligned with actual CEDA server endpoints
+// ============================================
+// CLI MODE - Human-friendly commands
+// ============================================
+function printUsage() {
+    const currentSession = loadSession();
+    const contextStr = getContextString();
+    const sessionDir = getHeraldDir();
+    console.log(`
+Herald MCP v${VERSION} - AI-native interface to CEDA
+
+Context: ${contextStr}
+Session: ${currentSession || "(none)"}
+Path:    ${sessionDir}
+
+Usage:
+  herald-mcp <command> [options]
+
+Commands:
+  chat                      Natural conversation mode (Claude voice)
+  predict "<signal>"        Start new prediction (saves session)
+  refine "<text>"           Refine current session
+  resume                    Show current session state
+  observe yes|no            Record feedback & close session
+  new                       Clear session, start fresh
+  health                    Check CEDA system status
+  stats                     Get server statistics
+
+Examples:
+  herald-mcp chat                                  # Natural conversation
+  herald-mcp predict "create safety assessment"   # Command mode
+  herald-mcp refine "add OSHA compliance"
+  herald-mcp observe yes
+
+Environment:
+  HERALD_API_URL      CEDA server URL (required)
+  HERALD_COMPANY      Company context (default: default)
+  HERALD_PROJECT      Project context (default: default)
+  HERALD_USER         User context (default: default)
+  ANTHROPIC_API_KEY   Claude key override (optional, bundled key available)
+  HERALD_API_TOKEN    Bearer token (optional)
+
+MCP Mode:
+  When piped, Herald speaks JSON-RPC for AI agents.
+`);
+}
+function formatOutput(data) {
+    if (data.error) {
+        console.error(`Error: ${data.error}`);
+        process.exit(1);
+    }
+    // Pretty print with session ID highlighted if present
+    if (data.sessionId) {
+        console.log(`\nSession: ${data.sessionId}\n`);
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
+async function runCLI(args) {
+    const command = args[0]?.toLowerCase();
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printUsage();
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(`herald-mcp v${VERSION}`);
+        return;
+    }
+    switch (command) {
+        case "chat": {
+            await runChatMode();
+            break;
+        }
+        case "health": {
+            const result = await callCedaAPI("/health");
+            formatOutput(result);
+            break;
+        }
+        case "stats": {
+            const result = await callCedaAPI("/api/stats");
+            formatOutput(result);
+            break;
+        }
+        case "predict": {
+            const signal = args[1];
+            if (!signal) {
+                console.error("Error: Missing signal. Usage: herald-mcp predict \"<signal>\"");
+                process.exit(1);
+            }
+            const result = await callCedaAPI("/api/predict", "POST", {
+                input: signal,
+                config: { enableAutoFix: true, maxAutoFixAttempts: 3 },
+            });
+            // Save session for future commands
+            if (result.sessionId) {
+                saveSession(result.sessionId);
+                console.log(`\n✓ Session saved: ${result.sessionId}\n`);
+            }
+            formatOutput(result);
+            break;
+        }
+        case "refine": {
+            const refinement = args[1];
+            if (!refinement) {
+                console.error("Error: Missing refinement. Usage: herald-mcp refine \"<refinement>\"");
+                process.exit(1);
+            }
+            const sessionId = loadSession();
+            if (!sessionId) {
+                console.error("Error: No active session. Run 'herald-mcp predict \"...\"' first.");
+                process.exit(1);
+            }
+            const result = await callCedaAPI("/api/refine", "POST", {
+                sessionId,
+                refinement,
+            });
+            formatOutput(result);
+            break;
+        }
+        case "resume":
+        case "session": {
+            const sessionId = args[1] || loadSession();
+            if (!sessionId) {
+                console.error("Error: No active session. Run 'herald-mcp predict \"...\"' first.");
+                process.exit(1);
+            }
+            const result = await callCedaAPI(`/api/session/${sessionId}`);
+            formatOutput(result);
+            break;
+        }
+        case "observe": {
+            const accepted = args[1]?.toLowerCase();
+            if (!accepted) {
+                console.error("Error: Missing feedback. Usage: herald-mcp observe yes|no");
+                process.exit(1);
+            }
+            const sessionId = loadSession();
+            if (!sessionId) {
+                console.error("Error: No active session. Run 'herald-mcp predict \"...\"' first.");
+                process.exit(1);
+            }
+            const result = await callCedaAPI("/api/feedback", "POST", {
+                sessionId,
+                accepted: accepted === "yes" || accepted === "true" || accepted === "accept",
+                comment: args[2],
+            });
+            // Clear session after feedback
+            clearSession();
+            console.log("\n✓ Session closed.\n");
+            formatOutput(result);
+            break;
+        }
+        case "new": {
+            clearSession();
+            console.log("✓ Session cleared. Ready for new prediction.");
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            printUsage();
+            process.exit(1);
+    }
+}
+// ============================================
+// MCP MODE - JSON-RPC for AI agents
+// ============================================
+const server = new Server({ name: "herald", version: VERSION }, { capabilities: { tools: {} } });
 const tools = [
     {
         name: "herald_health",
         description: "Check Herald and CEDA system status",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "herald_stats",
         description: "Get CEDA server statistics and loaded patterns info",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "herald_predict",
@@ -89,62 +452,35 @@ const tools = [
         inputSchema: {
             type: "object",
             properties: {
-                signal: {
-                    type: "string",
-                    description: "Natural language input (e.g., 'create safety assessment module')",
-                },
-                context: {
-                    type: "string",
-                    description: "Additional context for better prediction",
-                },
-                session_id: {
-                    type: "string",
-                    description: "Session ID for multi-turn conversations (returned from previous predict/refine)",
-                },
-                participant: {
-                    type: "string",
-                    description: "Participant name (e.g., 'user', 'architect', 'compliance')",
-                },
+                signal: { type: "string", description: "Natural language input" },
+                context: { type: "string", description: "Additional context" },
+                session_id: { type: "string", description: "Session ID for multi-turn" },
+                participant: { type: "string", description: "Participant name" },
             },
             required: ["signal"],
         },
     },
     {
         name: "herald_refine",
-        description: "Refine an existing prediction with additional requirements. Use session_id from previous predict call.",
+        description: "Refine an existing prediction with additional requirements.",
         inputSchema: {
             type: "object",
             properties: {
-                session_id: {
-                    type: "string",
-                    description: "Session ID from previous predict or refine call",
-                },
-                refinement: {
-                    type: "string",
-                    description: "Refinement instruction (e.g., 'make it OSHA compliant', 'add corrective actions section')",
-                },
-                context: {
-                    type: "string",
-                    description: "Additional context for refinement",
-                },
-                participant: {
-                    type: "string",
-                    description: "Participant name (e.g., 'user', 'architect', 'compliance')",
-                },
+                session_id: { type: "string", description: "Session ID from previous call" },
+                refinement: { type: "string", description: "Refinement instruction" },
+                context: { type: "string", description: "Additional context" },
+                participant: { type: "string", description: "Participant name" },
             },
             required: ["session_id", "refinement"],
         },
     },
     {
         name: "herald_session",
-        description: "Get session information including history of all predictions and refinements",
+        description: "Get session information including history",
         inputSchema: {
             type: "object",
             properties: {
-                session_id: {
-                    type: "string",
-                    description: "Session ID to retrieve",
-                },
+                session_id: { type: "string", description: "Session ID to retrieve" },
             },
             required: ["session_id"],
         },
@@ -155,149 +491,290 @@ const tools = [
         inputSchema: {
             type: "object",
             properties: {
-                session_id: {
-                    type: "string",
-                    description: "Session ID from prediction",
-                },
-                accepted: {
-                    type: "boolean",
-                    description: "Was prediction accepted by user?",
-                },
-                feedback: {
-                    type: "string",
-                    description: "Optional user feedback/comment",
-                },
+                session_id: { type: "string", description: "Session ID" },
+                accepted: { type: "boolean", description: "Was prediction accepted?" },
+                feedback: { type: "string", description: "Optional feedback" },
             },
             required: ["session_id", "accepted"],
         },
     },
+    // === HERALD CONTEXT SYNC TOOLS ===
+    {
+        name: "herald_context_status",
+        description: "Get status from Herald contexts across domains. Returns session counts, active threads, blockers, and pending items for each context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                context: { type: "string", description: "Optional: specific context to query. Omit for all known contexts." },
+            },
+        },
+    },
+    {
+        name: "herald_share_insight",
+        description: "Share a pattern insight with another Herald context. Herald instances communicate through shared insights to propagate learned patterns across domains.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                context: { type: "string", description: "Target context to share insight with" },
+                insight: { type: "string", description: "The insight to share" },
+                topic: { type: "string", description: "Optional topic/category for the insight" },
+            },
+            required: ["context", "insight"],
+        },
+    },
+    {
+        name: "herald_query_insights",
+        description: "Query Herald's accumulated insights on a topic. Herald draws from pattern knowledge shared across contexts. Use this when you need guidance on implementation decisions or domain patterns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                question: { type: "string", description: "What you need insight on" },
+                domain: { type: "string", description: "Optional domain context" },
+            },
+            required: ["question"],
+        },
+    },
 ];
-// Handle list tools
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools,
-}));
-// Handle tool calls
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    let result;
     switch (name) {
-        case "herald_health": {
-            // Maps to: GET /health
-            const result = await callCedaAPI("/health");
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
-        }
-        case "herald_stats": {
-            // Maps to: GET /api/stats
-            const result = await callCedaAPI("/api/stats");
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
-        }
+        case "herald_health":
+            result = await callCedaAPI("/health");
+            break;
+        case "herald_stats":
+            result = await callCedaAPI("/api/stats");
+            break;
         case "herald_predict": {
-            // Maps to: POST /api/predict
             const params = args;
-            // Build context array if additional context provided
-            const context = params.context ? [
-                {
-                    type: "user_context",
-                    value: params.context,
-                    source: "herald_mcp",
-                }
-            ] : [];
-            const result = await callCedaAPI("/api/predict", "POST", {
+            const context = params.context ? [{ type: "user_context", value: params.context, source: "herald_mcp" }] : [];
+            result = await callCedaAPI("/api/predict", "POST", {
                 input: params.signal,
                 context,
                 sessionId: params.session_id,
                 participant: params.participant,
-                config: {
-                    enableAutoFix: true,
-                    maxAutoFixAttempts: 3,
-                },
+                config: { enableAutoFix: true, maxAutoFixAttempts: 3 },
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            break;
         }
         case "herald_refine": {
-            // Maps to: POST /api/refine
             const params = args;
-            // Build context array if additional context provided
-            const context = params.context ? [
-                {
-                    type: "refinement_context",
-                    value: params.context,
-                    source: "herald_mcp",
-                }
-            ] : [];
-            const result = await callCedaAPI("/api/refine", "POST", {
+            const context = params.context ? [{ type: "refinement_context", value: params.context, source: "herald_mcp" }] : [];
+            result = await callCedaAPI("/api/refine", "POST", {
                 sessionId: params.session_id,
                 refinement: params.refinement,
                 context,
                 participant: params.participant,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            break;
         }
         case "herald_session": {
-            // Maps to: GET /api/session/:id
             const params = args;
-            const result = await callCedaAPI(`/api/session/${params.session_id}`);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            result = await callCedaAPI(`/api/session/${params.session_id}`);
+            break;
         }
         case "herald_observe": {
-            // Maps to: POST /api/feedback
             const params = args;
-            const result = await callCedaAPI("/api/feedback", "POST", {
-                sessionId: params.session_id, // CEDA uses camelCase
+            result = await callCedaAPI("/api/feedback", "POST", {
+                sessionId: params.session_id,
                 accepted: params.accepted,
                 comment: params.feedback,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
+            break;
+        }
+        // === HERALD CONTEXT SYNC HANDLERS ===
+        case "herald_context_status": {
+            const params = args;
+            const knownContexts = ["goprint", "disrupt", "spilno"];
+            const contextsToQuery = params.context ? [params.context] : knownContexts;
+            // Cloud mode: Call CEDA API (Herald-to-Herald protocol)
+            if (OFFSPRING_CLOUD_MODE && CEDA_API_URL) {
+                const contextParam = params.context ? `?context=${params.context}` : "";
+                result = await callCedaAPI(`/api/herald/contexts${contextParam}`);
+                break;
+            }
+            const statuses = [];
+            for (const ctx of contextsToQuery) {
+                const statusPath = join(AEGIS_OFFSPRING_PATH, `${ctx}.md`);
+                if (!existsSync(statusPath)) {
+                    statuses.push({
+                        context: ctx,
+                        status: "not_found",
+                        sessionCount: 0,
+                        lastOutcome: null,
+                        activeThreads: [],
+                        blockers: [],
+                        pendingItems: [],
+                        readyForSync: false,
+                    });
+                    continue;
+                }
+                const content = readFileSync(statusPath, "utf-8");
+                const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+                if (!frontmatterMatch) {
+                    statuses.push({
+                        context: ctx,
+                        status: "invalid_format",
+                        sessionCount: 0,
+                        lastOutcome: null,
+                        activeThreads: [],
+                        blockers: [],
+                        pendingItems: [],
+                        readyForSync: false,
+                    });
+                    continue;
+                }
+                const yaml = frontmatterMatch[1];
+                const parseYamlArray = (key) => {
+                    const match = yaml.match(new RegExp(`${key}:\\s*\\n((?:\\s+-[^\\n]+\\n?)+)`, "m"));
+                    if (!match)
+                        return [];
+                    return match[1]
+                        .split("\n")
+                        .filter((line) => line.trim().startsWith("-"))
+                        .map((line) => line.replace(/^\s*-\s*/, "").trim());
+                };
+                const parseYamlValue = (key) => {
+                    const match = yaml.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, "m"));
+                    return match ? match[1].trim() : null;
+                };
+                statuses.push({
+                    context: ctx,
+                    status: "active",
+                    sessionCount: parseInt(parseYamlValue("session_count") || "0", 10),
+                    lastOutcome: parseYamlValue("outcome"),
+                    activeThreads: parseYamlArray("active_threads"),
+                    blockers: parseYamlArray("blockers"),
+                    pendingItems: parseYamlArray("awaiting_aegis"), // Read from file but expose as pendingItems
+                    readyForSync: parseYamlValue("ready_for_handoff") === "true",
+                });
+            }
+            const totalSessions = statuses.reduce((sum, s) => sum + s.sessionCount, 0);
+            const pendingCount = statuses.reduce((sum, s) => sum + s.pendingItems.length, 0);
+            result = {
+                success: true,
+                mode: "local",
+                statuses,
+                summary: {
+                    totalSessions,
+                    pendingItemsCount: pendingCount,
+                    contextsQueried: contextsToQuery.length,
+                },
+            };
+            break;
+        }
+        case "herald_share_insight": {
+            const params = args;
+            const validContexts = ["goprint", "disrupt", "spilno"];
+            if (!validContexts.includes(params.context)) {
+                result = { success: false, error: `Unknown context: ${params.context}. Valid: ${validContexts.join(", ")}` };
+                break;
+            }
+            // Cloud mode: Call CEDA API (Herald-to-Herald protocol)
+            if (OFFSPRING_CLOUD_MODE && CEDA_API_URL) {
+                result = await callCedaAPI("/api/herald/insight", "POST", {
+                    targetContext: params.context,
+                    insight: params.insight,
+                    topic: params.topic,
+                });
+                break;
+            }
+            // Local mode: Write to filesystem
+            const insightPath = join(AEGIS_OFFSPRING_PATH, `${params.context}_insights.md`);
+            const entry = `---
+timestamp: ${new Date().toISOString()}
+from: herald
+topic: ${params.topic || "general"}
+---
+
+${params.insight}
+
+---
+`;
+            let existingContent = "";
+            if (existsSync(insightPath)) {
+                existingContent = readFileSync(insightPath, "utf-8");
+            }
+            writeFileSync(insightPath, existingContent + entry);
+            result = {
+                success: true,
+                mode: "local",
+                context: params.context,
+                message: `Insight shared with ${params.context}`,
+                path: insightPath,
+            };
+            break;
+        }
+        case "herald_query_insights": {
+            const params = args;
+            // Determine which context Herald is serving
+            const ctx = HERALD_VAULT || "default";
+            // Cloud mode: Call CEDA API (Herald-to-Herald protocol)
+            if (OFFSPRING_CLOUD_MODE && CEDA_API_URL) {
+                result = await callCedaAPI(`/api/herald/insights?context=${ctx}&query=${encodeURIComponent(params.question)}`);
+                break;
+            }
+            // Local mode: Read from filesystem
+            const insightsPath = join(AEGIS_OFFSPRING_PATH, `${ctx}_insights.md`);
+            let relevantInsights = "";
+            if (existsSync(insightsPath)) {
+                const content = readFileSync(insightsPath, "utf-8");
+                const entries = content.split(/^---$/m).filter((e) => e.trim());
+                const keywords = params.question.toLowerCase().split(/\s+/);
+                for (const entry of entries) {
+                    const entryLower = entry.toLowerCase();
+                    if (keywords.some((kw) => kw.length > 3 && entryLower.includes(kw))) {
+                        relevantInsights += entry.trim() + "\n\n";
+                    }
+                }
+            }
+            let response = `**Herald's Insight**\n\nOn your query: "${params.question}"\n\n`;
+            if (relevantInsights) {
+                response += `From accumulated pattern knowledge:\n\n${relevantInsights}`;
+            }
+            else {
+                response += `I don't have specific insights on this yet. Consider:\n`;
+                response += `1. Proceeding with your best judgment\n`;
+                response += `2. Recording your approach with herald_observe so I can learn\n`;
+                response += `3. The pattern will emerge through practice`;
+            }
+            result = {
+                success: true,
+                mode: "local",
+                context: ctx,
+                question: params.question,
+                response,
+                hasInsights: !!relevantInsights,
             };
+            break;
         }
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-// Start server
-async function main() {
+async function runMCP() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Herald MCP server running on stdio");
 }
+// ============================================
+// ENTRY POINT - Detect mode
+// ============================================
+async function main() {
+    const args = process.argv.slice(2);
+    // If we have CLI arguments, run CLI mode
+    if (args.length > 0) {
+        await runCLI(args);
+        return;
+    }
+    // If stdin is a TTY (human at terminal), show help
+    if (process.stdin.isTTY) {
+        printUsage();
+        return;
+    }
+    // Otherwise, run MCP server (AI agent calling via pipe)
+    await runMCP();
+}
 main().catch(console.error);

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@spilno/herald-mcp",
-  "version": "1.1.3",
+  "version": "1.3.0",
   "description": "Herald MCP - AI-native interface to CEDA (Cognitive Event-Driven Architecture)",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "herald-mcp": "./dist/index.js"
+    "herald-mcp": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/index.js",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build"