@iflow-mcp/jkheadley-instar 0.26.2

package/dist/monitoring/CredentialProvider.js

@@ -0,0 +1,196 @@
+/**
+ * CredentialProvider — cross-platform abstraction for Claude Code OAuth credential access.
+ *
+ * Implementations:
+ * - KeychainCredentialProvider: macOS Keychain (os-encrypted, production-proven)
+ * - ClaudeConfigCredentialProvider: File-based fallback (all platforms, 0600 permissions)
+ *
+ * Part of the Instar Quota Migration spec (Phase 1).
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// ── Token Redaction ─────────────────────────────────────────────────
+/**
+ * Redact a token for safe logging. Shows first 4 chars only.
+ * Returns "[TOKEN:abc1****]" format.
+ */
+export function redactToken(token) {
+    if (!token || token.length < 4)
+        return '[TOKEN:****]';
+    return `[TOKEN:${token.slice(0, 4)}****]`;
+}
+/**
+ * Redact an email for safe logging.
+ * Returns "[EMAIL:j***@***.com]" format.
+ */
+export function redactEmail(email) {
+    if (!email || !email.includes('@'))
+        return '[EMAIL:****]';
+    const [local, domain] = email.split('@');
+    const domainParts = domain.split('.');
+    const tld = domainParts[domainParts.length - 1];
+    return `[EMAIL:${local[0]}***@***.${tld}]`;
+}
+// ── Keychain Provider (macOS) ───────────────────────────────────────
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+export class KeychainCredentialProvider {
+    platform = 'darwin';
+    securityLevel = 'os-encrypted';
+    keychainAccount;
+    constructor() {
+        this.keychainAccount = os.userInfo().username;
+    }
+    async readCredentials() {
+        try {
+            const result = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-w'], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+            const data = JSON.parse(result.trim());
+            const oauth = data.claudeAiOauth;
+            if (!oauth?.accessToken)
+                return null;
+            return {
+                accessToken: oauth.accessToken,
+                expiresAt: oauth.expiresAt ?? 0,
+                refreshToken: oauth.refreshToken,
+                email: oauth.email,
+            };
+        }
+        catch {
+            // @silent-fallback-ok — Keychain may not have Claude credentials; null is expected
+            return null;
+        }
+    }
+    async writeCredentials(creds) {
+        // Read existing data to preserve non-credential fields
+        let existingData = {};
+        try {
+            const result = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-w'], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+            existingData = JSON.parse(result.trim());
+        }
+        catch {
+            // @silent-fallback-ok — no existing Keychain entry; start fresh
+        }
+        const newData = {
+            ...existingData,
+            claudeAiOauth: {
+                ...(existingData.claudeAiOauth || {}),
+                accessToken: creds.accessToken,
+                expiresAt: creds.expiresAt,
+                ...(creds.refreshToken ? { refreshToken: creds.refreshToken } : {}),
+                ...(creds.email ? { email: creds.email } : {}),
+            },
+        };
+        const jsonStr = JSON.stringify(newData);
+        const hexStr = Buffer.from(jsonStr).toString('hex');
+        execFileSync('security', ['-i'], {
+            input: `add-generic-password -U -a "${this.keychainAccount}" -s "${KEYCHAIN_SERVICE}" -X "${hexStr}"\n`,
+            encoding: 'utf-8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    async deleteCredentials(_email) {
+        try {
+            execFileSync('security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            // @silent-fallback-ok — Keychain entry already deleted or never existed
+        }
+    }
+}
+// ── Claude Config File Provider (All Platforms) ─────────────────────
+/**
+ * Reads credentials from Claude Code's local config files.
+ * Falls back to file-based storage with enforced 0600 permissions.
+ *
+ * Config path: ~/.claude/ (standard Claude Code config directory)
+ */
+export class ClaudeConfigCredentialProvider {
+    platform = process.platform;
+    securityLevel = 'file-permission-only';
+    configDir;
+    constructor(configDir) {
+        this.configDir = configDir || path.join(os.homedir(), '.claude');
+    }
+    async readCredentials() {
+        try {
+            // Try the credentials file first
+            const credPath = path.join(this.configDir, 'credentials.json');
+            if (!fs.existsSync(credPath)) {
+                // Try the legacy .credentials file
+                const legacyPath = path.join(this.configDir, '.credentials');
+                if (!fs.existsSync(legacyPath))
+                    return null;
+                return this.parseCredentialFile(legacyPath);
+            }
+            return this.parseCredentialFile(credPath);
+        }
+        catch {
+            // @silent-fallback-ok — credential file may be missing or malformed; null is expected
+            return null;
+        }
+    }
+    async writeCredentials(creds) {
+        // Ensure directory exists with proper permissions
+        if (!fs.existsSync(this.configDir)) {
+            fs.mkdirSync(this.configDir, { recursive: true, mode: 0o700 });
+        }
+        const credPath = path.join(this.configDir, 'credentials.json');
+        const data = {
+            accessToken: creds.accessToken,
+            expiresAt: creds.expiresAt,
+            ...(creds.refreshToken ? { refreshToken: creds.refreshToken } : {}),
+            ...(creds.email ? { email: creds.email } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(credPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+    }
+    async deleteCredentials(_email) {
+        const credPath = path.join(this.configDir, 'credentials.json');
+        try {
+            if (fs.existsSync(credPath)) {
+                fs.unlinkSync(credPath);
+            }
+        }
+        catch {
+            // @silent-fallback-ok — file already deleted or never existed
+        }
+    }
+    parseCredentialFile(filePath) {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Handle multiple possible formats
+        const token = data.accessToken || data.claudeAiOauth?.accessToken;
+        if (!token)
+            return null;
+        return {
+            accessToken: token,
+            expiresAt: data.expiresAt || data.claudeAiOauth?.expiresAt || 0,
+            refreshToken: data.refreshToken || data.claudeAiOauth?.refreshToken,
+            email: data.email || data.claudeAiOauth?.email,
+        };
+    }
+}
+// ── Factory ─────────────────────────────────────────────────────────
+/**
+ * Create the best available credential provider for the current platform.
+ *
+ * Priority:
+ * 1. macOS: Keychain (os-encrypted)
+ * 2. All platforms: File-based (~/.claude/) with 0600 permissions
+ *
+ * Note: keytar support (Linux libsecret, Windows Credential Manager)
+ * is planned but not yet implemented. When added, it will slot between
+ * Keychain and file-based in the priority chain.
+ */
+export function createDefaultProvider() {
+    if (process.platform === 'darwin') {
+        return new KeychainCredentialProvider();
+    }
+    // File-based fallback — log security warning
+    console.warn('[CredentialProvider] Using file-based credential storage (less secure). ' +
+        'Consider installing keytar for OS-native encrypted storage.');
+    return new ClaudeConfigCredentialProvider();
+}
+//# sourceMappingURL=CredentialProvider.js.map

package/dist/monitoring/CredentialProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialProvider.js","sourceRoot":"","sources":["../../src/monitoring/CredentialProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAmC7B,uEAAuE;AAEvE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC;IACtD,OAAO,UAAU,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,cAAc,CAAC;IAC1D,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAChD,OAAO,UAAU,KAAK,CAAC,CAAC,CAAC,WAAW,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED,uEAAuE;AAEvE,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAEnD,MAAM,OAAO,0BAA0B;IAC5B,QAAQ,GAAG,QAAQ,CAAC;IACpB,aAAa,GAAkB,cAAc,CAAC;IAC/C,eAAe,CAAS;IAEhC;QACE,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CACzB,UAAU,EACV,CAAC,uBAAuB,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,CAAC,EACvD,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CACvE,CAAC;YACF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACvC,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC;YACjC,IAAI,CAAC,KAAK,EAAE,WAAW;gBAAE,OAAO,IAAI,CAAC;YAErC,OAAO;gBACL,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,CAAC;gBAC/B,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;aACnB,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,mFAAmF;YACnF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAAwB;QAC7C,uDAAuD;QACvD,IAAI,YAAY,GAA4B,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CACzB,UAAU,EACV,CAAC,uBAAuB,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,CAAC,EACvD,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CACvE,CAAC;YACF,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;QAED,MAAM,OAAO,GAAG;YACd,GAAG,YAAY;YACf,aAAa,EAAE;gBACb,GAAG,CAAC,YAAY,CAAC,aAAwC,IAAI,EAAE,CAAC;gBAChE,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/C;SACF,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpD,YAAY,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE;YAC/B,KAAK,EAAE,+BAA+B,IAAI,CAAC,eAAe,SAAS,gBAAgB,SAAS,MAAM,KAAK;YACvG,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,MAAc;QACpC,IAAI,CAAC;YACH,YAAY,CACV,UAAU,EACV,CAAC,yBAAyB,EAAE,IAAI,EAAE,gBAAgB,CAAC,EACnD,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CACvE,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC;CACF;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,OAAO,8BAA8B;IAChC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC5B,aAAa,GAAkB,sBAAsB,CAAC;IACvD,SAAS,CAAS;IAE1B,YAAY,SAAkB;QAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,IAAI,CAAC;YACH,iCAAiC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;YAC/D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,mCAAmC;gBACnC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;gBAC7D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;oBAAE,OAAO,IAAI,CAAC;gBAC5C,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;YAC9C,CAAC;YACD,OAAO,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,sFAAsF;YACtF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAAwB;QAC7C,kDAAkD;QAClD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG;YACX,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,MAAc;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;QAC/D,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;QAChE,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,QAAgB;QAC1C,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE7B,mCAAmC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC;QAClE,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,OAAO;YACL,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,aAAa,EAAE,SAAS,IAAI,CAAC;YAC/D,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,aAAa,EAAE,YAAY;YACnE,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,aAAa,EAAE,KAAK;SAC/C,CAAC;IACJ,CAAC;CACF;AAED,uEAAuE;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,IAAI,0BAA0B,EAAE,CAAC;IAC1C,CAAC;IAED,6CAA6C;IAC7C,OAAO,CAAC,IAAI,CACV,0EAA0E;QAC1E,6DAA6D,CAC9D,CAAC;IACF,OAAO,IAAI,8BAA8B,EAAE,CAAC;AAC9C,CAAC"}

package/dist/monitoring/DegradationReporter.d.ts

@@ -0,0 +1,123 @@
+/**
+ * DegradationReporter — makes fallback activations LOUD, not silent.
+ *
+ * When a feature falls back to a secondary path, that's a bug. The fallback
+ * keeps the system running, but someone needs to know the primary path failed.
+ * Silent fallbacks are almost as bad as silent failures — the user gets a
+ * degraded experience and nobody knows about it.
+ *
+ * This reporter:
+ *   1. Logs visibly to console with [DEGRADATION] prefix
+ *   2. Queues reports until downstream systems (feedback, telegram) are ready
+ *   3. Drains to FeedbackManager (files bug report back to Instar)
+ *   4. Sends Telegram alert to agent-attention topic
+ *   5. Stores all degradations in a structured file for health checks
+ *
+ * Usage:
+ *   const reporter = DegradationReporter.getInstance();
+ *   reporter.report({
+ *     feature: 'TopicMemory',
+ *     primary: 'SQLite-backed context with summaries',
+ *     fallback: 'JSONL-based last 20 messages',
+ *     reason: 'better-sqlite3 failed to load',
+ *     impact: 'Sessions start without conversation summaries',
+ *   });
+ *
+ * Born from the insight: "Fallbacks should only and always be associated
+ * with a bug report back to Instar." — Justin, 2026-02-25
+ */
+export interface DegradationEvent {
+    /** Which feature degraded */
+    feature: string;
+    /** What the primary path does */
+    primary: string;
+    /** What the fallback does (the degraded path) */
+    fallback: string;
+    /** Why the primary path failed */
+    reason: string;
+    /** User-facing impact of the degradation */
+    impact: string;
+    /** When the degradation was detected */
+    timestamp: string;
+    /** Whether this was reported to the feedback system */
+    reported: boolean;
+    /** Whether this was sent as a Telegram alert */
+    alerted: boolean;
+}
+type TelegramSender = (topicId: number, text: string) => Promise<unknown>;
+type FeedbackSubmitter = (item: {
+    type: 'bug';
+    title: string;
+    description: string;
+    agentName: string;
+    instarVersion: string;
+    nodeVersion: string;
+    os: string;
+    context?: string;
+}) => Promise<unknown>;
+export declare class DegradationReporter {
+    private static instance;
+    private events;
+    private stateDir;
+    private agentName;
+    private instarVersion;
+    private feedbackSubmitter;
+    private telegramSender;
+    private alertTopicId;
+    private lastAlertTime;
+    private constructor();
+    static getInstance(): DegradationReporter;
+    /**
+     * Reset singleton for testing.
+     */
+    static resetForTesting(): void;
+    /**
+     * Configure with agent identity and storage.
+     * Called during server startup before features initialize.
+     */
+    configure(opts: {
+        stateDir: string;
+        agentName: string;
+        instarVersion: string;
+    }): void;
+    /**
+     * Connect downstream reporting systems.
+     * Called once the server is fully started and feedback/telegram are available.
+     * Drains any queued events that were reported before downstream was ready.
+     */
+    connectDownstream(opts: {
+        feedbackSubmitter?: FeedbackSubmitter;
+        telegramSender?: TelegramSender;
+        alertTopicId?: number | null;
+    }): void;
+    /**
+     * Report a degradation event.
+     *
+     * This is the primary API. Call this whenever a fallback activates.
+     * If downstream systems aren't ready yet, the event is queued.
+     */
+    report(event: Omit<DegradationEvent, 'timestamp' | 'reported' | 'alerted'>): void;
+    /**
+     * Get all degradation events (for health check API).
+     */
+    getEvents(): DegradationEvent[];
+    /**
+     * Generate a human-readable narrative for a degradation event.
+     * Used for Telegram alerts and health endpoint summaries.
+     * No technical identifiers, no structured fields — just plain language.
+     */
+    static narrativeFor(event: DegradationEvent): string;
+    /**
+     * Get unreported events (for monitoring).
+     */
+    getUnreportedEvents(): DegradationEvent[];
+    /**
+     * Check if any degradations have occurred.
+     */
+    hasDegradations(): boolean;
+    private reportEvent;
+    private drainQueue;
+    private persistToDisk;
+}
+export {};
+//# sourceMappingURL=DegradationReporter.d.ts.map

package/dist/monitoring/DegradationReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DegradationReporter.d.ts","sourceRoot":"","sources":["../../src/monitoring/DegradationReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1E,KAAK,iBAAiB,GAAG,CAAC,IAAI,EAAE;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAKvB,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoC;IAE3D,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,aAAa,CAAmB;IAGxC,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,YAAY,CAAuB;IAG3C,OAAO,CAAC,aAAa,CAAkC;IAEvD,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,mBAAmB;IAOzC;;OAEG;IACH,MAAM,CAAC,eAAe,IAAI,IAAI;IAI9B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI;IAMR;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE;QACtB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;QACtC,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,GAAG,IAAI;IASR;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC,GAAG,IAAI;IAuBjF;;OAEG;IACH,SAAS,IAAI,gBAAgB,EAAE;IAI/B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM;IA0BpD;;OAEG;IACH,mBAAmB,IAAI,gBAAgB,EAAE;IAIzC;;OAEG;IACH,eAAe,IAAI,OAAO;YAMZ,WAAW;IA8DzB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,aAAa;CA8BtB"}

package/dist/monitoring/DegradationReporter.js

@@ -0,0 +1,241 @@
+/**
+ * DegradationReporter — makes fallback activations LOUD, not silent.
+ *
+ * When a feature falls back to a secondary path, that's a bug. The fallback
+ * keeps the system running, but someone needs to know the primary path failed.
+ * Silent fallbacks are almost as bad as silent failures — the user gets a
+ * degraded experience and nobody knows about it.
+ *
+ * This reporter:
+ *   1. Logs visibly to console with [DEGRADATION] prefix
+ *   2. Queues reports until downstream systems (feedback, telegram) are ready
+ *   3. Drains to FeedbackManager (files bug report back to Instar)
+ *   4. Sends Telegram alert to agent-attention topic
+ *   5. Stores all degradations in a structured file for health checks
+ *
+ * Usage:
+ *   const reporter = DegradationReporter.getInstance();
+ *   reporter.report({
+ *     feature: 'TopicMemory',
+ *     primary: 'SQLite-backed context with summaries',
+ *     fallback: 'JSONL-based last 20 messages',
+ *     reason: 'better-sqlite3 failed to load',
+ *     impact: 'Sessions start without conversation summaries',
+ *   });
+ *
+ * Born from the insight: "Fallbacks should only and always be associated
+ * with a bug report back to Instar." — Justin, 2026-02-25
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+// How long before the same feature can trigger another Telegram alert (ms)
+const ALERT_COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
+export class DegradationReporter {
+    static instance = null;
+    events = [];
+    stateDir = null;
+    agentName = 'unknown';
+    instarVersion = '0.0.0';
+    // Downstream systems — connected once the server is fully up
+    feedbackSubmitter = null;
+    telegramSender = null;
+    alertTopicId = null;
+    // Dedup: track last alert time per feature to avoid spamming Telegram
+    lastAlertTime = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!DegradationReporter.instance) {
+            DegradationReporter.instance = new DegradationReporter();
+        }
+        return DegradationReporter.instance;
+    }
+    /**
+     * Reset singleton for testing.
+     */
+    static resetForTesting() {
+        DegradationReporter.instance = null;
+    }
+    /**
+     * Configure with agent identity and storage.
+     * Called during server startup before features initialize.
+     */
+    configure(opts) {
+        this.stateDir = opts.stateDir;
+        this.agentName = opts.agentName;
+        this.instarVersion = opts.instarVersion;
+    }
+    /**
+     * Connect downstream reporting systems.
+     * Called once the server is fully started and feedback/telegram are available.
+     * Drains any queued events that were reported before downstream was ready.
+     */
+    connectDownstream(opts) {
+        this.feedbackSubmitter = opts.feedbackSubmitter ?? null;
+        this.telegramSender = opts.telegramSender ?? null;
+        this.alertTopicId = opts.alertTopicId ?? null;
+        // Drain queued events that weren't reported yet
+        this.drainQueue();
+    }
+    /**
+     * Report a degradation event.
+     *
+     * This is the primary API. Call this whenever a fallback activates.
+     * If downstream systems aren't ready yet, the event is queued.
+     */
+    report(event) {
+        const full = {
+            ...event,
+            timestamp: new Date().toISOString(),
+            reported: false,
+            alerted: false,
+        };
+        // Always log to console — never silent
+        console.warn(`[DEGRADATION] ${event.feature}: ${event.reason}\n` +
+            `  Primary: ${event.primary}\n` +
+            `  Fallback: ${event.fallback}\n` +
+            `  Impact: ${event.impact}`);
+        this.events.push(full);
+        this.persistToDisk(full);
+        // Try to report immediately if downstream is connected
+        this.reportEvent(full);
+    }
+    /**
+     * Get all degradation events (for health check API).
+     */
+    getEvents() {
+        return [...this.events];
+    }
+    /**
+     * Generate a human-readable narrative for a degradation event.
+     * Used for Telegram alerts and health endpoint summaries.
+     * No technical identifiers, no structured fields — just plain language.
+     */
+    static narrativeFor(event) {
+        const impact = event.impact.replace(/\.$/, '');
+        const fallbackLower = event.fallback.toLowerCase();
+        // Detect failure-state fallbacks (no real alternative, just broken)
+        // These describe what ISN'T working, not what IS being used instead
+        const isFailureState = /^no |unavailable|never |lost|undiagnosed|unreachable|not running|not delivered|cannot|won't/i.test(fallbackLower)
+            || /goes undiagnosed|left halted|in memory only|only in memory|never delivered/i.test(fallbackLower);
+        if (isFailureState) {
+            return `${impact}. I'll keep trying, but this may need a restart to fully resolve.`;
+        }
+        // Positive fallback — describe the backup approach being used
+        // Strip prefixes like "Falling back to", "Message only in", etc.
+        let fallback = event.fallback
+            .replace(/^Falling back to /i, '')
+            .replace(/^Message only in /i, 'the ')
+            .replace(/\.$/, '');
+        // Strip parenthetical caveats — the user doesn't need "(no search, no summary updates)"
+        fallback = fallback.replace(/\s*\([^)]*\)\s*/g, ' ').trim();
+        return `${impact}. Using ${fallback} in the meantime — everything else is working fine.`;
+    }
+    /**
+     * Get unreported events (for monitoring).
+     */
+    getUnreportedEvents() {
+        return this.events.filter(e => !e.reported);
+    }
+    /**
+     * Check if any degradations have occurred.
+     */
+    hasDegradations() {
+        return this.events.length > 0;
+    }
+    // ── Internal ──────────────────────────────────────────────
+    async reportEvent(event) {
+        // Submit to feedback system
+        if (this.feedbackSubmitter && !event.reported) {
+            try {
+                await this.feedbackSubmitter({
+                    type: 'bug',
+                    title: `[DEGRADATION] ${event.feature}: ${event.reason}`,
+                    description: [
+                        `A feature fallback was activated, indicating the primary path is broken.`,
+                        ``,
+                        `**Feature**: ${event.feature}`,
+                        `**Primary path**: ${event.primary}`,
+                        `**Fallback used**: ${event.fallback}`,
+                        `**Reason**: ${event.reason}`,
+                        `**Impact**: ${event.impact}`,
+                        `**Timestamp**: ${event.timestamp}`,
+                    ].join('\n'),
+                    agentName: this.agentName,
+                    instarVersion: this.instarVersion,
+                    nodeVersion: process.version,
+                    os: `${os.platform()} ${os.release()}`,
+                    context: JSON.stringify({
+                        feature: event.feature,
+                        reason: event.reason,
+                        nodeArch: process.arch,
+                        nodeVersion: process.version,
+                    }),
+                });
+                event.reported = true;
+            }
+            catch (err) {
+                // @silent-fallback-ok — self-referential (cannot report own failures)
+                // Don't fail on reporting failures — the console log is the safety net
+                console.error(`[DEGRADATION] Failed to submit feedback: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        // Send Telegram alert (with per-feature cooldown to avoid spam)
+        if (this.telegramSender && this.alertTopicId && !event.alerted) {
+            const lastAlert = this.lastAlertTime.get(event.feature) ?? 0;
+            const now = Date.now();
+            if (now - lastAlert >= ALERT_COOLDOWN_MS) {
+                try {
+                    await this.telegramSender(this.alertTopicId, DegradationReporter.narrativeFor(event));
+                    event.alerted = true;
+                    this.lastAlertTime.set(event.feature, now);
+                }
+                catch {
+                    // Don't fail on alerting failures
+                }
+            }
+            else {
+                // Within cooldown — suppress the alert but mark as handled
+                event.alerted = true;
+            }
+        }
+        // Update persisted state
+        this.persistToDisk(event);
+    }
+    drainQueue() {
+        for (const event of this.events) {
+            if (!event.reported || !event.alerted) {
+                this.reportEvent(event);
+            }
+        }
+    }
+    persistToDisk(event) {
+        if (!this.stateDir)
+            return;
+        try {
+            const filePath = path.join(this.stateDir, 'degradations.json');
+            let existing = [];
+            try {
+                existing = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            }
+            catch { /* first write */ }
+            // Update or append
+            const idx = existing.findIndex(e => e.feature === event.feature && e.timestamp === event.timestamp);
+            if (idx >= 0) {
+                existing[idx] = event;
+            }
+            else {
+                existing.push(event);
+            }
+            // Keep only last 100 events
+            if (existing.length > 100) {
+                existing = existing.slice(-100);
+            }
+            fs.writeFileSync(filePath, JSON.stringify(existing, null, 2));
+        }
+        catch {
+            // Disk persistence is best-effort
+        }
+    }
+}
+//# sourceMappingURL=DegradationReporter.js.map

package/dist/monitoring/DegradationReporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DegradationReporter.js","sourceRoot":"","sources":["../../src/monitoring/DegradationReporter.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/FeedbackAnomalyDetector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Feedback Anomaly Detector — in-memory sliding window anomaly detection
+ * for feedback submissions.
+ *
+ * Detects:
+ *   - Rate bursts: Too many submissions per agent per hour
+ *   - Rapid fire: Submissions too close together from the same agent
+ *   - Daily limits: Too many submissions per agent per day
+ *
+ * Uses agent pseudonyms for tracking (privacy-preserving).
+ * All state is in-memory — resets on server restart.
+ */
+export interface AnomalyDetectorConfig {
+    /** Max submissions per agent per hour (default: 20) */
+    maxPerAgentPerHour?: number;
+    /** Max submissions per agent per day (default: 50) */
+    maxPerAgentPerDay?: number;
+    /** Min time between submissions from same agent in ms (default: 5000) */
+    minIntervalMs?: number;
+}
+export interface AnomalyCheckResult {
+    allowed: boolean;
+    reason?: string;
+    anomalyType?: 'rate_burst' | 'rapid_fire' | 'daily_limit';
+}
+export declare class FeedbackAnomalyDetector {
+    private submissions;
+    private config;
+    constructor(config?: AnomalyDetectorConfig);
+    /**
+     * Check whether a submission from the given agent pseudonym should be allowed.
+     */
+    check(agentPseudonym: string): AnomalyCheckResult;
+    /**
+     * Record a submission timestamp for the given agent pseudonym.
+     * Call this AFTER a successful submission.
+     */
+    recordSubmission(agentPseudonym: string): void;
+    /**
+     * Get current tracking stats.
+     */
+    getStats(): {
+        totalTracked: number;
+        flaggedAgents: string[];
+    };
+    /**
+     * Remove timestamps older than 24 hours to prevent unbounded memory growth.
+     */
+    private cleanup;
+}
+//# sourceMappingURL=FeedbackAnomalyDetector.d.ts.map

package/dist/monitoring/FeedbackAnomalyDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeedbackAnomalyDetector.d.ts","sourceRoot":"","sources":["../../src/monitoring/FeedbackAnomalyDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;CAC3D;AAKD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,MAAM,CAAkC;gBAEpC,MAAM,CAAC,EAAE,qBAAqB;IAc1C;;OAEG;IACH,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,kBAAkB;IA8CjD;;;OAGG;IACH,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAS9C;;OAEG;IACH,QAAQ,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE;IAmB7D;;OAEG;IACH,OAAO,CAAC,OAAO;CAWhB"}