@spilno/herald-mcp 1.34.3 → 1.34.4

package/README.md

@@ -30,11 +30,31 @@ herald.gotStuck('What failed');
 
 ## Quick Start
 
+### MCP Server (for AI agents like Claude)
+
 ```bash
 cd your-project
 npx @spilno/herald-mcp init
 ```
 
+### SDK (for programmatic access)
+
+```typescript
+import { herald } from '@spilno/herald-mcp';
+
+// Capture a pattern (something that worked)
+await herald.learned('Always run tests before committing');
+
+// Capture an antipattern (something that failed)
+await herald.gotStuck('Forgot to check existing tests before refactoring');
+
+// Query patterns
+const patterns = await herald.recall();
+
+// Configure (optional - uses git context by default)
+herald.configure({ baseUrl: 'https://custom.ceda.com', token: 'your-token' });
+```
+
 **What this does:**
 1. Creates `.mcp.json` with Herald MCP configuration
 2. Fetches learned patterns from CEDA (if any exist)
@@ -223,6 +243,82 @@ CEDA (Cognitive Event-Driven Architecture) is pattern memory for AI:
 
 Unlike RAG (retrieves content), CEDA retrieves **what worked**.
 
+## SDK API
+
+The SDK provides programmatic access to CEDA pattern memory for use in your own applications.
+
+### Installation
+
+```bash
+npm install @spilno/herald-mcp
+```
+
+### API Reference
+
+#### `herald.learned(insight, context?)`
+
+Capture a pattern (something that worked).
+
+```typescript
+await herald.learned('Always run tests before committing');
+await herald.learned('Use feature flags for gradual rollouts', 'deployment pipeline');
+```
+
+#### `herald.gotStuck(insight, context?)`
+
+Capture an antipattern (something that failed).
+
+```typescript
+await herald.gotStuck('Forgot to check existing tests before refactoring');
+await herald.gotStuck('Deployed without running migrations', 'production incident');
+```
+
+#### `herald.recall(topic?)`
+
+Query learned patterns and antipatterns.
+
+```typescript
+const patterns = await herald.recall();
+const deployPatterns = await herald.recall('deployment');
+```
+
+Returns an array of `Pattern` objects:
+
+```typescript
+interface Pattern {
+  insight: string;
+  feeling: 'success' | 'stuck';
+  signal?: string;
+  reinforcement?: string;
+  warning?: string;
+  scope?: string;
+}
+```
+
+#### `herald.configure(opts)`
+
+Configure the SDK (optional - uses git context by default).
+
+```typescript
+herald.configure({
+  baseUrl: 'https://custom.ceda.com',
+  token: 'your-api-token',
+  company: 'acme',
+  project: 'backend',
+  user: 'developer'
+});
+```
+
+### Context Detection
+
+By default, the SDK automatically derives context from:
+
+1. **Git remote** - Organization and repository name from git origin
+2. **Git user** - User name from git config
+3. **Path** - Falls back to folder names if not in a git repo
+
+This means you can use the SDK without any configuration in most projects.
+
 ## Links
 
 - **CEDA**: https://getceda.com
@@ -235,4 +331,4 @@ MIT
 
 ---
 
-*Herald v1.25.0 — Pattern memory for AI agents*
+*Herald v1.33.0 — Pattern memory for AI agents*

package/dist/cli.js

