@bookedsolid/rea 0.3.0 → 0.4.0

package/dist/gateway/observability/metrics.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Minimal Prometheus-style metrics for `rea serve` (G5).
+ *
+ * The gateway exposes an OPT-IN `/metrics` endpoint when `REA_METRICS_PORT`
+ * is set. The project rule is "no silent listeners" — without that env var
+ * nothing binds to a port, ever. When set, we bind to 127.0.0.1 ONLY and
+ * respond in the standard Prometheus text-exposition format.
+ *
+ * ## What we expose
+ *
+ *   rea_downstream_calls_total{server="<n>"}             counter
+ *   rea_downstream_errors_total{server="<n>"}            counter
+ *   rea_downstream_in_flight{server="<n>"}               gauge
+ *   rea_audit_lines_appended_total                        counter
+ *   rea_circuit_breaker_state{server="<n>"}              gauge (0=closed, 1=half-open, 2=open)
+ *   rea_seconds_since_last_halt_check                     gauge
+ *
+ * Conventions match https://prometheus.io/docs/instrumenting/exposition_formats/
+ * — Unix-epoch timestamps omitted, `# HELP` / `# TYPE` lines included.
+ *
+ * ## What this is NOT
+ *
+ * - Not full OpenTelemetry. No traces, no histograms, no exemplars. If a user
+ *   needs those, they can scrape these metrics and forward, or switch to an
+ *   OTel pipeline later — the primitives are isolated in this file.
+ * - Not served over TLS. This is loopback-only tooling. Any cross-host scrape
+ *   should tunnel through SSH or a reverse proxy.
+ * - Not a labelled cardinality bomb. Labels are limited to `server` (the set
+ *   of downstreams is fixed by the registry) — we do NOT label by `tool_name`
+ *   or anything user-controlled, which would let a downstream blow up the
+ *   metrics store.
+ *
+ * ## Why handcrafted?
+ *
+ * prom-client is small but pulls its own tree of transitive deps we don't
+ * otherwise need. The exposition format is ~30 lines; we keep dep count
+ * low and avoid the supply-chain surface.
+ */
+import type { Logger } from '../log.js';
+/**
+ * Encoded values for the circuit-breaker gauge. Keep numerically ordered by
+ * severity so a `max()` query surfaces the worst state.
+ */
+export declare const CIRCUIT_GAUGE: {
+    readonly closed: 0;
+    readonly halfOpen: 1;
+    readonly open: 2;
+};
+export type CircuitGaugeValue = (typeof CIRCUIT_GAUGE)[keyof typeof CIRCUIT_GAUGE];
+/**
+ * In-process state for the counters and gauges. A single instance is owned
+ * by the gateway and passed to any collaborator that needs to record.
+ *
+ * Methods mutate synchronously and never throw — metrics failures must not
+ * interrupt a tool call.
+ */
+export declare class MetricsRegistry {
+    private readonly downstreamCalls;
+    private readonly downstreamErrors;
+    private readonly downstreamInFlight;
+    private readonly circuitState;
+    private auditLinesAppended;
+    private lastHaltCheckMs;
+    incDownstreamCall(server: string): void;
+    incDownstreamError(server: string): void;
+    incDownstreamInFlight(server: string): void;
+    decDownstreamInFlight(server: string): void;
+    incAuditLines(n?: number): void;
+    setCircuitState(server: string, value: CircuitGaugeValue): void;
+    markHaltCheck(nowMs?: number): void;
+    /** Snapshot for tests / diagnostics. */
+    snapshot(): {
+        downstreamCalls: Record<string, number>;
+        downstreamErrors: Record<string, number>;
+        downstreamInFlight: Record<string, number>;
+        circuitState: Record<string, CircuitGaugeValue>;
+        auditLinesAppended: number;
+        lastHaltCheckMs: number | null;
+    };
+    /**
+     * Render the Prometheus text exposition. Every metric gets HELP + TYPE
+     * headers even when its table is empty — that makes the output stable
+     * across scrapes and easier to diff.
+     */
+    render(nowMs?: number): string;
+}
+export interface MetricsServer {
+    /** Returns the port actually bound (useful for tests that pass port 0). */
+    port(): number;
+    close(): Promise<void>;
+}
+export interface StartMetricsServerOptions {
+    port: number;
+    registry: MetricsRegistry;
+    logger?: Logger;
+    /**
+     * Override the bind host. Only loopback values (`127.0.0.1`, `::1`) are
+     * accepted; any other value — including `localhost`, `0.0.0.0`, `::`, or
+     * any LAN IP — throws a TypeError before a socket is opened. The
+     * /metrics endpoint has no auth, so binding a non-loopback interface
+     * would expose gateway internals to the network.
+     *
+     * Default: `127.0.0.1`.
+     */
+    host?: string;
+}
+/**
+ * Start a loopback-only HTTP server that serves `/metrics`.
+ *
+ * Security posture:
+ *   - Binds to 127.0.0.1 by default. Callers cannot override to a public
+ *     interface from the CLI; the `host` option exists for test injection.
+ *   - Rejects every non-GET request with 405 (Prometheus scrapers only GET).
+ *   - Rejects every path ≠ `/metrics` with 404. The body is a fixed string —
+ *     we do NOT echo the request path, which would allow response splitting
+ *     or reflected content.
+ *   - No query-string parsing, no request body read, no cookies.
+ */
+export declare function startMetricsServer(opts: StartMetricsServerOptions): Promise<MetricsServer>;
+/**
+ * Parse and validate `REA_METRICS_PORT`. Returns the numeric port, or `null`
+ * if the env var is unset / malformed. An out-of-range or non-numeric value
+ * logs a warning and also returns null — we never silently bind on a default.
+ */
+export declare function resolveMetricsPort(raw: string | undefined, logger?: Logger): number | null;

