@bookedsolid/rea 0.1.0

package/dist/config/tier-map.js

@@ -0,0 +1,108 @@
+import { Tier } from '../policy/types.js';
+/** Numeric severity for tier comparison — higher = more dangerous. */
+const TIER_SEVERITY = {
+    [Tier.Read]: 0,
+    [Tier.Write]: 1,
+    [Tier.Destructive]: 2,
+};
+/**
+ * Static tier classifications for known tool patterns.
+ * Tools not in this map default to Tier.Write (safe default).
+ */
+const STATIC_TIER_MAP = {
+    // Read-tier tools (safe, no side effects)
+    get_messages: Tier.Read,
+    get_channel: Tier.Read,
+    get_guild: Tier.Read,
+    get_member: Tier.Read,
+    get_webhook: Tier.Read,
+    list_channels: Tier.Read,
+    list_guilds: Tier.Read,
+    list_members: Tier.Read,
+    list_roles: Tier.Read,
+    list_threads: Tier.Read,
+    list_webhooks: Tier.Read,
+    list_projects: Tier.Read,
+    search_messages: Tier.Read,
+    query_audit_log: Tier.Read,
+    health_check: Tier.Read,
+    // Write-tier tools (create or modify)
+    send_message: Tier.Write,
+    send_embed: Tier.Write,
+    edit_message: Tier.Write,
+    add_reaction: Tier.Write,
+    create_thread: Tier.Write,
+    create_channel: Tier.Write,
+    create_role: Tier.Write,
+    create_invite: Tier.Write,
+    create_webhook: Tier.Write,
+    execute_webhook: Tier.Write,
+    edit_channel: Tier.Write,
+    edit_role: Tier.Write,
+    edit_webhook: Tier.Write,
+    set_slowmode: Tier.Write,
+    set_permissions: Tier.Write,
+    assign_role: Tier.Write,
+    move_channel: Tier.Write,
+    archive_thread: Tier.Write,
+    timeout_member: Tier.Write,
+    // Destructive-tier tools (irreversible or high-impact)
+    delete_message: Tier.Destructive,
+    delete_channel: Tier.Destructive,
+    delete_role: Tier.Destructive,
+    delete_webhook: Tier.Destructive,
+    purge_messages: Tier.Destructive,
+    ban_member: Tier.Destructive,
+    unban_member: Tier.Destructive,
+    kick_member: Tier.Destructive,
+};
+/**
+ * Derive the base tier for a tool using the static map and naming conventions.
+ * This is the "floor" — overrides cannot go below this.
+ */
+function deriveBaseTier(baseName) {
+    // Check static map first
+    if (STATIC_TIER_MAP[baseName]) {
+        return STATIC_TIER_MAP[baseName];
+    }
+    // Convention-based classification for tools not in the static map.
+    // This allows non-Discord downstream servers to get sensible defaults.
+    if (/^(get_|list_|search_|query_|read_|fetch_|check_|health_|describe_|show_|count_)/.test(baseName)) {
+        return Tier.Read;
+    }
+    if (/^(delete_|drop_|purge_|remove_|destroy_|ban_|kick_|revoke_|truncate_)/.test(baseName)) {
+        return Tier.Destructive;
+    }
+    // Default: Write (fail-safe — requires at least L1)
+    return Tier.Write;
+}
+/**
+ * Classify a tool by its tier. Checks gateway config overrides first,
+ * then static map, then naming conventions, then defaults to Write.
+ */
+export function classifyTool(toolName, serverName, gatewayConfig) {
+    // Strip server prefix for base lookup (e.g., "discord-ops__send_message" -> "send_message")
+    const baseName = toolName.includes('__') ? toolName.split('__').pop() : toolName;
+    const baseTier = deriveBaseTier(baseName);
+    // Check per-server overrides in gateway config
+    const serverConfig = gatewayConfig?.servers[serverName];
+    const override = serverConfig?.tool_overrides?.[toolName];
+    if (override?.tier) {
+        const overrideTier = override.tier;
+        // SECURITY: Prevent tier downgrades — overrides cannot lower a tool below its base tier.
+        if (TIER_SEVERITY[overrideTier] < TIER_SEVERITY[baseTier]) {
+            console.error(`[rea] WARNING: tool_override for "${toolName}" attempted to downgrade tier from ${baseTier} to ${overrideTier} — ignoring override`);
+            return baseTier;
+        }
+        return overrideTier;
+    }
+    return baseTier;
+}
+/**
+ * Check if a tool is explicitly blocked in gateway config.
+ */
+export function isToolBlocked(toolName, serverName, gatewayConfig) {
+    const serverConfig = gatewayConfig?.servers[serverName];
+    const override = serverConfig?.tool_overrides?.[toolName];
+    return override?.blocked === true;
+}

