@iflow-mcp/jkheadley-instar 0.26.2

package/dist/threadline/CircuitBreaker.js

@@ -0,0 +1,238 @@
+/**
+ * CircuitBreaker — Per-agent circuit breaker for inter-agent communication.
+ *
+ * Part of Threadline Protocol Phase 5 (Section 7.9). Prevents cascading failures
+ * when a remote agent becomes unreliable.
+ *
+ * Circuit breaker rules:
+ * - 5 consecutive errors → circuit opens
+ * - Open circuit → all messages queued (not delivered), user notified
+ * - Auto-reset after 1 hour (transition to half-open, then closed on first success)
+ * - 3 circuit breaks in 24h → auto-downgrade trust to untrusted
+ * - Manual reset via user intervention at any time
+ *
+ * Storage: {stateDir}/threadline/circuit-breaker.json
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+/** Number of consecutive failures before circuit opens */
+const FAILURE_THRESHOLD = 5;
+/** Auto-reset timeout in milliseconds (1 hour) */
+const AUTO_RESET_MS = 60 * 60 * 1000;
+/** Window for counting activations (24 hours) */
+const ACTIVATION_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Number of activations in window that triggers auto-downgrade */
+const DOWNGRADE_ACTIVATION_THRESHOLD = 3;
+// ── Helpers ──────────────────────────────────────────────────────────
+function atomicWrite(filePath, data) {
+    const tmpPath = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, data);
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+function safeJsonParse(filePath, fallback) {
+    try {
+        if (!fs.existsSync(filePath))
+            return fallback;
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+export class CircuitBreaker {
+    threadlineDir;
+    filePath;
+    circuits;
+    trustManager;
+    nowFn;
+    constructor(options) {
+        this.threadlineDir = path.join(options.stateDir, 'threadline');
+        fs.mkdirSync(this.threadlineDir, { recursive: true });
+        this.filePath = path.join(this.threadlineDir, 'circuit-breaker.json');
+        this.trustManager = options.trustManager ?? null;
+        this.nowFn = options.nowFn ?? (() => Date.now());
+        this.circuits = this.loadCircuits();
+    }
+    // ── Success / Failure Recording ─────────────────────────────────
+    /**
+     * Record a successful interaction with an agent.
+     * If circuit is half-open, closes it.
+     */
+    recordSuccess(agentName) {
+        const circuit = this.getOrCreateCircuit(agentName);
+        circuit.consecutiveFailures = 0;
+        circuit.totalSuccesses++;
+        circuit.lastSuccess = new Date(this.nowFn()).toISOString();
+        if (circuit.state === 'half-open') {
+            circuit.state = 'closed';
+            circuit.resetAt = new Date(this.nowFn()).toISOString();
+        }
+        this.save();
+    }
+    /**
+     * Record a failed interaction with an agent.
+     * Opens circuit after FAILURE_THRESHOLD consecutive failures.
+     */
+    recordFailure(agentName) {
+        const circuit = this.getOrCreateCircuit(agentName);
+        circuit.consecutiveFailures++;
+        circuit.totalFailures++;
+        circuit.lastFailure = new Date(this.nowFn()).toISOString();
+        if (circuit.state === 'half-open') {
+            // Failure during half-open → reopen
+            this.openCircuit(circuit);
+        }
+        else if (circuit.state === 'closed' && circuit.consecutiveFailures >= FAILURE_THRESHOLD) {
+            this.openCircuit(circuit);
+        }
+        this.save();
+    }
+    // ── State Queries ───────────────────────────────────────────────
+    /**
+     * Check if circuit is open (or should auto-transition to half-open).
+     * Returns true if the circuit is open (messages should be queued).
+     */
+    isOpen(agentName) {
+        const circuit = this.circuits[agentName];
+        if (!circuit)
+            return false;
+        if (circuit.state === 'open') {
+            // Check if auto-reset period has elapsed
+            if (circuit.openedAt) {
+                const elapsed = this.nowFn() - new Date(circuit.openedAt).getTime();
+                if (elapsed >= AUTO_RESET_MS) {
+                    // Transition to half-open
+                    circuit.state = 'half-open';
+                    this.save();
+                    return false; // Half-open allows one attempt
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the current circuit state for an agent.
+     * Applies auto-reset logic before returning.
+     */
+    getState(agentName) {
+        const circuit = this.circuits[agentName];
+        if (!circuit)
+            return null;
+        // Apply auto-reset if needed
+        if (circuit.state === 'open' && circuit.openedAt) {
+            const elapsed = this.nowFn() - new Date(circuit.openedAt).getTime();
+            if (elapsed >= AUTO_RESET_MS) {
+                circuit.state = 'half-open';
+                this.save();
+            }
+        }
+        return { ...circuit };
+    }
+    /**
+     * Get all circuit states.
+     */
+    getAllStates() {
+        return Object.values(this.circuits).map(c => ({ ...c }));
+    }
+    // ── Manual Reset ────────────────────────────────────────────────
+    /**
+     * Manually reset a circuit (user intervention).
+     * Clears consecutive failures and closes the circuit.
+     */
+    reset(agentName) {
+        const circuit = this.circuits[agentName];
+        if (!circuit)
+            return false;
+        circuit.state = 'closed';
+        circuit.consecutiveFailures = 0;
+        circuit.resetAt = new Date(this.nowFn()).toISOString();
+        circuit.openedAt = undefined;
+        this.save();
+        return true;
+    }
+    // ── Auto-Downgrade Check ────────────────────────────────────────
+    /**
+     * Check if 3 activations in 24h should trigger trust auto-downgrade.
+     * Called internally when a circuit opens.
+     * Returns true if downgrade was triggered.
+     */
+    checkAutoDowngrade(agentName) {
+        const circuit = this.circuits[agentName];
+        if (!circuit)
+            return false;
+        // Clean up old activations outside the window
+        const windowStart = this.nowFn() - ACTIVATION_WINDOW_MS;
+        circuit.activationsInWindow = circuit.activationsInWindow.filter(a => new Date(a.timestamp).getTime() > windowStart);
+        if (circuit.activationsInWindow.length >= DOWNGRADE_ACTIVATION_THRESHOLD) {
+            if (this.trustManager) {
+                this.trustManager.autoDowngrade(agentName, `Circuit breaker activated ${circuit.activationsInWindow.length} times in 24 hours`);
+                return true;
+            }
+        }
+        return false;
+    }
+    // ── Persistence ─────────────────────────────────────────────────
+    /**
+     * Force reload from disk.
+     */
+    reload() {
+        this.circuits = this.loadCircuits();
+    }
+    // ── Private ─────────────────────────────────────────────────────
+    getOrCreateCircuit(agentName) {
+        if (!this.circuits[agentName]) {
+            this.circuits[agentName] = {
+                agent: agentName,
+                state: 'closed',
+                consecutiveFailures: 0,
+                totalFailures: 0,
+                totalSuccesses: 0,
+                activationCount: 0,
+                activationsInWindow: [],
+            };
+        }
+        return this.circuits[agentName];
+    }
+    openCircuit(circuit) {
+        circuit.state = 'open';
+        circuit.openedAt = new Date(this.nowFn()).toISOString();
+        circuit.activationCount++;
+        circuit.activationsInWindow.push({
+            timestamp: new Date(this.nowFn()).toISOString(),
+        });
+        this.save();
+        // Check for auto-downgrade after opening
+        this.checkAutoDowngrade(circuit.agent);
+    }
+    loadCircuits() {
+        const data = safeJsonParse(this.filePath, {
+            circuits: {},
+            updatedAt: '',
+        });
+        return data.circuits;
+    }
+    save() {
+        try {
+            const data = {
+                circuits: this.circuits,
+                updatedAt: new Date(this.nowFn()).toISOString(),
+            };
+            atomicWrite(this.filePath, JSON.stringify(data, null, 2));
+        }
+        catch {
+            // Save failure should not break circuit evaluation
+        }
+    }
+}
+//# sourceMappingURL=CircuitBreaker.js.map

package/dist/threadline/CircuitBreaker.js.map

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

package/dist/threadline/ComputeMeter.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ComputeMeter — Per-agent and global compute budget tracking.
+ *
+ * Part of Threadline Protocol Phase 6A (A2A Gateway). Prevents cost overrun
+ * from inbound A2A messages by enforcing hourly/daily token limits per agent
+ * (tied to trust level) and a global daily cap across all network agents.
+ *
+ * Rolling windows: hourly resets when the hour changes, daily resets at midnight UTC.
+ *
+ * Storage: {stateDir}/threadline/compute-meters.json
+ */
+export type TrustLevel = 'untrusted' | 'verified' | 'trusted' | 'autonomous';
+export interface ComputeBudget {
+    hourlyTokenLimit: number;
+    dailyTokenLimit: number;
+    maxConcurrentSessions: number;
+}
+export interface AgentMeterState {
+    agentIdentity: string;
+    hourlyTokens: number;
+    dailyTokens: number;
+    activeSessions: number;
+    hourWindowStart: string;
+    dayWindowStart: string;
+    lastUpdated: string;
+}
+export interface GlobalMeterState {
+    dailyTokens: number;
+    dayWindowStart: string;
+    lastUpdated: string;
+}
+export interface ComputeMeterConfig {
+    stateDir: string;
+    globalDailyCap?: number;
+    budgetOverrides?: Partial<Record<TrustLevel, Partial<ComputeBudget>>>;
+}
+export interface MeterCheckResult {
+    allowed: boolean;
+    reason?: string;
+    remaining: {
+        hourlyTokens: number;
+        dailyTokens: number;
+        globalDailyTokens: number;
+        sessions: number;
+    };
+    retryAfterSeconds?: number;
+}
+export declare class ComputeMeter {
+    private readonly threadlineDir;
+    private readonly filePath;
+    private readonly globalDailyCap;
+    private readonly budgetOverrides;
+    private agents;
+    private global;
+    constructor(config: ComputeMeterConfig);
+    /**
+     * Get the compute budget for a given trust level.
+     * Applies any configured overrides on top of the default tier.
+     */
+    getBudget(trustLevel: TrustLevel): ComputeBudget;
+    /**
+     * Check if a request with the given token count would be allowed.
+     * Does NOT consume tokens — use `record()` for that.
+     */
+    check(agentIdentity: string, trustLevel: TrustLevel, tokenCount: number): MeterCheckResult;
+    /**
+     * Record token consumption for an agent.
+     * Returns the check result after recording. Fails if budget would be exceeded.
+     */
+    record(agentIdentity: string, trustLevel: TrustLevel, tokenCount: number): MeterCheckResult;
+    /**
+     * Increment the active session count for an agent.
+     * Returns false if the agent is already at the maximum for their trust level.
+     */
+    incrementSessions(agentIdentity: string, trustLevel: TrustLevel): boolean;
+    /**
+     * Decrement the active session count for an agent.
+     * Clamps to zero — never goes negative.
+     */
+    decrementSessions(agentIdentity: string): void;
+    /**
+     * Get current meter state for a specific agent, or null if unknown.
+     */
+    getAgentState(agentIdentity: string): AgentMeterState | null;
+    /**
+     * Get the global meter state.
+     */
+    getGlobalState(): GlobalMeterState;
+    /**
+     * Reset meters. If agentIdentity is provided, resets only that agent.
+     * If omitted, resets all agents and the global counter.
+     */
+    reset(agentIdentity?: string): void;
+    /**
+     * Persist current meter state to disk.
+     * Uses atomic write (tmp file + rename) to prevent corruption.
+     */
+    persist(): void;
+    /**
+     * Reload meter state from disk.
+     * Rolls any stale windows after loading.
+     */
+    reload(): void;
+    private getOrCreateAgent;
+    /**
+     * Roll agent windows if the hour or day has changed since window start.
+     */
+    private rollWindows;
+    /**
+     * Roll the global daily window if the UTC date has changed.
+     */
+    private rollGlobalWindow;
+}
+//# sourceMappingURL=ComputeMeter.d.ts.map

package/dist/threadline/ComputeMeter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComputeMeter.d.ts","sourceRoot":"","sources":["../../src/threadline/ComputeMeter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AA4DD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsD;IAEtF,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,kBAAkB;IAoBtC;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa;IAahD;;;OAGG;IACH,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB;IAyE1F;;;OAGG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB;IAsB3F;;;OAGG;IACH,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO;IAczE;;;OAGG;IACH,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAU9C;;OAEG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAU5D;;OAEG;IACH,cAAc,IAAI,gBAAgB;IAQlC;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAgBnC;;;OAGG;IACH,OAAO,IAAI,IAAI;IAiBf;;;OAGG;IACH,MAAM,IAAI,IAAI;IA6Bd,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAOzB"}