package/dist/gateway/observability/metrics.js

@@ -0,0 +1,321 @@
+/**
+ * Minimal Prometheus-style metrics for `rea serve` (G5).
+ *
+ * The gateway exposes an OPT-IN `/metrics` endpoint when `REA_METRICS_PORT`
+ * is set. The project rule is "no silent listeners" — without that env var
+ * nothing binds to a port, ever. When set, we bind to 127.0.0.1 ONLY and
+ * respond in the standard Prometheus text-exposition format.
+ *
+ * ## What we expose
+ *
+ *   rea_downstream_calls_total{server="<n>"}             counter
+ *   rea_downstream_errors_total{server="<n>"}            counter
+ *   rea_downstream_in_flight{server="<n>"}               gauge
+ *   rea_audit_lines_appended_total                        counter
+ *   rea_circuit_breaker_state{server="<n>"}              gauge (0=closed, 1=half-open, 2=open)
+ *   rea_seconds_since_last_halt_check                     gauge
+ *
+ * Conventions match https://prometheus.io/docs/instrumenting/exposition_formats/
+ * — Unix-epoch timestamps omitted, `# HELP` / `# TYPE` lines included.
+ *
+ * ## What this is NOT
+ *
+ * - Not full OpenTelemetry. No traces, no histograms, no exemplars. If a user
+ *   needs those, they can scrape these metrics and forward, or switch to an
+ *   OTel pipeline later — the primitives are isolated in this file.
+ * - Not served over TLS. This is loopback-only tooling. Any cross-host scrape
+ *   should tunnel through SSH or a reverse proxy.
+ * - Not a labelled cardinality bomb. Labels are limited to `server` (the set
+ *   of downstreams is fixed by the registry) — we do NOT label by `tool_name`
+ *   or anything user-controlled, which would let a downstream blow up the
+ *   metrics store.
+ *
+ * ## Why handcrafted?
+ *
+ * prom-client is small but pulls its own tree of transitive deps we don't
+ * otherwise need. The exposition format is ~30 lines; we keep dep count
+ * low and avoid the supply-chain surface.
+ */
+import http from 'node:http';
+/**
+ * Loopback address we bind to. IPv4 first by convention — operators expect
+ * `curl http://127.0.0.1:<port>/metrics` to work without dual-stack surprise.
+ */
+const LOOPBACK = '127.0.0.1';
+/**
+ * Strict allowlist of host values that `startMetricsServer` will accept.
+ * Anything else (0.0.0.0, ::, LAN IPs, hostnames) is rejected at the API
+ * boundary so no in-process caller can accidentally expose the
+ * unauthenticated /metrics surface to the network.
+ *
+ * SECURITY: Do NOT add non-loopback entries. If you need off-host scraping,
+ * tunnel via SSH or front 127.0.0.1 with a TLS-terminating reverse proxy.
+ */
+const ALLOWED_HOSTS = new Set(['127.0.0.1', '::1']);
+/** Path we serve. All other paths get 404. */
+const METRICS_PATH = '/metrics';
+/**
+ * Wall-clock budget for `server.close()`. Past this point any surviving
+ * keep-alive sockets are destroyed outright so shutdown never waits on a
+ * Prometheus scraper that is holding the connection open.
+ */
+const CLOSE_DEADLINE_MS = 2_000;
+/**
+ * Encoded values for the circuit-breaker gauge. Keep numerically ordered by
+ * severity so a `max()` query surfaces the worst state.
+ */
+export const CIRCUIT_GAUGE = {
+    closed: 0,
+    halfOpen: 1,
+    open: 2,
+};
+/**
+ * In-process state for the counters and gauges. A single instance is owned
+ * by the gateway and passed to any collaborator that needs to record.
+ *
+ * Methods mutate synchronously and never throw — metrics failures must not
+ * interrupt a tool call.
+ */
+export class MetricsRegistry {
+    downstreamCalls = new Map();
+    downstreamErrors = new Map();
+    downstreamInFlight = new Map();
+    circuitState = new Map();
+    auditLinesAppended = 0;
+    lastHaltCheckMs = null;
+    incDownstreamCall(server) {
+        this.downstreamCalls.set(server, (this.downstreamCalls.get(server) ?? 0) + 1);
+    }
+    incDownstreamError(server) {
+        this.downstreamErrors.set(server, (this.downstreamErrors.get(server) ?? 0) + 1);
+    }
+    incDownstreamInFlight(server) {
+        this.downstreamInFlight.set(server, (this.downstreamInFlight.get(server) ?? 0) + 1);
+    }
+    decDownstreamInFlight(server) {
+        const next = Math.max(0, (this.downstreamInFlight.get(server) ?? 0) - 1);
+        this.downstreamInFlight.set(server, next);
+    }
+    incAuditLines(n = 1) {
+        this.auditLinesAppended += Math.max(0, n | 0);
+    }
+    setCircuitState(server, value) {
+        this.circuitState.set(server, value);
+    }
+    markHaltCheck(nowMs = Date.now()) {
+        this.lastHaltCheckMs = nowMs;
+    }
+    /** Snapshot for tests / diagnostics. */
+    snapshot() {
+        return {
+            downstreamCalls: Object.fromEntries(this.downstreamCalls),
+            downstreamErrors: Object.fromEntries(this.downstreamErrors),
+            downstreamInFlight: Object.fromEntries(this.downstreamInFlight),
+            circuitState: Object.fromEntries(this.circuitState),
+            auditLinesAppended: this.auditLinesAppended,
+            lastHaltCheckMs: this.lastHaltCheckMs,
+        };
+    }
+    /**
+     * Render the Prometheus text exposition. Every metric gets HELP + TYPE
+     * headers even when its table is empty — that makes the output stable
+     * across scrapes and easier to diff.
+     */
+    render(nowMs = Date.now()) {
+        const lines = [];
+        const emitCounter = (name, help, rows) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} counter`);
+            for (const [server, v] of rows) {
+                lines.push(`${name}{server="${escapeLabel(server)}"} ${v}`);
+            }
+        };
+        const emitGauge = (name, help, rows) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} gauge`);
+            for (const [server, v] of rows) {
+                lines.push(`${name}{server="${escapeLabel(server)}"} ${v}`);
+            }
+        };
+        emitCounter('rea_downstream_calls_total', 'Total tool calls dispatched to each downstream server.', this.downstreamCalls);
+        emitCounter('rea_downstream_errors_total', 'Total failed tool calls per downstream server.', this.downstreamErrors);
+        emitGauge('rea_downstream_in_flight', 'Tool calls currently executing against each downstream server.', this.downstreamInFlight);
+        lines.push('# HELP rea_audit_lines_appended_total Audit lines appended since gateway start.');
+        lines.push('# TYPE rea_audit_lines_appended_total counter');
+        lines.push(`rea_audit_lines_appended_total ${this.auditLinesAppended}`);
+        emitGauge('rea_circuit_breaker_state', 'Circuit breaker state per server (0=closed, 1=half-open, 2=open).', this.circuitState);
+        lines.push('# HELP rea_seconds_since_last_halt_check Seconds since the middleware last consulted .rea/HALT.');
+        lines.push('# TYPE rea_seconds_since_last_halt_check gauge');
+        const secondsSince = this.lastHaltCheckMs === null ? -1 : Math.max(0, (nowMs - this.lastHaltCheckMs) / 1000);
+        lines.push(`rea_seconds_since_last_halt_check ${secondsSince}`);
+        // Prometheus requires a trailing newline.
+        return lines.join('\n') + '\n';
+    }
+}
+/**
+ * Sanitize label values per Prometheus rules (escape `\`, `"`, and newlines).
+ * Server names come from the registry which already restricts the allowed
+ * charset, but defense-in-depth costs nothing.
+ */
+function escapeLabel(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+/**
+ * Start a loopback-only HTTP server that serves `/metrics`.
+ *
+ * Security posture:
+ *   - Binds to 127.0.0.1 by default. Callers cannot override to a public
+ *     interface from the CLI; the `host` option exists for test injection.
+ *   - Rejects every non-GET request with 405 (Prometheus scrapers only GET).
+ *   - Rejects every path ≠ `/metrics` with 404. The body is a fixed string —
+ *     we do NOT echo the request path, which would allow response splitting
+ *     or reflected content.
+ *   - No query-string parsing, no request body read, no cookies.
+ */
+export function startMetricsServer(opts) {
+    return new Promise((resolve, reject) => {
+        // Track every live socket so shutdown can guarantee a bounded wall-clock.
+        // `server.close()` on its own only stops accepting NEW connections —
+        // keep-alive sessions (like a sticky Prometheus scraper) drain on their
+        // own schedule. We destroy tracked sockets past the deadline.
+        const sockets = new Set();
+        const server = http.createServer((req, res) => {
+            // Defensive: if the url is missing or non-string we treat it as 404.
+            const url = typeof req.url === 'string' ? req.url : '';
+            // Strip any query string; exposition format endpoints ignore it.
+            const pathOnly = url.split('?')[0] ?? '';
+            if (req.method !== 'GET') {
+                res.statusCode = 405;
+                res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                res.setHeader('Allow', 'GET');
+                res.end('method not allowed\n');
+                return;
+            }
+            if (pathOnly !== METRICS_PATH) {
+                res.statusCode = 404;
+                res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                // Fixed body — never echo `url` here. XSS via a text/plain body is
+                // limited but avoiding reflection costs nothing.
+                res.end('not found\n');
+                return;
+            }
+            try {
+                const body = opts.registry.render();
+                res.statusCode = 200;
+                // Prometheus convention: version=0.0.4 exposition format is served as
+                // text/plain. No charset is strictly required by the standard but
+                // utf-8 is safe.
+                res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+                res.end(body);
+            }
+            catch (err) {
+                // Don't leak stack or internals. Log for the operator.
+                opts.logger?.error({
+                    event: 'metrics.render_failed',
+                    message: 'failed to render metrics',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                res.statusCode = 500;
+                res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                res.end('internal error\n');
+            }
+        });
+        server.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.once('close', () => {
+                sockets.delete(socket);
+            });
+        });
+        server.on('error', (err) => {
+            reject(err);
+        });
+        // Resolve the bind host with defense-in-depth:
+        //   1. The public `host` option is validated against a strict loopback
+        //      allowlist. Non-loopback values throw synchronously BEFORE a socket
+        //      opens — a caller bug cannot silently bind 0.0.0.0 and expose the
+        //      unauthenticated endpoint.
+        //   2. Default when unset: 127.0.0.1.
+        let host;
+        if (opts.host === undefined) {
+            host = LOOPBACK;
+        }
+        else if (ALLOWED_HOSTS.has(opts.host)) {
+            host = opts.host;
+        }
+        else {
+            reject(new TypeError(`rea metrics: refusing to bind host "${opts.host}" — only loopback (127.0.0.1, ::1) is permitted; the endpoint has no auth`));
+            return;
+        }
+        server.listen(opts.port, host, () => {
+            const addr = server.address();
+            const actualPort = addr !== null && typeof addr === 'object' ? addr.port : opts.port;
+            opts.logger?.info({
+                event: 'metrics.listening',
+                message: `metrics endpoint bound on ${host}:${actualPort}${METRICS_PATH}`,
+                port: actualPort,
+                host,
+            });
+            resolve({
+                port: () => actualPort,
+                close: () => new Promise((closeResolve) => {
+                    let settled = false;
+                    const finish = () => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        clearTimeout(deadline);
+                        closeResolve();
+                    };
+                    // Happy path: server.close() fires when all in-flight requests
+                    // plus their underlying sockets have drained naturally.
+                    server.close(() => finish());
+                    // Fallback path: after CLOSE_DEADLINE_MS, destroy any surviving
+                    // sockets so the close callback can fire. `closeIdleConnections`
+                    // handles idle keep-alive sessions first (Node 18.2+), then we
+                    // destroy whatever is left — including in-flight requests, which
+                    // a stalled scraper could pin indefinitely otherwise.
+                    const deadline = setTimeout(() => {
+                        try {
+                            server.closeIdleConnections?.();
+                        }
+                        catch {
+                            // Best-effort — method is optional on older Node.
+                        }
+                        for (const sock of sockets) {
+                            try {
+                                sock.destroy();
+                            }
+                            catch {
+                                // Sockets may already be closing.
+                            }
+                        }
+                        sockets.clear();
+                        // Some platforms don't deliver the close() callback after a
+                        // forced socket shutdown — settle directly.
+                        finish();
+                    }, CLOSE_DEADLINE_MS);
+                    // Don't let the timer hold the process open if shutdown beats it.
+                    deadline.unref();
+                }),
+            });
+        });
+    });
+}
+/**
+ * Parse and validate `REA_METRICS_PORT`. Returns the numeric port, or `null`
+ * if the env var is unset / malformed. An out-of-range or non-numeric value
+ * logs a warning and also returns null — we never silently bind on a default.
+ */
+export function resolveMetricsPort(raw, logger) {
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        logger?.warn({
+            event: 'metrics.port_invalid',
+            message: `REA_METRICS_PORT="${raw}" is not a valid TCP port; metrics endpoint will NOT start`,
+        });
+        return null;
+    }
+    return n;
+}