package/dist/config/types.d.ts

@@ -0,0 +1,24 @@
+import type { Tier } from '../policy/types.js';
+export interface ToolOverride {
+    tier?: Tier;
+    blocked?: boolean;
+}
+export interface DownstreamServer {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    tool_overrides?: Record<string, ToolOverride>;
+    /** Max concurrent in-flight calls to this server (0 = unlimited) */
+    max_concurrent_calls?: number;
+    /** Max calls per minute to this server (0 = unlimited) */
+    calls_per_minute?: number;
+}
+export interface GatewayOptions {
+    /** Cap on tool result size in KB. Results exceeding this are truncated. Default: 512 */
+    max_result_size_kb?: number;
+}
+export interface GatewayConfig {
+    version: string;
+    servers: Record<string, DownstreamServer>;
+    gateway?: GatewayOptions;
+}

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/gateway/circuit-breaker.d.ts

@@ -0,0 +1,43 @@
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    /** Consecutive failures before opening the circuit. Default: 5 */
+    failureThreshold?: number;
+    /** Milliseconds to wait in open state before moving to half-open. Default: 30_000 */
+    cooldownMs?: number;
+}
+export interface CircuitStatus {
+    state: CircuitState;
+    serverName: string;
+    retryAt?: string;
+}
+interface CircuitEntry {
+    state: CircuitState;
+    consecutiveFailures: number;
+    openedAt: number | null;
+    failureThreshold: number;
+    cooldownMs: number;
+}
+/**
+ * Per-server circuit breaker.
+ *
+ * State machine:
+ *   closed    → open      after N consecutive failures
+ *   open      → half-open after cooldown period
+ *   half-open → closed    on next success
+ *   half-open → open      on next failure
+ */
+export declare class CircuitBreaker {
+    private circuits;
+    private defaultOptions;
+    constructor(defaults?: CircuitBreakerOptions);
+    private getOrCreate;
+    /**
+     * Returns null if the call may proceed, or a CircuitStatus if the circuit is open.
+     * Side effect: transitions open → half-open if cooldown has elapsed.
+     */
+    isAllowed(serverName: string): CircuitStatus | null;
+    recordSuccess(serverName: string): void;
+    recordFailure(serverName: string): void;
+    getCircuit(serverName: string): CircuitEntry | undefined;
+}
+export {};

package/dist/gateway/circuit-breaker.js

