@spilno/herald-mcp 1.36.0 → 1.36.2

package/dist/cli.js

@@ -26,11 +26,106 @@ import { sanitize, previewSanitization } from "./sanitization.js";
 const CEDA_API_URL = process.env.CEDA_URL || process.env.HERALD_API_URL || "https://getceda.com";
 // CEDA_TOKEN is the primary auth (from app.getceda.com OAuth)
 // HERALD_API_TOKEN kept for backwards compatibility
-const CEDA_API_TOKEN = process.env.CEDA_TOKEN || process.env.HERALD_API_TOKEN;
+// CEDA-FIX: Also check ~/.herald/token.json for global token (one key per user)
+const TOKEN_FILE_PATH = join(homedir(), ".herald", "token.json");
+function loadGlobalToken() {
+    try {
+        if (existsSync(TOKEN_FILE_PATH)) {
+            const data = JSON.parse(readFileSync(TOKEN_FILE_PATH, "utf-8"));
+            return {
+                token: data.token || undefined,
+                refreshToken: data.refreshToken || undefined,
+            };
+        }
+    }
+    catch {
+        // Ignore errors reading global token
+    }
+    return {};
+}
+function isTokenExpired(token) {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());
+        if (!payload.exp)
+            return true;
+        // Consider expired if less than 60s remaining
+        return payload.exp * 1000 < Date.now() + 60_000;
+    }
+    catch {
+        return true;
+    }
+}
+const globalTokens = loadGlobalToken();
+let CEDA_API_TOKEN = process.env.CEDA_TOKEN || process.env.HERALD_API_TOKEN || globalTokens.token;
+let CEDA_REFRESH_TOKEN = globalTokens.refreshToken;
+// Mutex: serialize concurrent refresh attempts so only one network call fires
+let refreshInFlight = null;
+/**
+ * Refresh the access token using the stored refresh token.
+ * Updates in-memory token and writes back to ~/.herald/token.json.
+ * Returns true on success, false on failure.
+ * Concurrent calls coalesce into a single network request.
+ */
+async function refreshAccessToken() {
+    if (refreshInFlight)
+        return refreshInFlight;
+    refreshInFlight = doRefreshAccessToken().finally(() => { refreshInFlight = null; });
+    return refreshInFlight;
+}
+async function doRefreshAccessToken() {
+    if (!CEDA_REFRESH_TOKEN)
+        return false;
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 10_000);
+        const response = await fetch(`${CEDA_API_URL}/api/auth/refresh`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: CEDA_REFRESH_TOKEN }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            console.error(`[Herald] Token refresh failed: HTTP ${response.status}`);
+            return false;
+        }
+        const data = await response.json();
+        CEDA_API_TOKEN = data.accessToken;
+        CEDA_REFRESH_TOKEN = data.refreshToken;
+        // Write updated tokens back to disk
+        try {
+            if (existsSync(TOKEN_FILE_PATH)) {
+                const existing = JSON.parse(readFileSync(TOKEN_FILE_PATH, "utf-8"));
+                existing.token = data.accessToken;
+                existing.refreshToken = data.refreshToken;
+                // Update expiresAt from new token
+                try {
+                    const payload = JSON.parse(Buffer.from(data.accessToken.split('.')[1], 'base64').toString());
+                    existing.expiresAt = payload.exp
+                        ? new Date(payload.exp * 1000).toISOString()
+                        : new Date(Date.now() + data.expiresIn * 1000).toISOString();
+                }
+                catch {
+                    existing.expiresAt = new Date(Date.now() + data.expiresIn * 1000).toISOString();
+                }
+                writeFileSync(TOKEN_FILE_PATH, JSON.stringify(existing, null, 2), "utf-8");
+            }
+        }
+        catch {
+            // Non-fatal: token works in memory even if disk write fails
+        }
+        console.error("[Herald] Token refreshed");
+        return true;
+    }
+    catch (error) {
+        console.error(`[Herald] Token refresh error: ${error}`);
+        return false;
+    }
+}
 const CEDA_API_USER = process.env.HERALD_API_USER;
 const CEDA_API_PASS = process.env.HERALD_API_PASS;
 // CEDA-70: Zero-config context - everything auto-derived, nothing required