@@ -134,9 +134,11 @@ function hashTag(input) {
 }
 function deriveTagSet() {
     // 1. Check env vars (explicit override)
-    if (process.env.HERALD_COMPANY) {
+    // HERALD_ORG is primary, HERALD_COMPANY for backwards compat
+    const envOrg = process.env.HERALD_ORG || process.env.HERALD_COMPANY;
+    if (envOrg) {
         return {
-            tags: [process.env.HERALD_COMPANY, process.env.HERALD_PROJECT].filter(Boolean),
+            tags: [envOrg, process.env.HERALD_PROJECT].filter(Boolean),
             trust: 'LOW', // Env vars can be set by anyone
             source: 'env',
             propagates: false
@@ -213,9 +215,11 @@ function persistContext(tagSet, user) {
 function loadOrDeriveContext() {
     const user = process.env.HERALD_USER || deriveUser();
     // 1. Check env vars (explicit override - highest priority, but LOW trust)
-    if (process.env.HERALD_COMPANY) {
+    // HERALD_ORG is primary, HERALD_COMPANY for backwards compat
+    const envOrg = process.env.HERALD_ORG || process.env.HERALD_COMPANY;
+    if (envOrg) {
         return {
-            tags: [process.env.HERALD_COMPANY, process.env.HERALD_PROJECT].filter(Boolean),
+            tags: [envOrg, process.env.HERALD_PROJECT].filter(Boolean),
             user,
             trust: 'LOW',
             source: 'env',
@@ -261,7 +265,7 @@ const LOADED_CONTEXT = loadOrDeriveContext();
 let HERALD_USER = LOADED_CONTEXT.user;
 // Tags from context (env > stored > git > path) - can be refreshed
 let HERALD_TAGS = LOADED_CONTEXT.tags;
-let HERALD_COMPANY = HERALD_TAGS[0] || "";
+let HERALD_ORG = HERALD_TAGS[0] || "";
 let HERALD_PROJECT = HERALD_TAGS[1] || HERALD_TAGS[0] || "";
 // ADR-001: Trust level determines pattern propagation
 // These are mutable - verification with CEDA may upgrade/downgrade trust
@@ -307,7 +311,7 @@ const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || "";
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY || "";
 // Session persistence - context-isolated paths
 function getHeraldDir() {
-    return join(homedir(), ".herald", HERALD_COMPANY, HERALD_PROJECT, HERALD_USER);
+    return join(homedir(), ".herald", HERALD_ORG, HERALD_PROJECT, HERALD_USER);
 }
 function getSessionFile() {
     return join(getHeraldDir(), "session");
@@ -424,7 +428,7 @@ function clearSession() {
     }
 }
 function getContextString() {
-    return `${HERALD_COMPANY}:${HERALD_PROJECT}:${HERALD_USER}`;
+    return `${HERALD_ORG}:${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.
@@ -672,7 +676,7 @@ async function callCedaAPI(endpoint, method = "GET", body) {
         endpoint.startsWith("/api/observations");
     if (method === "GET" && needsTenantParams) {
         const separator = endpoint.includes("?") ? "&" : "?";
-        url += `${separator}company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}`;
+        url += `${separator}org=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}`;
     }
     const headers = {
         "Content-Type": "application/json",
@@ -685,7 +689,7 @@ async function callCedaAPI(endpoint, method = "GET", body) {
     if (method === "POST" && body && typeof body === "object") {
         enrichedBody = {
             ...body,
-            company: HERALD_COMPANY,
+            org: HERALD_ORG,
             project: HERALD_PROJECT,
             user: HERALD_USER,
         };
@@ -1077,7 +1081,7 @@ Example flow:
         inputSchema: {
             type: "object",
             properties: {
-                company: { type: "string", description: "Filter by company (optional, defaults to HERALD_COMPANY)" },
+                org: { type: "string", description: "Filter by org (optional, defaults to HERALD_ORG)" },
                 project: { type: "string", description: "Filter by project (optional)" },
                 user: { type: "string", description: "Filter by user (optional)" },
                 status: { type: "string", description: "Filter by status: active, archived, or expired (optional)" },
@@ -1412,9 +1416,9 @@ async function fetchPatternsWithCascade() {
     const patterns = [];
     const antipatterns = [];
     const queries = [
-        { scope: "user", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100` },
-        { scope: "project", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&limit=100` },
-        { scope: "company", url: `/api/herald/reflections?company=${HERALD_COMPANY}&limit=100` },
+        { scope: "user", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100` },
+        { scope: "project", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&limit=100` },
+        { scope: "org", url: `/api/herald/reflections?org=${HERALD_ORG}&limit=100` },
     ];
     for (const { scope, url } of queries) {
         try {
@@ -1440,14 +1444,14 @@ async function fetchPatternsWithCascade() {
             // Continue if a level fails
         }
     }
-    return { patterns, antipatterns, context: `${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}` };
+    return { patterns, antipatterns, context: `${HERALD_USER}→${HERALD_PROJECT}→${HERALD_ORG}` };
 }
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
     const resources = [
         {
             uri: "herald://patterns",
             name: "Herald Learned Patterns",
-            description: `Patterns and antipatterns learned from past sessions for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}. READ THIS AT SESSION START.`,
+            description: `Patterns and antipatterns learned from past sessions for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_ORG}. READ THIS AT SESSION START.`,
             mimeType: "text/plain",
         },
         {
@@ -1504,7 +1508,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     }
     if (uri === "herald://context") {
         const context = {
-            company: HERALD_COMPANY,
+            org: HERALD_ORG,
             project: HERALD_PROJECT,
             user: HERALD_USER,
             vault: HERALD_VAULT || null,
@@ -1536,7 +1540,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 Welcome to Herald - your AI-native interface to CEDA (Cognitive Event-Driven Architecture).
 
 ## Current Context
-- Company: ${HERALD_COMPANY}
+- Company: ${HERALD_ORG}
 - Project: ${HERALD_PROJECT}
 - User: ${HERALD_USER}
 
@@ -1597,7 +1601,7 @@ Herald will:
                 const cloudAvailable = !cedaHealth.error;
                 const config = {
                     cedaUrl: CEDA_API_URL,
-                    company: HERALD_COMPANY,
+                    org: HERALD_ORG,
                     project: HERALD_PROJECT,
                     user: HERALD_USER,
                     vault: HERALD_VAULT || "(not set)",
@@ -1642,7 +1646,7 @@ Herald will:
                     // Update module-level variables directly
                     HERALD_USER = newContext.user;
                     HERALD_TAGS = newContext.tags;
-                    HERALD_COMPANY = newContext.tags[0] || "";
+                    HERALD_ORG = newContext.tags[0] || "";
                     HERALD_PROJECT = newContext.tags[1] || newContext.tags[0] || "";
                     TRUST_LEVEL = newContext.trust;
                     CONTEXT_SOURCE = newContext.source;
@@ -1653,7 +1657,7 @@ Herald will:
                                 text: JSON.stringify({
                                     refreshed: true,
                                     context: {
-                                        company: HERALD_COMPANY,
+                                        org: HERALD_ORG,
                                         project: HERALD_PROJECT,
                                         user: HERALD_USER,
                                         tags: HERALD_TAGS,
@@ -1675,7 +1679,7 @@ Herald will:
                             type: "text",
                             text: JSON.stringify({
                                 context: {
-                                    company: HERALD_COMPANY,
+                                    org: HERALD_ORG,
                                     project: HERALD_PROJECT,
                                     user: HERALD_USER,
                                     tags: HERALD_TAGS,
@@ -1823,7 +1827,7 @@ Herald will:
                     topic,
                     targetVault,
                     sourceVault: HERALD_VAULT || undefined,
-                    company: HERALD_COMPANY,
+                    org: HERALD_ORG,
                     project: HERALD_PROJECT,
                     user: HERALD_USER,
                 };
@@ -1835,7 +1839,7 @@ Herald will:
                         insight,
                         toContext: targetVault || "all", // Required by CEDA, default to broadcast
                         topic,
-                        fromContext: HERALD_VAULT || `${HERALD_COMPANY}/${HERALD_PROJECT}`,
+                        fromContext: HERALD_VAULT || `${HERALD_ORG}/${HERALD_PROJECT}`,
                     });
                     // Check if API returned an error
                     if (result.error) {
@@ -1916,12 +1920,29 @@ Herald will:
                 const failed = [];
                 for (const item of buffer) {
                     try {
-                        const result = await callCedaAPI("/api/herald/insight", "POST", {
-                            insight: item.insight,
-                            topic: item.topic,
-                            toContext: item.targetVault || "all", // CEDA expects toContext, default to "all"
-                            fromContext: item.sourceVault, // CEDA expects fromContext
-                        });
+                        let result;
+                        // CEDA-100: Route based on buffer item type
+                        if (item.type === "reflection") {
+                            // Reflections go to /api/herald/reflect (stored in PlanetScale, shown in dashboard)
+                            result = await callCedaAPI("/api/herald/reflect", "POST", {
+                                session: item.session || item.insight,
+                                feeling: item.feeling || "success",
+                                insight: item.insight,
+                                method: item.method || "direct",
+                                org: item.org,
+                                project: item.project,
+                                user: item.user,
+                            });
+                        }
+                        else {
+                            // Insights (default) go to /api/herald/insight (legacy behavior)
+                            result = await callCedaAPI("/api/herald/insight", "POST", {
+                                insight: item.insight,
+                                topic: item.topic,
+                                toContext: item.targetVault || "all",
+                                fromContext: item.sourceVault,
+                            });
+                        }
                         if (result.error) {
                             failed.push(item);
                         }
@@ -1972,7 +1993,7 @@ Herald will:
                 const status = args?.status;
                 const limit = args?.limit;
                 const params = new URLSearchParams();
-                params.set("company", company || HERALD_COMPANY);
+                params.set("company", company || HERALD_ORG);
                 if (project)
                     params.set("project", project);
                 if (user)
@@ -2097,17 +2118,22 @@ Herald will:
                         feeling,
                         insight: sanitizedInsight, // Sanitized - no PII/secrets transmitted
                         method: "direct", // Track capture method for meta-learning
-                        company: HERALD_COMPANY,
+                        org: HERALD_ORG,
                         project: HERALD_PROJECT,
                         user: HERALD_USER,
                         vault: HERALD_VAULT || undefined,
                     });
                     if (result.error) {
                         // If cloud fails, store locally for later processing (also sanitized)
+                        // CEDA-100: Mark as reflection type for proper sync routing
                         bufferInsight({
-                            insight: `[REFLECT:${feeling}] ${sanitizedInsight} | Context: ${sanitizedSession}`,
+                            insight: sanitizedInsight,
+                            session: sanitizedSession,
+                            feeling,
+                            method: "direct",
+                            type: "reflection",
                             topic: feeling === "stuck" ? "antipattern" : "pattern",
-                            company: HERALD_COMPANY,
+                            org: HERALD_ORG,
                             project: HERALD_PROJECT,
                             user: HERALD_USER,
                         });
@@ -2139,7 +2165,7 @@ Herald will:
                                         ? `Antipattern captured: "${insight}"`
                                         : `Pattern captured: "${insight}"`,
                                     context: {
-                                        company: HERALD_COMPANY,
+                                        org: HERALD_ORG,
                                         project: HERALD_PROJECT,
                                         tags: HERALD_TAGS,
                                         trust: TRUST_LEVEL,
@@ -2152,10 +2178,15 @@ Herald will:
                 }
                 catch (error) {
                     // Network error - buffer locally (sanitized)
+                    // CEDA-100: Mark as reflection type for proper sync routing
                     bufferInsight({
-                        insight: `[REFLECT:${feeling}] ${sanitizedInsight} | Context: ${sanitizedSession}`,
+                        insight: sanitizedInsight,
+                        session: sanitizedSession,
+                        feeling,
+                        method: "direct",
+                        type: "reflection",
                         topic: feeling === "stuck" ? "antipattern" : "pattern",
-                        company: HERALD_COMPANY,
+                        org: HERALD_ORG,
                         project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
@@ -2191,11 +2222,12 @@ Herald will:
                             return true;
                         }).map(item => ({ ...item, scope }));
                     };
-                    // Cascade queries: user (most specific) → project → company (broadest)
+                    // CEDA-95: Cascade queries with minLevel=1 to only return graduated patterns (not observations)
+                    // Observations (level 0) are raw captures; patterns (level 1+) are validated
                     const queries = [
-                        { scope: "user", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100` },
-                        { scope: "project", url: `/api/herald/reflections?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&limit=100` },
-                        { scope: "company", url: `/api/herald/reflections?company=${HERALD_COMPANY}&limit=100` },
+                        { scope: "user", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100&minLevel=1` },
+                        { scope: "project", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&limit=100&minLevel=1` },
+                        { scope: "org", url: `/api/herald/reflections?org=${HERALD_ORG}&limit=100&minLevel=1` },
                     ];
                     const patterns = [];
                     const antipatterns = [];
@@ -2215,7 +2247,7 @@ Herald will:
                     const metaResult = await callCedaAPI("/api/herald/meta-patterns");
                     const metaPatterns = metaResult.metaPatterns || [];
                     // Build readable summary with scope indicators
-                    let summary = `## Learned Patterns for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}\n\n`;
+                    let summary = `## Learned Patterns for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_ORG}\n\n`;
                     if (antipatterns.length > 0) {
                         summary += `### ⚠️ Antipatterns (avoid these)\n`;
                         antipatterns.forEach((ap, i) => {
@@ -2244,7 +2276,7 @@ Herald will:
                         summary += `Recommended capture method: ${meta.recommendedMethod} (${(meta.confidence * 100).toFixed(0)}% confidence)\n`;
                     }
                     if (patterns.length === 0 && antipatterns.length === 0) {
-                        summary = `No patterns learned yet for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_COMPANY}.\n\nCapture patterns with "herald reflect" or "herald simulate" when you notice friction or flow.`;
+                        summary = `No patterns learned yet for ${HERALD_USER}→${HERALD_PROJECT}→${HERALD_ORG}.\n\nCapture patterns with "herald reflect" or "herald simulate" when you notice friction or flow.`;
                     }
                     return {
                         content: [{
@@ -2328,17 +2360,22 @@ Herald will:
                         outcome: extracted.outcome,
                         reinforcement: sanitizedReinforcement,
                         warning: sanitizedWarning,
-                        company: HERALD_COMPANY,
+                        org: HERALD_ORG,
                         project: HERALD_PROJECT,
                         user: HERALD_USER,
                         vault: HERALD_VAULT || undefined,
                     });
                     if (result.error) {
                         // Cloud failed but we have AI extraction - buffer with enriched data (sanitized)
+                        // CEDA-100: Mark as reflection type for proper sync routing
                         bufferInsight({
-                            insight: `[SIMULATE:${feeling}] Signal: ${sanitizedSignal} | Insight: ${simSanitizedInsight} | ${extracted.outcome === "pattern" ? `Reinforce: ${sanitizedReinforcement}` : `Warn: ${sanitizedWarning}`}`,
+                            insight: simSanitizedInsight,
+                            session: simSanitizedSession,
+                            feeling,
+                            method: "simulation",
+                            type: "reflection",
                             topic: extracted.outcome,
-                            company: HERALD_COMPANY,
+                            org: HERALD_ORG,
                             project: HERALD_PROJECT,
                             user: HERALD_USER,
                         });
@@ -2446,7 +2483,7 @@ Herald will:
                         patternText,
                         outcome,
                         helped: outcome === "helped",
-                        company: HERALD_COMPANY,
+                        org: HERALD_ORG,
                         project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
@@ -2497,7 +2534,7 @@ Herald will:
                         insight,
                         scope,
                         topic,
-                        sourceCompany: HERALD_COMPANY,
+                        sourceCompany: HERALD_ORG,
                         sourceProject: HERALD_PROJECT,
                         sourceUser: HERALD_USER,
                         sourceVault: HERALD_VAULT || undefined,
@@ -2568,7 +2605,7 @@ Herald will:
                         patternId,
                         sessionId,
                         all: deleteAll,
-                        company: HERALD_COMPANY,
+                        org: HERALD_ORG,
                         project: HERALD_PROJECT,
                         user: HERALD_USER,
                     });
@@ -2592,7 +2629,7 @@ Herald will:
                         message = `All patterns from session ${sessionId} deleted`;
                     }
                     else if (deleteAll) {
-                        message = `All patterns for ${HERALD_COMPANY}/${HERALD_PROJECT}/${HERALD_USER} deleted`;
+                        message = `All patterns for ${HERALD_ORG}/${HERALD_PROJECT}/${HERALD_USER} deleted`;
                     }
                     return {
                         content: [{
@@ -2622,7 +2659,7 @@ Herald will:
             case "herald_export": {
                 const format = args?.format || "json";
                 try {
-                    const result = await callCedaAPI(`/api/herald/export?company=${HERALD_COMPANY}&project=${HERALD_PROJECT}&user=${HERALD_USER}&format=${format}`);
+                    const result = await callCedaAPI(`/api/herald/export?org=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&format=${format}`);
                     if (result.error) {
                         return {
                             content: [{
@@ -2643,7 +2680,7 @@ Herald will:
                                     message: `Data exported in ${format.toUpperCase()} format (GDPR Art. 20)`,
                                     gdprArticle: "Article 20 - Right to Data Portability",
                                     format,
-                                    context: `${HERALD_COMPANY}/${HERALD_PROJECT}/${HERALD_USER}`,
+                                    context: `${HERALD_ORG}/${HERALD_PROJECT}/${HERALD_USER}`,
                                     ...result,
                                 }, null, 2)
                             }],
@@ -2734,7 +2771,7 @@ async function verifyWithCeda() {
             const ctx = result.context;
             VERIFIED_CONTEXT = {
                 verified: true,
-                company: ctx.company,
+                org: (ctx.org || ctx.company),
                 project: ctx.project,
                 trust: ctx.trust,
                 tags: ctx.tags,
@@ -2743,7 +2780,7 @@ async function verifyWithCeda() {
             TRUST_LEVEL = VERIFIED_CONTEXT.trust || 'HIGH';
             PROPAGATES = true;
             CONTEXT_SOURCE = 'verified';
-            console.error(`[Herald] Verified with CEDA: ${VERIFIED_CONTEXT.company}/${VERIFIED_CONTEXT.project} (trust: HIGH)`);
+            console.error(`[Herald] Verified with CEDA: ${VERIFIED_CONTEXT.org}/${VERIFIED_CONTEXT.project} (trust: HIGH)`);
         }
         else {
             // Not verified - user not registered or no access to this repo
@@ -2794,7 +2831,7 @@ async function runMCP() {
     console.error(`User: ${HERALD_USER} | Tags: [${HERALD_TAGS.join(", ")}]`);
     console.error(`Trust: ${TRUST_LEVEL} (${CONTEXT_SOURCE})${PROPAGATES ? " | Propagates: YES" : ""}`);
     if (VERIFIED_CONTEXT?.verified) {
-        console.error(`Context: ${VERIFIED_CONTEXT.company}/${VERIFIED_CONTEXT.project} (server-verified)`);
+        console.error(`Context: ${VERIFIED_CONTEXT.org}/${VERIFIED_CONTEXT.project} (server-verified)`);
     }
     // Send startup heartbeat for visibility (non-blocking)
     sendStartupHeartbeat();