@@ -0,0 +1,86 @@
+/**
+ * Per-server circuit breaker.
+ *
+ * State machine:
+ *   closed    → open      after N consecutive failures
+ *   open      → half-open after cooldown period
+ *   half-open → closed    on next success
+ *   half-open → open      on next failure
+ */
+export class CircuitBreaker {
+    circuits = new Map();
+    defaultOptions;
+    constructor(defaults = {}) {
+        this.defaultOptions = {
+            failureThreshold: defaults.failureThreshold ?? 5,
+            cooldownMs: defaults.cooldownMs ?? 30_000,
+        };
+    }
+    getOrCreate(serverName) {
+        let entry = this.circuits.get(serverName);
+        if (!entry) {
+            entry = {
+                state: 'closed',
+                consecutiveFailures: 0,
+                openedAt: null,
+                failureThreshold: this.defaultOptions.failureThreshold,
+                cooldownMs: this.defaultOptions.cooldownMs,
+            };
+            this.circuits.set(serverName, entry);
+        }
+        return entry;
+    }
+    /**
+     * Returns null if the call may proceed, or a CircuitStatus if the circuit is open.
+     * Side effect: transitions open → half-open if cooldown has elapsed.
+     */
+    isAllowed(serverName) {
+        const entry = this.getOrCreate(serverName);
+        if (entry.state === 'closed')
+            return null;
+        if (entry.state === 'open') {
+            const elapsed = Date.now() - (entry.openedAt ?? 0);
+            if (elapsed >= entry.cooldownMs) {
+                entry.state = 'half-open';
+                entry.consecutiveFailures = 0;
+                console.error(`[rea] circuit-breaker: "${serverName}" transitioned open → half-open (probing recovery)`);
+                return null;
+            }
+            const retryAt = new Date((entry.openedAt ?? 0) + entry.cooldownMs).toISOString();
+            return {
+                state: 'open',
+                serverName,
+                retryAt,
+            };
+        }
+        return null;
+    }
+    recordSuccess(serverName) {
+        const entry = this.getOrCreate(serverName);
+        if (entry.state === 'half-open') {
+            entry.state = 'closed';
+            entry.consecutiveFailures = 0;
+            entry.openedAt = null;
+            console.error(`[rea] circuit-breaker: "${serverName}" recovered — circuit closed`);
+        }
+        else if (entry.state === 'closed') {
+            entry.consecutiveFailures = 0;
+        }
+    }
+    recordFailure(serverName) {
+        const entry = this.getOrCreate(serverName);
+        if (entry.state === 'open')
+            return;
+        entry.consecutiveFailures++;
+        const shouldOpen = entry.state === 'half-open' || entry.consecutiveFailures >= entry.failureThreshold;
+        if (shouldOpen) {
+            entry.state = 'open';
+            entry.openedAt = Date.now();
+            const retryAt = new Date(entry.openedAt + entry.cooldownMs).toISOString();
+            console.error(`[rea] circuit-breaker: "${serverName}" OPENED after ${entry.consecutiveFailures} failure(s) — will retry at ${retryAt}`);
+        }
+    }
+    getCircuit(serverName) {
+        return this.circuits.get(serverName);
+    }
+}

package/dist/gateway/middleware/audit-types.d.ts

@@ -0,0 +1,16 @@
+import type { Tier, InvocationStatus } from '../../policy/types.js';
+export interface AuditRecord {
+    timestamp: string;
+    session_id: string;
+    tool_name: string;
+    server_name: string;
+    tier: Tier;
+    status: InvocationStatus;
+    autonomy_level: string;
+    duration_ms: number;
+    account_name?: string;
+    error?: string;
+    redacted_fields?: string[];
+    hash: string;
+    prev_hash: string;
+}

package/dist/gateway/middleware/audit-types.js

@@ -0,0 +1 @@
+export {};

package/dist/gateway/middleware/audit.d.ts

@@ -0,0 +1,12 @@
+import type { Policy } from '../../policy/types.js';
+import type { Middleware } from './chain.js';
+/**
+ * Post-execution middleware: appends a hash-chained JSONL audit record.
+ *
+ * SECURITY: Each audit middleware instance maintains its own hash chain.
+ * SECURITY: Audit write failures are logged to stderr but do NOT crash the gateway.
+ * SECURITY: Wraps next() in try/finally to ensure audit runs even on middleware exceptions.
+ * SECURITY: Placed as outermost middleware so audit records ALL invocations, including denials.
+ * PERFORMANCE: All fs operations are async to avoid blocking the event loop.
+ */
+export declare function createAuditMiddleware(baseDir: string, policy?: Policy): Middleware;