-// User is ALWAYS known (whoami). Company/project inferred from path as tags.
+// User is ALWAYS known (whoami). Org/project inferred from path as tags.
 function deriveUser() {
     // Priority: git user > env var > OS user
     // Git user is trusted (immutable identity from git config)
@@ -729,8 +824,55 @@ async function callCedaAPI(endpoint, method = "GET", body) {
             signal: controller.signal,
         });
         clearTimeout(timeoutId);
+        if (response.status === 401 && CEDA_REFRESH_TOKEN) {
+            // Drain original response body to avoid leak
+            await response.text().catch(() => { });
+            // Attempt auto-refresh and retry once
+            const refreshed = await refreshAccessToken();
+            if (refreshed) {
+                const retryHeaders = { ...headers, Authorization: `Bearer ${CEDA_API_TOKEN}` };
+                const retryController = new AbortController();
+                const retryTimeoutId = setTimeout(() => retryController.abort(), CEDA_REQUEST_TIMEOUT_MS);
+                try {
+                    const retryResponse = await fetch(url, {
+                        method,
+                        headers: retryHeaders,
+                        body: enrichedBody ? JSON.stringify(enrichedBody) : undefined,
+                        signal: retryController.signal,
+                    });
+                    clearTimeout(retryTimeoutId);
+                    if (!retryResponse.ok) {
+                        try {
+                            const errorBody = await retryResponse.json();
+                            return { success: false, error: `HTTP ${retryResponse.status}: ${errorBody.message || errorBody.error || retryResponse.statusText}`, details: errorBody };
+                        }
+                        catch {
+                            return { success: false, error: `HTTP ${retryResponse.status}: ${retryResponse.statusText}` };
+                        }
+                    }
+                    return await retryResponse.json();
+                }
+                catch (retryError) {
+                    clearTimeout(retryTimeoutId);
+                    return { success: false, error: `Retry after refresh failed: ${retryError}` };
+                }
+            }
+            // Refresh failed — fall through with a synthetic 401 error
+            return { success: false, error: `HTTP 401: Unauthorized (token refresh failed)` };
+        }
         if (!response.ok) {
-            return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
+            // CEDA-FIX: Include response body for better error messages
+            try {
+                const errorBody = await response.json();
+                return {
+                    success: false,
+                    error: `HTTP ${response.status}: ${errorBody.message || errorBody.error || response.statusText}`,
+                    details: errorBody
+                };
+            }
+            catch {
+                return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
+            }
         }
         return await response.json();
     }
@@ -953,7 +1095,7 @@ const tools = [
     },
     {
         name: "herald_context",
-        description: `Get or refresh Herald's context (company/project/user).
+        description: `Get or refresh Herald's context (org/project/user).
 
 Context is derived from git (trusted) or path (fallback).
 Use refresh=true after cloning a repo or changing directories to update context.
@@ -1118,7 +1260,7 @@ Example flow:
     // CEDA-49: Session Management Tools
     {
         name: "herald_session_list",
-        description: "List sessions for a company with optional filters. Returns session summaries including id, status, created/updated timestamps.",
+        description: "List sessions for a org with optional filters. Returns session summaries including id, status, created/updated timestamps.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1235,6 +1377,52 @@ Shows what would be redacted and final transmitted text.`,
             required: ["session", "feeling", "insight"],
         },
     },