package/dist/gateway/server.d.ts

@@ -33,10 +33,25 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { DownstreamPool } from './downstream-pool.js';
 import type { Registry } from '../registry/types.js';
 import type { Policy } from '../policy/types.js';
+import { type Logger } from './log.js';
+import { type MetricsRegistry } from './observability/metrics.js';
 export interface GatewayOptions {
     baseDir: string;
     policy: Policy;
     registry: Registry;
+    /**
+     * Optional structured logger. If omitted, a default logger is created that
+     * writes to `process.stderr` honoring `REA_LOG_LEVEL`. Tests inject their
+     * own logger to capture records.
+     */
+    logger?: Logger;
+    /**
+     * Optional metrics registry. When supplied, the terminal middleware and
+     * connection lifecycle events increment counters/gauges on it. When
+     * omitted, no metrics are recorded — this keeps the gateway usable in
+     * tests without bringing in the metrics surface.
+     */
+    metrics?: MetricsRegistry;
 }
 export interface GatewayHandle {
     /** Expose the Server for test harnesses that attach InMemoryTransport. */
@@ -47,5 +62,9 @@ export interface GatewayHandle {
     stop(): Promise<void>;
     /** Exposed for tests. */
     pool: DownstreamPool;
+    /** The active logger — shared with serve.ts so startup messages stay in one sink. */
+    logger: Logger;
+    /** Optional metrics registry (undefined when the caller did not supply one). */
+    metrics: MetricsRegistry | undefined;
 }
 export declare function createGateway(opts: GatewayOptions): GatewayHandle;

package/dist/gateway/server.js

@@ -31,7 +31,7 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { DownstreamPool, splitPrefixed } from './downstream-pool.js';
 import { createAuditMiddleware } from './middleware/audit.js';
 import { createKillSwitchMiddleware } from './middleware/kill-switch.js';
@@ -41,7 +41,7 @@ import { createBlockedPathsMiddleware } from './middleware/blocked-paths.js';
 import { createRateLimitMiddleware } from './middleware/rate-limit.js';
 import { createCircuitBreakerMiddleware } from './middleware/circuit-breaker.js';
 import { createInjectionMiddleware } from './middleware/injection.js';
-import { createRedactMiddleware, } from './middleware/redact.js';
+import { createRedactMiddleware } from './middleware/redact.js';
 import { wrapRegex } from './redact-safe/match-timeout.js';
 import { createResultSizeCapMiddleware } from './middleware/result-size-cap.js';
 import { executeChain } from './middleware/chain.js';
@@ -50,6 +50,8 @@ import { CircuitBreaker } from './circuit-breaker.js';
 import { currentSessionId } from './session.js';
 import { InvocationStatus, Tier } from '../policy/types.js';
 import { log } from '../cli/utils.js';
+import { createLogger } from './log.js';
+import { CIRCUIT_GAUGE } from './observability/metrics.js';
 /**
  * Build the ordered middleware chain used on every CallToolRequest.
  * Order is prescriptive — DO NOT reorder without reading THREAT_MODEL.md §
@@ -82,30 +84,68 @@ function compileUserRedactPatterns(policy, matchTimeoutMs) {
     }
     return out;
 }
-function buildMiddlewareChain(opts) {
-    const { baseDir, policy } = opts;
+function buildMiddlewareChain(opts, deps) {
+    const { baseDir, policy, metrics } = opts;
     const matchTimeoutMs = policy.redact?.match_timeout_ms ?? 100;
     const userPatterns = compileUserRedactPatterns(policy, matchTimeoutMs);
     return [
-        createAuditMiddleware(baseDir, policy),
-        createKillSwitchMiddleware(baseDir),
+        // Metrics threaded through so `rea_audit_lines_appended_total` advances
+        // on every durable audit append and `rea_seconds_since_last_halt_check`
+        // reflects per-invocation cadence, not gateway uptime.
+        createAuditMiddleware(baseDir, policy, metrics),
+        createKillSwitchMiddleware(baseDir, metrics),
         createTierMiddleware(),
         createPolicyMiddleware(policy, undefined, baseDir),
         createBlockedPathsMiddleware(policy, baseDir),
         createRateLimitMiddleware(new RateLimiter()),
-        createCircuitBreakerMiddleware(new CircuitBreaker()),
-        createInjectionMiddleware(policy.injection_detection === 'warn' ? 'warn' : 'block', {
-            matchTimeoutMs,
-        }),
+        createCircuitBreakerMiddleware(deps.breaker),
+        createInjectionMiddleware(policy.injection_detection === 'warn' ? 'warn' : 'block', (() => {
+            // G9 follow-up: preserve the tri-state for `suspiciousBlocksWrites`
+            // (true / false / undefined-omitted). With `exactOptionalPropertyTypes`
+            // we must omit the key entirely rather than passing `undefined` so
+            // the middleware's `?? true` / `?? false` default logic runs for
+            // consumers who did not configure the flag. `bst-internal*` profiles
+            // pin the flag explicitly.
+            const pinned = policy.injection?.suspicious_blocks_writes;
+            return pinned === undefined
+                ? { matchTimeoutMs }
+                : { matchTimeoutMs, suspiciousBlocksWrites: pinned };
+        })()),
         createRedactMiddleware({ matchTimeoutMs, userPatterns }),
         createResultSizeCapMiddleware(),
     ];
 }
 export function createGateway(opts) {
     const { registry } = opts;
-    const pool = new DownstreamPool(registry);
+    const logger = opts.logger ?? createLogger({ base: { session_id: currentSessionId() } });
+    const metrics = opts.metrics;
+    const pool = new DownstreamPool(registry, logger);
     const server = new Server({ name: 'rea', version: '0.2.0' }, { capabilities: { tools: {} } });
-    const staticChain = buildMiddlewareChain(opts);
+    // Build the circuit breaker with observability hooks wired in — state
+    // transitions log a structured record AND update the Prometheus gauge.
+    const breaker = new CircuitBreaker({
+        onStateChange: (event) => {
+            const level = event.to === 'open' ? 'warn' : 'info';
+            logger[level]({
+                event: `circuit.${event.to.replace('-', '_')}`,
+                server_name: event.server,
+                message: `circuit-breaker: "${event.server}" ${event.from} → ${event.to} (${event.reason})`,
+                ...(event.retryAt !== undefined ? { retry_at: event.retryAt } : {}),
+            });
+            switch (event.to) {
+                case 'closed':
+                    metrics?.setCircuitState(event.server, CIRCUIT_GAUGE.closed);
+                    break;
+                case 'half-open':
+                    metrics?.setCircuitState(event.server, CIRCUIT_GAUGE.halfOpen);
+                    break;
+                case 'open':
+                    metrics?.setCircuitState(event.server, CIRCUIT_GAUGE.open);
+                    break;
+            }
+        },
+    });
+    const staticChain = buildMiddlewareChain(opts, { breaker });
     // ── Handlers ─────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         if (pool.size === 0)
@@ -159,13 +199,19 @@ export function createGateway(opts) {
                 context.error = 'No downstream servers in .rea/registry.yaml — add one to enable proxying';
                 return;
             }
+            metrics?.incDownstreamCall(serverName);
+            metrics?.incDownstreamInFlight(serverName);
             try {
                 context.result = await pool.callTool(prefixed, context.arguments);
             }
             catch (err) {
+                metrics?.incDownstreamError(serverName);
                 context.status = InvocationStatus.Error;
                 context.error = err instanceof Error ? err.message : String(err);
             }
+            finally {
+                metrics?.decDownstreamInFlight(serverName);
+            }
         };
         try {
             await executeChain([...staticChain, terminal], ctx);
@@ -224,14 +270,51 @@ export function createGateway(opts) {
         // Connect to downstream children first so the `listTools` catalog is ready
         // by the time the upstream client connects.
         if (pool.size === 0) {
-            log('rea serve: no downstream servers in .rea/registry.yaml — running in no-op mode. Add servers to enable proxying.');
+            logger.info({
+                event: 'gateway.no_downstreams',
+                message: 'no downstream servers in .rea/registry.yaml — running in no-op mode. Add servers to enable proxying.',
+            });
         }
         else {
+            for (const s of registry.servers) {
+                if (!s.enabled)
+                    continue;
+                logger.info({
+                    event: 'downstream.connect_attempt',
+                    server_name: s.name,
+                    message: `connecting downstream "${s.name}"`,
+                });
+            }
             try {
                 await pool.connectAll();
+                for (const s of registry.servers) {
+                    if (!s.enabled)
+                        continue;
+                    const conn = pool.getConnection(s.name);
+                    if (conn !== undefined && conn.isHealthy) {
+                        logger.info({
+                            event: 'downstream.connected',
+                            server_name: s.name,
+                            message: `downstream "${s.name}" connected`,
+                        });
+                        // Every healthy downstream starts in the closed state — record
+                        // the initial circuit-breaker gauge so scrapers see a baseline.
+                        metrics?.setCircuitState(s.name, CIRCUIT_GAUGE.closed);
+                    }
+                    else {
+                        logger.warn({
+                            event: 'downstream.unhealthy_on_start',
+                            server_name: s.name,
+                            message: `downstream "${s.name}" did not come up healthy`,
+                        });
+                    }
+                }
             }
             catch (err) {
-                log(`rea serve: downstream connect error: ${err instanceof Error ? err.message : err}`);
+                logger.error({
+                    event: 'downstream.connect_failed',
+                    message: `downstream connect error: ${err instanceof Error ? err.message : err}`,
+                });
                 // Continue — individual connections may still be healthy.
             }
         }
@@ -242,6 +325,7 @@ export function createGateway(opts) {
         if (stopping)
             return;
         stopping = true;
+        logger.info({ event: 'gateway.shutdown', message: 'gateway stop requested' });
         try {
             await server.close();
         }
@@ -250,7 +334,7 @@ export function createGateway(opts) {
         }
         await pool.close();
     }
-    return { server, start, stop, pool };
+    return { server, start, stop, pool, logger, metrics };
 }
 // Prevent TS from complaining about the unused `Tier` import when the file is
 // compiled in isolation; keeping the import pins the semantic dependency edge