package/dist/gateway/middleware/audit.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { Tier, InvocationStatus } from '../../policy/types.js';
+function computeHash(record) {
+    const payload = JSON.stringify(record);
+    return crypto.createHash('sha256').update(payload).digest('hex');
+}
+/**
+ * Post-execution middleware: appends a hash-chained JSONL audit record.
+ *
+ * SECURITY: Each audit middleware instance maintains its own hash chain.
+ * SECURITY: Audit write failures are logged to stderr but do NOT crash the gateway.
+ * SECURITY: Wraps next() in try/finally to ensure audit runs even on middleware exceptions.
+ * SECURITY: Placed as outermost middleware so audit records ALL invocations, including denials.
+ * PERFORMANCE: All fs operations are async to avoid blocking the event loop.
+ */
+export function createAuditMiddleware(baseDir, policy) {
+    // REA writes to a single .rea/audit.jsonl file (not dated per-day files).
+    const reaDir = path.join(baseDir, '.rea');
+    const auditFile = path.join(reaDir, 'audit.jsonl');
+    let prevHash = '0000000000000000000000000000000000000000000000000000000000000000';
+    let dirEnsured = false;
+    // SECURITY: Use a write queue to serialize audit writes, ensuring the hash chain is linear.
+    let writeQueue = Promise.resolve();
+    return async (ctx, next) => {
+        let nextError;
+        try {
+            await next();
+        }
+        catch (err) {
+            // Capture the error but still write the audit record
+            nextError = err instanceof Error ? err : new Error(String(err));
+            ctx.status = InvocationStatus.Error;
+            ctx.error = nextError.message;
+        }
+        // Build audit record — always runs, even after exceptions.
+        // SECURITY: autonomy_level from ctx.metadata reflects the hot-reloaded policy (set by policy
+        // middleware inside next()). Falls back to the startup policy if metadata was not set (e.g.,
+        // kill-switch denied before policy middleware ran).
+        const duration_ms = Date.now() - ctx.start_time;
+        const autonomyLevel = ctx.metadata.autonomy_level ?? policy?.autonomy_level ?? 'unknown';
+        // Serialize audit writes via a queue to maintain hash chain linearity under concurrency.
+        // Each write awaits the previous one before computing its hash, ensuring a linear chain.
+        const writePromise = writeQueue.then(async () => {
+            try {
+                const now = new Date().toISOString();
+                const recordBase = {
+                    timestamp: now,
+                    session_id: ctx.session_id,
+                    tool_name: ctx.tool_name,
+                    server_name: ctx.server_name,
+                    tier: ctx.tier ?? Tier.Write,
+                    status: ctx.status,
+                    autonomy_level: autonomyLevel,
+                    duration_ms,
+                    prev_hash: prevHash,
+                };
+                if (ctx.error) {
+                    recordBase.error = ctx.error;
+                }
+                if (ctx.redacted_fields?.length) {
+                    recordBase.redacted_fields = ctx.redacted_fields;
+                }
+                const hash = computeHash(recordBase);
+                const record = { ...recordBase, hash };
+                prevHash = hash;
+                const line = JSON.stringify(record) + '\n';
+                // Ensure .rea dir exists (cached, with retry on failure)
+                if (!dirEnsured) {
+                    await fs.mkdir(reaDir, { recursive: true });
+                    dirEnsured = true;
+                }
+                try {
+                    await fs.appendFile(auditFile, line);
+                }
+                catch {
+                    // Directory may have been deleted externally — retry once with mkdir
+                    dirEnsured = false;
+                    await fs.mkdir(reaDir, { recursive: true });
+                    dirEnsured = true;
+                    await fs.appendFile(auditFile, line);
+                }
+            }
+            catch (auditErr) {
+                // SECURITY: Never crash the gateway on audit failure — log to stderr
+                dirEnsured = false;
+                console.error('[rea] AUDIT WRITE FAILED:', auditErr instanceof Error ? auditErr.message : auditErr);
+            }
+        });
+        writeQueue = writePromise;
+        await writePromise;
+        // Re-throw the original error if next() failed
+        if (nextError) {
+            throw nextError;
+        }
+    };
+}

package/dist/gateway/middleware/blocked-paths.d.ts

@@ -0,0 +1,12 @@
+import type { Policy } from '../../policy/types.js';
+import type { Middleware } from './chain.js';
+/**
+ * Pre-execution middleware: denies tool invocations whose arguments
+ * reference paths that are in the policy's blocked_paths list.
+ *
+ * SECURITY: Inspects all string values in arguments (including nested objects/arrays).
+ * SECURITY: Always blocks .rea/ regardless of policy configuration.
+ * SECURITY: Normalizes URL-encoded characters, path separators, and case before comparison.
+ * SECURITY: Re-reads blocked_paths from policy.yaml when baseDir is provided (hot-reload).
+ */
+export declare function createBlockedPathsMiddleware(initialPolicy: Policy, baseDir?: string): Middleware;