+    // Capture raw observation (Level 0) - feeds into graduation pipeline
+    {
+        name: "herald_observe",
+        description: `Capture a raw observation (Level 0) for later pattern graduation.
+
+Unlike herald_reflect (Level 1, pre-validated), observations are raw signals that
+feed into CEDA's clustering pipeline. When enough similar observations accumulate,
+they auto-graduate into patterns.
+
+WHEN TO USE:
+- You notice something interesting but aren't sure if it's a pattern yet
+- Recording a data point without committing to "pattern" or "antipattern"
+- Logging what happened for later analysis
+- "That's interesting..." moments
+
+WHEN TO USE herald_reflect INSTEAD:
+- You're confident it IS a pattern or antipattern
+- User explicitly says "capture this" / "log this pattern"
+- Clear success or failure signal
+
+Example flow:
+1. User tries a new approach → herald_observe (raw signal)
+2. Same approach works 3x → CEDA auto-graduates to pattern
+3. User confirms it's reliable → herald_reflect (validated)
+
+TRIGGER WORDS: "observe", "note this", "interesting", "log observation", "raw signal"`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                input: {
+                    type: "string",
+                    description: "What was observed — the raw signal or event"
+                },
+                outcome: {
+                    type: "string",
+                    enum: ["accepted", "modified", "rejected"],
+                    description: "How it turned out: accepted (worked), modified (worked with changes), rejected (didn't work)"
+                },
+                feedback: {
+                    type: "string",
+                    description: "Optional context or notes about the observation"
+                },
+            },
+            required: ["input", "outcome"],
+        },
+    },
     // Query learned patterns - Claude reads this to avoid repeating mistakes
     {
         name: "herald_patterns",
@@ -1359,8 +1547,8 @@ call with outcome="helped" to reinforce that pattern.`,
         description: `Share an insight with other Herald contexts using scope control.
 
 Scopes:
-- "parent": Share with parent project/company (escalate learning)
-- "siblings": Share with sibling projects in same company
+- "parent": Share with parent project/org (escalate learning)
+- "siblings": Share with sibling projects in same org
 - "all": Share globally across all contexts
 
 Use this to propagate valuable patterns beyond the current context.
@@ -1400,7 +1588,7 @@ Use this when:
 Parameters:
 - pattern_id: Delete a specific pattern by ID
 - session_id: Delete all patterns from a session
-- all: Delete ALL patterns for current context (company/project/user)
+- all: Delete ALL patterns for current context (org/project/user)
 
 WARNING: This action is irreversible. Data will be permanently deleted.`,
         inputSchema: {
@@ -1432,7 +1620,7 @@ Use this when:
 - Migrating data between systems
 - Compliance audit requires data export
 
-Returns all patterns for the current context (company/project/user) in the specified format.`,
+Returns all patterns for the current context (org/project/user) in the specified format.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -1456,11 +1644,11 @@ async function fetchPatternsWithCascade() {
     const seenInsights = new Set();
     const patterns = [];
     const antipatterns = [];
-    // CEDA-102: Use company param for backwards compat with deployed CEDA server
+    // CEDA-102: Use org param for backwards compat with deployed CEDA server
     const queries = [
-        { scope: "user", url: `/api/herald/reflections?company=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100` },
-        { scope: "project", url: `/api/herald/reflections?company=${HERALD_ORG}&project=${HERALD_PROJECT}&limit=100` },
-        { scope: "org", url: `/api/herald/reflections?company=${HERALD_ORG}&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 {
@@ -1499,7 +1687,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
         {
             uri: "herald://context",
             name: "Herald Context",
-            description: "Current Herald context configuration (company/project/user)",
+            description: "Current Herald context configuration (org/project/user)",
             mimeType: "application/json",
         },
     ];
@@ -1582,7 +1770,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 Welcome to Herald - your AI-native interface to CEDA (Cognitive Event-Driven Architecture).
 
 ## Current Context
-- Company: ${HERALD_ORG}
+- Org: ${HERALD_ORG}
 - Project: ${HERALD_PROJECT}
 - User: ${HERALD_USER}
 
@@ -1603,7 +1791,7 @@ Welcome to Herald - your AI-native interface to CEDA (Cognitive Event-Driven Arc
 - \`herald_session\` - View session history (legacy)
 
 **Session Management (CEDA-49):**
-- \`herald_session_list\` - List sessions with filters (company, project, user, status)
+- \`herald_session_list\` - List sessions with filters (org, project, user, status)
 - \`herald_session_get\` - Get detailed session info including prediction state
 - \`herald_session_history\` - View version history for a session
 - \`herald_session_rollback\` - Restore a session to a previous version
@@ -1960,6 +2148,7 @@ Herald will:
                 }
                 const synced = [];
                 const failed = [];
+                const errors = []; // CEDA-FIX: Track error details
                 for (const item of buffer) {
                     try {
                         let result;
@@ -1987,13 +2176,23 @@ Herald will:
                         }
                         if (result.error) {
                             failed.push(item);
+                            // CEDA-FIX: Capture error details
+                            const details = result.details;
+                            const errorMsg = String(details?.message || result.error);
+                            if (!errors.includes(errorMsg)) {
+                                errors.push(errorMsg);
+                            }
                         }
                         else {
                             synced.push(item);
                         }
                     }
-                    catch {
+                    catch (err) {
                         failed.push(item);
+                        const errorMsg = err instanceof Error ? err.message : String(err);
+                        if (!errors.includes(errorMsg)) {
+                            errors.push(errorMsg);
+                        }
                     }
                 }
                 // Save only failed items back to buffer
@@ -2007,6 +2206,8 @@ Herald will:
                                 synced: synced.length,
                                 failed: failed.length,
                                 remainingBuffer: failed.length,
+                                // CEDA-FIX: Include error details so users know WHY sync failed
+                                ...(errors.length > 0 && { errors }),
                             }, null, 2)
                         }],
                 };
@@ -2029,13 +2230,13 @@ Herald will:
             }
             // CEDA-49: Session Management Tools
             case "herald_session_list": {
-                const company = args?.company;
+                const org = args?.org;
                 const project = args?.project;
                 const user = args?.user;
                 const status = args?.status;
                 const limit = args?.limit;
                 const params = new URLSearchParams();
-                params.set("company", company || HERALD_ORG);
+                params.set("org", org || HERALD_ORG);
                 if (project)
                     params.set("project", project);
                 if (user)
@@ -2249,8 +2450,120 @@ Herald will:
                     };
                 }
             }
+            case "herald_observe": {
+                const input = args?.input;
+                const outcome = args?.outcome;
+                const feedback = args?.feedback;
+                if (!input || !outcome) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "Missing required fields: input and outcome" }) }],
+                        isError: true,
+                    };
+                }
+                // Sanitize before transmission
+                const inputPreview = previewSanitization(input);
+                const feedbackPreview = feedback ? previewSanitization(feedback) : null;
+                if (inputPreview.wouldBlock || feedbackPreview?.wouldBlock) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: "Content contains restricted data that cannot be transmitted",
+                                    blockReason: inputPreview.blockReason || feedbackPreview?.blockReason,
+                                    hint: "Remove private keys, credentials, or other restricted data before observing.",
+                                }, null, 2)
+                            }],
+                        isError: true,
+                    };
+                }
+                try {
+                    const result = await callCedaAPI("/api/observations", "POST", {
+                        input: inputPreview.sanitized,
+                        outcome,
+                        feedback: feedbackPreview?.sanitized,
+                        source: "herald",
+                        org: HERALD_ORG,
+                        project: HERALD_PROJECT,
+                        user: HERALD_USER,
+                    });
+                    if (result.error) {
+                        // Buffer locally if cloud unavailable
+                        bufferInsight({
+                            insight: inputPreview.sanitized,
+                            session: `observation: ${outcome}`,
+                            feeling: outcome === "rejected" ? "stuck" : "success",
+                            method: "observe",
+                            type: "observation",
+                            topic: "observation",
+                            org: HERALD_ORG,
+                            project: HERALD_PROJECT,
+                            user: HERALD_USER,
+                        });
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        success: true,
+                                        mode: "local",
+                                        message: "Observation buffered locally (cloud unavailable)",
+                                        level: 0,
+                                        hint: "Use herald_sync to flush buffer when cloud recovers.",
+                                        buffered: true,
+                                    }, null, 2)
+                                }],
+                        };
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    mode: "cloud",
+                                    level: 0,
+                                    message: `Observation captured: "${input.substring(0, 80)}"`,
+                                    outcome,
+                                    observationId: result.observationId,
+                                    context: {
+                                        org: HERALD_ORG,
+                                        project: HERALD_PROJECT,
+                                    },
+                                    graduation: "Will auto-graduate to pattern when similar observations cluster (3+ needed)",
+                                    ...result,
+                                }, null, 2)
+                            }],
+                    };
+                }
+                catch {
+                    // Network error - buffer locally
+                    bufferInsight({
+                        insight: inputPreview.sanitized,
+                        session: `observation: ${outcome}`,
+                        feeling: outcome === "rejected" ? "stuck" : "success",
+                        method: "observe",
+                        type: "observation",
+                        topic: "observation",
+                        org: HERALD_ORG,
+                        project: HERALD_PROJECT,
+                        user: HERALD_USER,
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    mode: "local",
+                                    message: "Observation buffered locally (network error)",
+                                    level: 0,
+                                    hint: "Use herald_sync when cloud recovers.",
+                                    buffered: true,
+                                }, null, 2)
+                            }],
+                    };
+                }
+            }
             case "herald_patterns": {
-                // Query learned patterns with inheritance: user → project → company
+                // Query learned patterns with inheritance: user → project → org
                 // More specific patterns take precedence over broader ones
                 try {
                     // Helper to dedupe patterns by insight text (first occurrence wins)
@@ -2264,17 +2577,15 @@ Herald will:
                             return true;
                         }).map(item => ({ ...item, scope }));
                     };
-                    // CEDA-95: Cascade queries - use company param for backwards compat with deployed server
-                    // CEDA-102: User reflections now saved with level=1, so minLevel=1 is appropriate
-                    // But we also query without minLevel to catch level=0 reflections from before the fix
+                    // Level-gated cascade: user sees own (any level), project sees level>=2, org sees level>=3
                     const queries = [
-                        { scope: "user", url: `/api/herald/reflections?company=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=100` },
-                        { scope: "project", url: `/api/herald/reflections?company=${HERALD_ORG}&project=${HERALD_PROJECT}&limit=100` },
-                        { scope: "org", url: `/api/herald/reflections?company=${HERALD_ORG}&limit=100` },
+                        { scope: "user", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&user=${HERALD_USER}&limit=50` },
+                        { scope: "project", url: `/api/herald/reflections?org=${HERALD_ORG}&project=${HERALD_PROJECT}&minLevel=2&limit=50` },
+                        { scope: "org", url: `/api/herald/reflections?org=${HERALD_ORG}&minLevel=3&limit=50` },
                     ];
                     const patterns = [];
                     const antipatterns = [];
-                    // Query each level, dedupe as we go (user patterns win over project, project over company)
+                    // Query each level, dedupe as we go (user patterns win over project, project over org)
                     for (const { scope, url } of queries) {
                         try {
                             const result = await callCedaAPI(url);
@@ -2577,7 +2888,7 @@ Herald will:
                         insight,
                         scope,
                         topic,
-                        sourceCompany: HERALD_ORG,
+                        sourceOrg: HERALD_ORG,
                         sourceProject: HERALD_PROJECT,
                         sourceUser: HERALD_USER,
                         sourceVault: HERALD_VAULT || undefined,
@@ -2595,7 +2906,7 @@ Herald will:
                         };
                     }
                     const scopeDescription = {
-                        parent: "parent project/company",
+                        parent: "parent project/org",
                         siblings: "sibling projects",
                         all: "all contexts globally",
                     };
@@ -2837,7 +3148,7 @@ async function verifyWithCeda() {
             const ctx = result.context;
             VERIFIED_CONTEXT = {
                 verified: true,
-                org: (ctx.org || ctx.company),
+                org: (ctx.org || ctx.org),
                 project: ctx.project,
                 trust: ctx.trust,
                 tags: ctx.tags,
@@ -2890,6 +3201,10 @@ async function sendStartupHeartbeat() {
 async function runMCP() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Auto-refresh expired access token before verification
+    if (CEDA_API_TOKEN && isTokenExpired(CEDA_API_TOKEN) && CEDA_REFRESH_TOKEN) {
+        await refreshAccessToken();
+    }
     // CEDA-82: Verify trust with CEDA server before announcing
     // This may upgrade trust if user is registered
     await verifyWithCeda();