@bookedsolid/rea 0.3.0 → 0.4.0

package/dist/cli/status.js

@@ -0,0 +1,399 @@
+/**
+ * `rea status` — running-process introspection for `rea serve` (G5).
+ *
+ * `rea check` is the ON-DISK view: policy, HALT, recent audit entries. It
+ * works when no gateway is running.
+ *
+ * `rea status` is the LIVE view: is a gateway running for this cwd? What is
+ * its session id? What does the audit chain look like right now? Is HALT
+ * active?
+ *
+ * Detection strategy for "is serve running":
+ *   1. Read `.rea/serve.pid`.
+ *   2. If the pidfile exists, `kill(pid, 0)` to check liveness.
+ *   3. If kill throws ESRCH or EPERM, the pid is stale — treat as not-running
+ *      and surface that nuance in the output.
+ *
+ * Output modes:
+ *   - Default: human-pretty, matching the spacing used by `rea check`.
+ *   - `--json`: canonical JSON object, composable with jq and future tooling.
+ *
+ * This command is read-only. It does NOT clean up stale pidfiles (the serve
+ * process is the only writer). It does NOT run the full audit verifier —
+ * `rea audit verify` is the authoritative check and is expensive on large
+ * chains; here we just report line count, last timestamp, and a cheap "last
+ * record's stored hash is non-empty" heuristic as an integrity smoke signal.
+ */
+import fs from 'node:fs';
+import { loadPolicy } from '../policy/loader.js';
+import { AUDIT_FILE, HALT_FILE, POLICY_FILE, REA_DIR, SERVE_PID_FILE, SERVE_STATE_FILE, err, exitWithMissingPolicy, log, reaPath, } from './utils.js';
+/**
+ * Tail window size for the audit summary. 64 KiB is more than enough to
+ * hold the last audit record (typical record ≪ 1 KiB) but small enough
+ * that reading it never spikes memory even on a multi-hundred-MB chain.
+ */
+const AUDIT_TAIL_WINDOW_BYTES = 64 * 1024;
+/**
+ * Strip every ASCII control code (C0 plus DEL) from a string. Defense
+ * against ANSI/OSC escape injection when a disk-controlled field reaches
+ * the operator's terminal via `console.log` in pretty mode.
+ *
+ * This is strict: every byte in 0x00-0x1F plus 0x7F is replaced with `?`.
+ * That drops CR/LF/TAB inside fields, which is fine — the fields this
+ * helper guards (halt_reason, session_id, started_at, last_timestamp,
+ * profile) are short identifiers or trimmed reasons, not multi-line
+ * narratives. Preserving TAB/LF would reopen the ESC+... attack surface
+ * because ANSI sequences begin with ESC (0x1B).
+ *
+ * SECURITY: Only pretty-print paths call this — JSON mode must not, since
+ * JSON.stringify already escapes control chars safely (`\u0000`), and a
+ * double-pass would corrupt legitimate audit values for downstream jq
+ * consumers.
+ *
+ * Exported so unit tests can assert the exact sanitization behavior.
+ */
+export function sanitizeForTerminal(value) {
+    return value.replace(/[\x00-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2028\u2029\u2066-\u2069]/g, '?');
+}
+/**
+ * Null-safe wrapper for {@link sanitizeForTerminal} so call sites don't
+ * need a ternary at every disk-sourced field.
+ */
+function safePretty(value) {
+    if (value === null || value === undefined)
+        return null;
+    return sanitizeForTerminal(value);
+}
+/** Returns true if the OS confirms a live process at `pid`. */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // Signal 0 tests existence without delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        // EPERM means the process exists but belongs to another user — for our
+        // purposes (was-it-started-on-this-machine), that still counts as alive.
+        // ESRCH means no such process.
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+function readPidfile(baseDir) {
+    const p = reaPath(baseDir, SERVE_PID_FILE);
+    try {
+        const raw = fs.readFileSync(p, 'utf8').trim();
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0)
+            return null;
+        return n;
+    }
+    catch {
+        return null;
+    }
+}
+function readServeState(baseDir) {
+    const p = reaPath(baseDir, SERVE_STATE_FILE);
+    try {
+        const raw = fs.readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            session_id: typeof parsed.session_id === 'string' ? parsed.session_id : null,
+            started_at: typeof parsed.started_at === 'string' ? parsed.started_at : null,
+            metrics_port: typeof parsed.metrics_port === 'number' && Number.isInteger(parsed.metrics_port)
+                ? parsed.metrics_port
+                : null,
+        };
+    }
+    catch {
+        return { session_id: null, started_at: null, metrics_port: null };
+    }
+}
+function probeServe(baseDir) {
+    const pid = readPidfile(baseDir);
+    if (pid === null) {
+        // No pidfile — serve isn't running (at least not via `rea serve`).
+        return {
+            running: false,
+            pid: null,
+            stale: false,
+            session_id: null,
+            started_at: null,
+            metrics_port: null,
+        };
+    }
+    const alive = isProcessAlive(pid);
+    const state = readServeState(baseDir);
+    return {
+        running: alive,
+        pid,
+        stale: !alive,
+        session_id: state.session_id,
+        started_at: state.started_at,
+        metrics_port: state.metrics_port,
+    };
+}
+/**
+ * Count newline bytes in the file via a streaming read. O(file-size) in
+ * wall-clock but O(chunk-size) in memory — production chains can reach
+ * hundreds of MB; we must never hold the full file in a Buffer.
+ */
+function countLinesStreaming(filePath) {
+    let count = 0;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(64 * 1024);
+        let bytesRead = 0;
+        while ((bytesRead = fs.readSync(fd, buf, 0, buf.length, null)) > 0) {
+            for (let i = 0; i < bytesRead; i++) {
+                if (buf[i] === 0x0a)
+                    count++;
+            }
+        }
+    }
+    catch {
+        // Partial result is still useful; return whatever we counted.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignored */
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Read up to `windowBytes` from the end of the file. Uses `pread` via a
+ * positioned `readSync` so we never materialize more than the window into
+ * memory, regardless of file size. The window is intentionally generous
+ * (default 64 KiB) vs. a typical ~200-byte audit record so the tail line
+ * is always fully represented.
+ */
+function readTailBytes(filePath, windowBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (stat.size === 0)
+            return '';
+        const toRead = Math.min(windowBytes, stat.size);
+        const buf = Buffer.alloc(toRead);
+        const start = stat.size - toRead;
+        fs.readSync(fd, buf, 0, toRead, start);
+        return buf.toString('utf8');
+    }
+    catch {
+        return '';
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignored */
+            }
+        }
+    }
+}
+/**
+ * Quickly compute audit stats without running the full verifier. Memory
+ * posture:
+ *   - Line count is computed with a streaming newline scan (64 KiB chunk
+ *     buffer, regardless of total file size).
+ *   - `last_timestamp` + `tail_hash_looks_valid` come from a 64-KiB tail
+ *     window read via `readSync` at a positive offset — we never
+ *     materialize the full file.
+ *
+ * Missing / corrupt / empty files degrade to "present: false" or
+ * "lines: 0".
+ */
+function summarizeAudit(baseDir) {
+    const p = reaPath(baseDir, AUDIT_FILE);
+    if (!fs.existsSync(p)) {
+        return { present: false, lines: 0, last_timestamp: null, tail_hash_looks_valid: false };
+    }
+    // Streaming line count — O(file-size) CPU, O(chunk) memory.
+    // NOTE: countLinesStreaming and readTailBytes open the file independently.
+    // A concurrent append between the two opens can produce a `lines` count
+    // that is one higher than the tail record implies. This is a display-only
+    // function; the inconsistency is cosmetic and intentionally accepted.
+    const lineCount = countLinesStreaming(p);
+    // Tail-window scan for the last JSON record. If the last window isn't
+    // large enough to contain a full record (extremely rare: record >64 KiB),
+    // we degrade gracefully — the JSON parse just fails and we emit null.
+    const tailWindow = readTailBytes(p, AUDIT_TAIL_WINDOW_BYTES);
+    if (tailWindow.length === 0) {
+        return {
+            present: true,
+            lines: lineCount,
+            last_timestamp: null,
+            tail_hash_looks_valid: false,
+        };
+    }
+    // Find the last complete line. The first line in the window may be a
+    // partial record (we sliced mid-line); ignore it by finding the last
+    // newline-terminated segment.
+    const windowLines = tailWindow.split('\n').filter((line) => line.length > 0);
+    const tail = windowLines[windowLines.length - 1];
+    let last_timestamp = null;
+    let tail_hash_looks_valid = false;
+    if (tail !== undefined) {
+        try {
+            const rec = JSON.parse(tail);
+            if (typeof rec.timestamp === 'string')
+                last_timestamp = rec.timestamp;
+            if (typeof rec.hash === 'string' && /^[0-9a-f]{64}$/i.test(rec.hash)) {
+                tail_hash_looks_valid = true;
+            }
+        }
+        catch {
+            // Broken last line — leave both as default.
+        }
+    }
+    return { present: true, lines: lineCount, last_timestamp, tail_hash_looks_valid };
+}
+/**
+ * Build the canonical payload. Separate from print paths so the JSON and
+ * pretty outputs stay in lockstep.
+ */
+export function computeStatusPayload(baseDir) {
+    const policyPath = reaPath(baseDir, POLICY_FILE);
+    if (!fs.existsSync(policyPath)) {
+        exitWithMissingPolicy(policyPath);
+    }
+    const policy = loadPolicy(baseDir);
+    const haltPath = reaPath(baseDir, HALT_FILE);
+    const haltActive = fs.existsSync(haltPath);
+    let haltReason = null;
+    if (haltActive) {
+        try {
+            haltReason = fs.readFileSync(haltPath, 'utf8').trim();
+        }
+        catch {
+            haltReason = null;
+        }
+    }
+    return {
+        base_dir: baseDir,
+        serve: probeServe(baseDir),
+        policy: {
+            profile: policy.profile,
+            autonomy_level: policy.autonomy_level,
+            blocked_paths_count: policy.blocked_paths.length,
+            codex_required: policy.review?.codex_required !== false,
+            halt_active: haltActive,
+            halt_reason: haltReason,
+        },
+        audit: summarizeAudit(baseDir),
+    };
+}
+function printPretty(payload) {
+    // Every terminal-bound string field flows through `safePretty` or
+    // `sanitizeForTerminal` to prevent ANSI/OSC escape injection. This
+    // includes `base_dir`: although it originates from `process.cwd()`, the
+    // filesystem path is operator-controlled and a maliciously named directory
+    // can embed ESC/OSC bytes that inject terminal sequences when printed.
+    const p = payload.policy;
+    const s = payload.serve;
+    const a = payload.audit;
+    const baseDir = sanitizeForTerminal(payload.base_dir);
+    const profile = sanitizeForTerminal(p.profile);
+    const autonomy = sanitizeForTerminal(p.autonomy_level);
+    const haltReason = safePretty(p.halt_reason);
+    const sessionId = safePretty(s.session_id);
+    const startedAt = safePretty(s.started_at);
+    const lastTimestamp = safePretty(a.last_timestamp);
+    console.log('');
+    log(`Status — ${baseDir}`);
+    console.log('');
+    console.log('  Policy');
+    console.log(`    Profile:            ${profile}`);
+    console.log(`    Autonomy:           ${autonomy}`);
+    console.log(`    Blocked paths:      ${p.blocked_paths_count} entries`);
+    console.log(`    Codex required:     ${p.codex_required ? 'yes' : 'no'}`);
+    if (p.halt_active) {
+        console.log(`    HALT:               ACTIVE`);
+        if (haltReason !== null) {
+            console.log(`                        ${haltReason}`);
+        }
+    }
+    else {
+        console.log(`    HALT:               inactive`);
+    }
+    console.log('');
+    console.log('  rea serve');
+    if (!s.running) {
+        if (s.pid !== null && s.stale) {
+            console.log(`    Running:            no (stale pidfile — pid ${s.pid})`);
+        }
+        else {
+            console.log(`    Running:            no`);
+        }
+    }
+    else {
+        console.log(`    Running:            yes (pid ${s.pid ?? '?'})`);
+        if (sessionId !== null) {
+            console.log(`    Session id:         ${sessionId}`);
+        }
+        if (startedAt !== null) {
+            console.log(`    Started at:         ${startedAt}`);
+        }
+        if (s.metrics_port !== null) {
+            console.log(`    Metrics endpoint:   http://127.0.0.1:${s.metrics_port}/metrics`);
+        }
+        else {
+            console.log(`    Metrics endpoint:   disabled (set REA_METRICS_PORT to enable)`);
+        }
+    }
+    console.log('');
+    console.log('  Audit log');
+    if (!a.present) {
+        console.log(`    State:              not yet written`);
+    }
+    else if (a.lines === 0) {
+        console.log(`    State:              empty`);
+    }
+    else {
+        console.log(`    Lines:              ${a.lines}`);
+        if (lastTimestamp !== null) {
+            console.log(`    Last record at:     ${lastTimestamp}`);
+        }
+        console.log(`    Tail hash:          ${a.tail_hash_looks_valid ? 'looks valid' : 'unexpected shape — run `rea audit verify`'}`);
+    }
+    console.log('');
+}
+function printJson(payload) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+export function runStatus(options = {}) {
+    const baseDir = process.cwd();
+    let payload;
+    try {
+        payload = computeStatusPayload(baseDir);
+    }
+    catch (e) {
+        // `exitWithMissingPolicy` already handles the missing-policy path; any
+        // other loadPolicy error reaches here.
+        err(`Failed to build status: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    if (options.json === true) {
+        printJson(payload);
+    }
+    else {
+        printPretty(payload);
+    }
+}
+// Exported so tests can construct the expected directory without duplicating
+// the path segment.
+export const INTERNAL = { REA_DIR };

package/dist/cli/utils.d.ts

@@ -9,6 +9,10 @@ export declare const POLICY_FILE = "policy.yaml";
 export declare const REGISTRY_FILE = "registry.yaml";
 export declare const HALT_FILE = "HALT";
 export declare const AUDIT_FILE = "audit.jsonl";
+/** Pidfile written by `rea serve` for `rea status` introspection (G5). */
+export declare const SERVE_PID_FILE = "serve.pid";
+/** State file written by `rea serve` carrying session_id + start metadata (G5). */
+export declare const SERVE_STATE_FILE = "serve.state.json";
 export declare function reaPath(baseDir: string, ...segments: string[]): string;
 /**
  * Standard log prefix so users notice the transition from reagent → rea.

package/dist/cli/utils.js

@@ -23,6 +23,10 @@ export const POLICY_FILE = 'policy.yaml';
 export const REGISTRY_FILE = 'registry.yaml';
 export const HALT_FILE = 'HALT';
 export const AUDIT_FILE = 'audit.jsonl';
+/** Pidfile written by `rea serve` for `rea status` introspection (G5). */
+export const SERVE_PID_FILE = 'serve.pid';
+/** State file written by `rea serve` carrying session_id + start metadata (G5). */
+export const SERVE_STATE_FILE = 'serve.state.json';
 export function reaPath(baseDir, ...segments) {
     return path.join(baseDir, REA_DIR, ...segments);
 }

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

@@ -1,9 +1,24 @@
 export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Callback invoked on every circuit state transition (G5). The constructor
+ * can wire this to a structured logger and/or a metrics gauge so state
+ * changes are observable without requiring the breaker itself to depend on
+ * those modules.
+ */
+export type CircuitStateChangeListener = (event: {
+    server: string;
+    from: CircuitState;
+    to: CircuitState;
+    reason: 'failure_threshold' | 'cooldown_elapsed' | 'recovered' | 'half_open_failed';
+    retryAt?: string;
+}) => void;
 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;
+    /** Optional listener for state transitions. See {@link CircuitStateChangeListener}. */
+    onStateChange?: CircuitStateChangeListener;
 }
 export interface CircuitStatus {
     state: CircuitState;
@@ -29,7 +44,9 @@ interface CircuitEntry {
 export declare class CircuitBreaker {
     private circuits;
     private defaultOptions;
+    private readonly onStateChange;
     constructor(defaults?: CircuitBreakerOptions);
+    private notify;
     private getOrCreate;
     /**
      * Returns null if the call may proceed, or a CircuitStatus if the circuit is open.

package/dist/gateway/circuit-breaker.js

@@ -10,11 +10,23 @@
 export class CircuitBreaker {
     circuits = new Map();
     defaultOptions;
+    onStateChange;
     constructor(defaults = {}) {
         this.defaultOptions = {
             failureThreshold: defaults.failureThreshold ?? 5,
             cooldownMs: defaults.cooldownMs ?? 30_000,
         };
+        this.onStateChange = defaults.onStateChange;
+    }
+    notify(event) {
+        if (this.onStateChange === undefined)
+            return;
+        try {
+            this.onStateChange(event);
+        }
+        catch {
+            // Listeners must never break the breaker. Swallow.
+        }
     }
     getOrCreate(serverName) {
         let entry = this.circuits.get(serverName);
@@ -43,7 +55,12 @@ export class CircuitBreaker {
             if (elapsed >= entry.cooldownMs) {
                 entry.state = 'half-open';
                 entry.consecutiveFailures = 0;
-                console.error(`[rea] circuit-breaker: "${serverName}" transitioned open → half-open (probing recovery)`);
+                this.notify({
+                    server: serverName,
+                    from: 'open',
+                    to: 'half-open',
+                    reason: 'cooldown_elapsed',
+                });
                 return null;
             }
             const retryAt = new Date((entry.openedAt ?? 0) + entry.cooldownMs).toISOString();
@@ -61,7 +78,12 @@ export class CircuitBreaker {
             entry.state = 'closed';
             entry.consecutiveFailures = 0;
             entry.openedAt = null;
-            console.error(`[rea] circuit-breaker: "${serverName}" recovered — circuit closed`);
+            this.notify({
+                server: serverName,
+                from: 'half-open',
+                to: 'closed',
+                reason: 'recovered',
+            });
         }
         else if (entry.state === 'closed') {
             entry.consecutiveFailures = 0;
@@ -71,13 +93,20 @@ export class CircuitBreaker {
         const entry = this.getOrCreate(serverName);
         if (entry.state === 'open')
             return;
+        const previous = entry.state;
         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}`);
+            this.notify({
+                server: serverName,
+                from: previous,
+                to: 'open',
+                reason: previous === 'half-open' ? 'half_open_failed' : 'failure_threshold',
+                retryAt,
+            });
         }
     }
     getCircuit(serverName) {

package/dist/gateway/downstream-pool.d.ts

@@ -7,6 +7,7 @@
  */
 import { DownstreamConnection, type DownstreamToolInfo } from './downstream.js';
 import type { Registry } from '../registry/types.js';
+import type { Logger } from './log.js';
 export interface PrefixedTool extends DownstreamToolInfo {
     /** Server name, not prefixed. */
     server: string;
@@ -15,7 +16,7 @@ export interface PrefixedTool extends DownstreamToolInfo {
 }
 export declare class DownstreamPool {
     private readonly connections;
-    constructor(registry: Registry);
+    constructor(registry: Registry, logger?: Logger);
     get size(): number;
     connectAll(): Promise<void>;
     /**

package/dist/gateway/downstream-pool.js

@@ -8,11 +8,11 @@
 import { DownstreamConnection } from './downstream.js';
 export class DownstreamPool {
     connections = new Map();
-    constructor(registry) {
+    constructor(registry, logger) {
         for (const server of registry.servers) {
             if (!server.enabled)
                 continue;
-            this.connections.set(server.name, new DownstreamConnection(server));
+            this.connections.set(server.name, new DownstreamConnection(server, logger));
         }
     }
     get size() {

package/dist/gateway/downstream.d.ts

@@ -36,6 +36,7 @@
  * a transport error could double-post. We leave the decision to the caller.
  */
 import type { RegistryServer } from '../registry/types.js';
+import type { Logger } from './log.js';
 export interface DownstreamToolInfo {
     name: string;
     description?: string;
@@ -43,15 +44,44 @@ export interface DownstreamToolInfo {
 }
 /**
  * Build the child env by layering:
- *   allowlist → registry env_passthrough → registry env.
+ *   allowlist → registry env_passthrough → interpolated registry env.
  * Later entries win. Missing host values are skipped so `process.env[name]`
  * being undefined does not serialize as the literal string "undefined".
  *
+ * The explicit `env:` map may contain `${VAR}` placeholders (see
+ * `registry/interpolate.ts` for the exact grammar). Placeholders referencing
+ * unset host vars are returned via the `missing` array — the caller MUST
+ * refuse to spawn the server if `missing.length > 0`, otherwise the child
+ * receives unresolved `${...}` strings which are nearly always wrong.
+ *
  * Exported for testing.
  */
-export declare function buildChildEnv(config: RegistryServer, hostEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export interface BuiltChildEnv {
+    /** Fully resolved env to pass to the child transport. */
+    env: Record<string, string>;
+    /**
+     * Names of `${VAR}` references that were not set in `hostEnv`. When
+     * non-empty, the caller MUST NOT spawn the child — mark the connection
+     * unhealthy and log each entry.
+     */
+    missing: string[];
+    /**
+     * Keys in `env` whose value is secret-bearing (either because the key
+     * name matches the secret-name heuristic, or because one of its
+     * interpolated `${VAR}` references did). Callers MUST NOT log the
+     * corresponding values.
+     */
+    secretKeys: string[];
+}
+export declare function buildChildEnv(config: RegistryServer, hostEnv?: NodeJS.ProcessEnv): BuiltChildEnv;
 export declare class DownstreamConnection {
     private readonly config;
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    private readonly logger?;
     private client;
     /**
      * Whether a reconnect has already been attempted in the CURRENT failure
@@ -63,7 +93,13 @@ export declare class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     private lastReconnectAt;
     private health;
-    constructor(config: RegistryServer);
+    constructor(config: RegistryServer, 
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    logger?: Logger | undefined);
     get name(): string;
     get isHealthy(): boolean;
     connect(): Promise<void>;