package/dist/gateway/middleware/blocked-paths.js

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import { InvocationStatus } from '../../policy/types.js';
+import { loadPolicyAsync } from '../../policy/loader.js';
+/**
+ * Pre-execution middleware: denies tool invocations whose arguments
+ * reference paths that are in the policy's blocked_paths list.
+ *
+ * SECURITY: Inspects all string values in arguments (including nested objects/arrays).
+ * SECURITY: Always blocks .rea/ regardless of policy configuration.
+ * SECURITY: Normalizes URL-encoded characters, path separators, and case before comparison.
+ * SECURITY: Re-reads blocked_paths from policy.yaml when baseDir is provided (hot-reload).
+ */
+export function createBlockedPathsMiddleware(initialPolicy, baseDir) {
+    return async (ctx, next) => {
+        // Hot-reload blocked_paths from policy.yaml if baseDir is available
+        let blockedPaths = initialPolicy.blocked_paths;
+        if (baseDir) {
+            try {
+                const policy = await loadPolicyAsync(baseDir);
+                blockedPaths = policy.blocked_paths;
+            }
+            catch {
+                // Fall back to initial policy's blocked_paths on read failure
+            }
+        }
+        // Always protect .rea/ — it's the trust root of the system.
+        const paths = [...new Set([...blockedPaths, '.rea/'])];
+        // Recursively extract all string values from arguments
+        const stringValues = extractStringValues(ctx.arguments);
+        for (const [key, value] of stringValues) {
+            for (const blocked of paths) {
+                if (containsBlockedPath(value, blocked)) {
+                    ctx.status = InvocationStatus.Denied;
+                    ctx.error = `Argument "${key}" references blocked path "${blocked}". Tool: ${ctx.tool_name}`;
+                    return;
+                }
+            }
+        }
+        await next();
+    };
+}
+/**
+ * Recursively extract all string values from an object, with their key paths.
+ * Handles nested objects and arrays.
+ */
+function extractStringValues(obj, prefix = '', seen = new WeakSet()) {
+    const results = [];
+    if (obj === null || obj === undefined)
+        return results;
+    if (typeof obj === 'string') {
+        results.push([prefix || 'value', obj]);
+        return results;
+    }
+    if (typeof obj !== 'object')
+        return results;
+    // Circular reference guard
+    const objRef = obj;
+    if (seen.has(objRef))
+        return results;
+    seen.add(objRef);
+    if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+            results.push(...extractStringValues(obj[i], `${prefix}[${i}]`, seen));
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(obj)) {
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            results.push(...extractStringValues(value, fullKey, seen));
+        }
+    }
+    return results;
+}
+/**
+ * Check if a string value references a blocked path.
+ *
+ * SECURITY: Decodes URL-encoded characters (%2F, %2f, etc.)
+ * SECURITY: Normalizes path separators and resolves . and .. segments
+ * SECURITY: Performs case-insensitive comparison for cross-platform safety
+ */
+function containsBlockedPath(value, blockedPath) {
+    // Normalize the value: decode URL encoding, normalize slashes and path segments
+    const normalized = normalizePath(value);
+    const normalizedBlocked = blockedPath.replace(/\\/g, '/').toLowerCase();
+    // Direct containment check (case-insensitive)
+    if (normalized.includes(normalizedBlocked))
+        return true;
+    // Check without leading dot/slash for relative path variants
+    const stripped = normalizedBlocked.replace(/^\.?\/?/, '');
+    if (stripped && normalized.includes(stripped))
+        return true;
+    return false;
+}
+/**
+ * Normalize a path string for blocked-path comparison.
+ *
+ * 1. Decode URL-encoded characters (handles %2F, %2f, %2E, etc.)
+ * 2. Normalize backslashes to forward slashes
+ * 3. Normalize path segments (resolve . and ..)
+ * 4. Lowercase for case-insensitive comparison
+ */
+function normalizePath(value) {
+    let decoded = value;
+    // Decode URL-encoded characters (try/catch for malformed sequences)
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        // If decoding fails, use the original value — may contain partial encoding
+    }
+    // Normalize backslashes to forward slashes
+    decoded = decoded.replace(/\\/g, '/');
+    // Use path.normalize to resolve . and .. segments, then re-normalize slashes
+    decoded = path.normalize(decoded).replace(/\\/g, '/');
+    // Lowercase for case-insensitive comparison
+    return decoded.toLowerCase();
+}

package/dist/gateway/middleware/chain.d.ts

@@ -0,0 +1,28 @@
+import { InvocationStatus, type Tier } from '../../policy/types.js';
+export interface InvocationContext {
+    tool_name: string;
+    server_name: string;
+    arguments: Record<string, unknown>;
+    session_id: string;
+    tier?: Tier;
+    status: InvocationStatus;
+    error?: string;
+    result?: unknown;
+    start_time: number;
+    redacted_fields?: string[];
+    metadata: Record<string, unknown>;
+}
+export type NextFn = () => Promise<void>;
+export type Middleware = (ctx: InvocationContext, next: NextFn) => Promise<void>;
+/**
+ * Execute a middleware chain in onion (koa-style) order.
+ *
+ * SECURITY: Once status is set to Denied, it is locked for the remainder
+ * of the chain. No middleware can revert a denial.
+ */
+export declare function executeChain(middlewares: Middleware[], ctx: InvocationContext): Promise<void>;
+/**
+ * Type-safe factory for building named middleware chains.
+ * Returns a function that executes the chain with a fresh context.
+ */
+export declare function createMiddlewareChain(middlewares: Middleware[]): (ctx: InvocationContext) => Promise<void>;

package/dist/gateway/middleware/chain.js

@@ -0,0 +1,40 @@
+import { InvocationStatus } from '../../policy/types.js';
+/**
+ * Execute a middleware chain in onion (koa-style) order.
+ *
+ * SECURITY: Once status is set to Denied, it is locked for the remainder
+ * of the chain. No middleware can revert a denial.
+ */
+export function executeChain(middlewares, ctx) {
+    let index = -1;
+    let deniedOnce = false;
+    let savedError;
+    function dispatch(i) {
+        if (i <= index) {
+            return Promise.reject(new Error('next() called multiple times'));
+        }
+        index = i;
+        const mw = middlewares[i];
+        if (!mw) {
+            return Promise.resolve();
+        }
+        return Promise.resolve(mw(ctx, () => dispatch(i + 1))).then(() => {
+            if (ctx.status === InvocationStatus.Denied && !deniedOnce) {
+                deniedOnce = true;
+                savedError = ctx.error;
+            }
+            if (deniedOnce && ctx.status !== InvocationStatus.Denied) {
+                ctx.status = InvocationStatus.Denied;
+                ctx.error = savedError ?? 'Denial status was tampered with — re-locked';
+            }
+        });
+    }
+    return dispatch(0);
+}
+/**
+ * Type-safe factory for building named middleware chains.
+ * Returns a function that executes the chain with a fresh context.
+ */
+export function createMiddlewareChain(middlewares) {
+    return (ctx) => executeChain(middlewares, ctx);
+}

package/dist/gateway/middleware/circuit-breaker.d.ts

@@ -0,0 +1,11 @@
+import type { CircuitBreaker } from '../circuit-breaker.js';
+import type { Middleware } from './chain.js';
+/**
+ * PreToolUse + PostToolUse middleware: wraps downstream calls with a circuit breaker.
+ *
+ * On entry: if the circuit is open, denies the call immediately and returns the
+ * structured error without hitting the downstream server.
+ *
+ * On exit: records success or failure so the breaker can track state transitions.
+ */
+export declare function createCircuitBreakerMiddleware(breaker: CircuitBreaker): Middleware;

package/dist/gateway/middleware/circuit-breaker.js

@@ -0,0 +1,43 @@
+import { InvocationStatus } from '../../policy/types.js';
+/**
+ * PreToolUse + PostToolUse middleware: wraps downstream calls with a circuit breaker.
+ *
+ * On entry: if the circuit is open, denies the call immediately and returns the
+ * structured error without hitting the downstream server.
+ *
+ * On exit: records success or failure so the breaker can track state transitions.
+ */
+export function createCircuitBreakerMiddleware(breaker) {
+    return async (ctx, next) => {
+        const status = breaker.isAllowed(ctx.server_name);
+        if (status !== null) {
+            // Circuit is open — fail fast
+            ctx.status = InvocationStatus.Denied;
+            ctx.error =
+                `Circuit breaker open for server "${status.serverName}": downstream is unavailable. ` +
+                    `State: ${status.state}. Will retry at ${status.retryAt ?? 'unknown'}.`;
+            ctx.metadata.circuit_breaker = {
+                state: status.state,
+                serverName: status.serverName,
+                retryAt: status.retryAt,
+            };
+            return;
+        }
+        try {
+            await next();
+            // A Denied status from the middleware chain (policy, rate-limit, etc.) is not a
+            // downstream failure — only Error status means the server itself failed.
+            if (ctx.status === InvocationStatus.Error) {
+                breaker.recordFailure(ctx.server_name);
+            }
+            else {
+                breaker.recordSuccess(ctx.server_name);
+            }
+        }
+        catch (err) {
+            // Unhandled exceptions from inner middlewares also count as failures
+            breaker.recordFailure(ctx.server_name);
+            throw err;
+        }
+    };
+}