@bookedsolid/rea 0.1.0 → 0.2.0

package/dist/gateway/reviewers/codex.js

@@ -0,0 +1,80 @@
+/**
+ * Codex adversarial reviewer adapter (G11.2).
+ *
+ * ## Why this class throws from `review()`
+ *
+ * The actual Codex review path is the `codex-adversarial` agent shipped under
+ * `.claude/agents/`, invoked from Claude Code via the `/codex-review` slash
+ * command (which eventually reaches the Codex plugin's
+ * `/codex:adversarial-review`). None of that is importable from TS — the
+ * agent runtime is the harness, not a library.
+ *
+ * `CodexReviewer` exists so:
+ *
+ *   1. `selectReviewer()` can return a typed reviewer handle with a stable
+ *      `name`/`version` that the audit log and CLI can surface.
+ *   2. `isAvailable()` can cheaply probe the CLI without invoking a review.
+ *   3. G11.3 (startup probe) and G11.4 (no-Codex policy) have something to
+ *      type-check against now, so the broader flow can land without waiting
+ *      for an in-process Codex SDK that may never ship.
+ *
+ * If we ever get a native Codex TS client, `review()` becomes real and this
+ * comment block goes away. Until then: treat a Codex selection as
+ * "dispatch to the agent", not "await reviewer.review(...)".
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Upper bound on `codex --version` so a hung CLI can't stall the push gate. */
+const VERSION_PROBE_TIMEOUT_MS = 2_000;
+/** Token used as `version` when we never successfully read one. */
+const UNKNOWN_VERSION = 'unknown';
+const defaultExec = (file, args, options) => execFileAsync(file, [...args], options);
+export class CodexReviewer {
+    name = 'codex';
+    exec;
+    cachedVersion;
+    constructor(opts = {}) {
+        this.exec = opts.exec ?? defaultExec;
+    }
+    /**
+     * Lazily populated via `codex --version`. We don't block construction on
+     * the probe because the selector calls `isAvailable()` before it commits
+     * to Codex, so we'll have a fresh value by the time anything reads it.
+     */
+    get version() {
+        return this.cachedVersion ?? UNKNOWN_VERSION;
+    }
+    async isAvailable() {
+        try {
+            const { stdout } = await this.exec('codex', ['--version'], {
+                timeout: VERSION_PROBE_TIMEOUT_MS,
+            });
+            // Cache on success so `version` is non-`unknown` the moment the
+            // selector picks this reviewer.
+            this.cachedVersion = stdout.trim() || UNKNOWN_VERSION;
+            return true;
+        }
+        catch {
+            // Any failure — timeout, ENOENT, non-zero exit — means we shouldn't
+            // route through Codex. Callers don't need the reason; the selector
+            // logs why it fell back.
+            return false;
+        }
+    }
+    /**
+     * Not invokable from TS — see the file header. The selector contract is
+     * "CodexReviewer handles mean dispatch to the codex-adversarial agent";
+     * if a caller ignores that and awaits this, we throw loudly rather than
+     * silently produce a bad `ReviewResult`.
+     *
+     * TODO(0.3.0): when Codex ships a native TS client, this path will
+     * actually run the review. At that point, instrument with
+     * `recordTelemetry` the same way `ClaudeSelfReviewer.review()` does
+     * today (G11.5). The throwing placeholder below is deliberately NOT
+     * instrumented — there is nothing to measure.
+     */
+    async review(_req) {
+        throw new Error('CodexReviewer.review() is invoked via the codex-adversarial agent, not directly from TS');
+    }
+}

package/dist/gateway/reviewers/select.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Reviewer selector (G11.2).
+ *
+ * Single source of truth for "which adversarial reviewer should run against
+ * this branch?" Downstream callers get back a reviewer handle plus two
+ * audit-friendly signals: `degraded` (is this a fallback?) and `reason`
+ * (why did we pick this one?).
+ *
+ * Precedence, high to low:
+ *
+ *   1. `REA_REVIEWER` env var — explicit operator choice wins over all policy
+ *   2. `registry.reviewer` — second-wins operator pin in `.rea/registry.yaml`
+ *   3. `policy.review.codex_required === false` — first-class no-Codex mode
+ *      (G11.4 semantics). ClaudeSelfReviewer is NOT degraded here because
+ *      the operator explicitly chose this lane.
+ *   4. Default: prefer Codex, fall back to ClaudeSelfReviewer with
+ *      `degraded: true` if Codex is unavailable.
+ *   5. Both unavailable → throw. The push gate has an audited escape hatch
+ *      (`REA_SKIP_CODEX_REVIEW`, G11.1) for when that's legitimately the
+ *      operator's intent.
+ *
+ * The caller decides what to do with the result. The audit record should
+ * always capture `reviewer.name`, `reviewer.version`, `degraded`, and
+ * `reason` verbatim.
+ */
+import type { Policy } from '../../policy/types.js';
+import type { Registry } from '../../registry/types.js';
+import type { AdversarialReviewer } from './types.js';
+export interface SelectionResult {
+    reviewer: AdversarialReviewer;
+    /**
+     * `true` iff we fell back to a less-preferred reviewer than the operator
+     * would have gotten in the default Codex-available case.
+     */
+    degraded: boolean;
+    /** Short machine-readable code — one of the literals below. */
+    reason: SelectionReason;
+}
+/**
+ * Closed enum of reasons so downstream code can switch on it without
+ * stringly-typed comparisons. Stable — adding a new case is fine; renaming
+ * is a breaking change to audit consumers.
+ */
+export type SelectionReason = 'env:REA_REVIEWER' | 'registry.reviewer' | 'policy.review.codex_required=false' | 'default:codex-available' | 'default:codex-unavailable-fallback';
+/**
+ * Narrow seam so tests can stub reviewer construction without touching
+ * process env or the Anthropic SDK.
+ */
+export interface SelectorDeps {
+    makeCodex: () => AdversarialReviewer;
+    makeClaudeSelf: () => AdversarialReviewer;
+}
+/**
+ * Thrown when neither Codex nor ClaudeSelfReviewer can run. Keep the
+ * message actionable — the operator should know which knobs to flip.
+ */
+export declare class NoReviewerAvailableError extends Error {
+    constructor();
+}
+/**
+ * Pick the reviewer for the current branch. Callers MUST await — the
+ * Codex availability probe is an exec, not a sync call.
+ */
+export declare function selectReviewer(policy: Policy, registry: Registry, env?: NodeJS.ProcessEnv, deps?: SelectorDeps): Promise<SelectionResult>;

package/dist/gateway/reviewers/select.js

@@ -0,0 +1,102 @@
+/**
+ * Reviewer selector (G11.2).
+ *
+ * Single source of truth for "which adversarial reviewer should run against
+ * this branch?" Downstream callers get back a reviewer handle plus two
+ * audit-friendly signals: `degraded` (is this a fallback?) and `reason`
+ * (why did we pick this one?).
+ *
+ * Precedence, high to low:
+ *
+ *   1. `REA_REVIEWER` env var — explicit operator choice wins over all policy
+ *   2. `registry.reviewer` — second-wins operator pin in `.rea/registry.yaml`
+ *   3. `policy.review.codex_required === false` — first-class no-Codex mode
+ *      (G11.4 semantics). ClaudeSelfReviewer is NOT degraded here because
+ *      the operator explicitly chose this lane.
+ *   4. Default: prefer Codex, fall back to ClaudeSelfReviewer with
+ *      `degraded: true` if Codex is unavailable.
+ *   5. Both unavailable → throw. The push gate has an audited escape hatch
+ *      (`REA_SKIP_CODEX_REVIEW`, G11.1) for when that's legitimately the
+ *      operator's intent.
+ *
+ * The caller decides what to do with the result. The audit record should
+ * always capture `reviewer.name`, `reviewer.version`, `degraded`, and
+ * `reason` verbatim.
+ */
+import { ClaudeSelfReviewer } from './claude-self.js';
+import { CodexReviewer } from './codex.js';
+const defaultDeps = {
+    makeCodex: () => new CodexReviewer(),
+    makeClaudeSelf: () => new ClaudeSelfReviewer(),
+};
+/**
+ * Thrown when neither Codex nor ClaudeSelfReviewer can run. Keep the
+ * message actionable — the operator should know which knobs to flip.
+ */
+export class NoReviewerAvailableError extends Error {
+    constructor() {
+        super('No adversarial reviewer is available: Codex CLI is unreachable AND ' +
+            'ANTHROPIC_API_KEY is unset. Either install/authenticate the Codex ' +
+            'CLI, export ANTHROPIC_API_KEY, or use the REA_SKIP_CODEX_REVIEW ' +
+            'audited escape hatch (G11.1) for this push.');
+        this.name = 'NoReviewerAvailableError';
+    }
+}
+function isKnownReviewer(value) {
+    return value === 'codex' || value === 'claude-self';
+}
+/**
+ * Pick the reviewer for the current branch. Callers MUST await — the
+ * Codex availability probe is an exec, not a sync call.
+ */
+export async function selectReviewer(policy, registry, env = process.env, deps = defaultDeps) {
+    // 1. Env override — operator explicitly chose. We do NOT probe
+    // availability here; if the operator said "use X", respect it and let
+    // the reviewer's own error path surface any config problem.
+    const envChoice = env['REA_REVIEWER'];
+    if (typeof envChoice === 'string' && envChoice.length > 0) {
+        if (!isKnownReviewer(envChoice)) {
+            throw new Error(`REA_REVIEWER=${envChoice} is not a known reviewer. Valid values: codex, claude-self.`);
+        }
+        return {
+            reviewer: envChoice === 'codex' ? deps.makeCodex() : deps.makeClaudeSelf(),
+            degraded: false,
+            reason: 'env:REA_REVIEWER',
+        };
+    }
+    // 2. Registry pin — same trust level as env, just written down.
+    if (registry.reviewer !== undefined) {
+        return {
+            reviewer: registry.reviewer === 'codex' ? deps.makeCodex() : deps.makeClaudeSelf(),
+            degraded: false,
+            reason: 'registry.reviewer',
+        };
+    }
+    // 3. Policy opt-in to no-Codex mode. Per G11.4, this is a first-class
+    // choice — NOT degraded. The operator has declared ClaudeSelfReviewer
+    // is good enough for this project.
+    if (policy.review?.codex_required === false) {
+        return {
+            reviewer: deps.makeClaudeSelf(),
+            degraded: false,
+            reason: 'policy.review.codex_required=false',
+        };
+    }
+    // 4. Default path — try Codex first.
+    const codex = deps.makeCodex();
+    if (await codex.isAvailable()) {
+        return { reviewer: codex, degraded: false, reason: 'default:codex-available' };
+    }
+    // 5. Codex unavailable — fall back to ClaudeSelfReviewer if we can.
+    const claude = deps.makeClaudeSelf();
+    if (await claude.isAvailable()) {
+        return {
+            reviewer: claude,
+            // Crucial: in this branch the operator wanted Codex and got a
+            // same-model fallback instead. Audit must flag it.
+            degraded: true,
+            reason: 'default:codex-unavailable-fallback',
+        };
+    }
+    throw new NoReviewerAvailableError();
+}

package/dist/gateway/reviewers/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Adversarial reviewer interface — shared shape for every pluggable reviewer
+ * rea knows how to dispatch through `hooks/push-review-gate.sh`.
+ *
+ * The push gate today hard-codes Codex. G11.2 abstracts the reviewer so we
+ * have a real fallback (same-model Claude self-review) when Codex is
+ * rate-limited or otherwise unavailable, and so G11.3/G11.4/G11.5 have a
+ * stable contract to type-check against.
+ *
+ * The types live in their own file so callers (the selector, future
+ * middleware, docs tooling) can import them without dragging in the runtime
+ * adapters (`codex.ts`, `claude-self.ts`).
+ */
+/** Verdict returned by a reviewer after inspecting a diff. */
+export type ReviewVerdict = 'pass' | 'concerns' | 'blocking' | 'error';
+/**
+ * One finding surfaced by a reviewer. Intentionally loose on optional
+ * positional fields — `line` and `start_line` are mutually useful but not
+ * every reviewer surfaces both, and we accept either (or neither when the
+ * finding is whole-file).
+ */
+export interface ReviewFinding {
+    category: 'security' | 'correctness' | 'edge-case' | 'test-gap' | 'api-design' | 'performance';
+    severity: 'high' | 'medium' | 'low';
+    file: string;
+    line?: number;
+    start_line?: number;
+    issue: string;
+    evidence?: string;
+    suggested_fix?: string;
+}
+/**
+ * Single-reviewer result. One of these is what the push gate ultimately acts
+ * on. `degraded` is a first-class signal — `false` means the operator is
+ * getting the review they asked for; `true` means we fell back (same-model
+ * check, truncated diff, etc.) and the audit log should reflect that.
+ */
+export interface ReviewResult {
+    /** Short reviewer id — e.g. `codex`, `claude-self`. Matches the class `name`. */
+    reviewer_name: string;
+    /** Model / plugin version used to produce this review. */
+    reviewer_version: string;
+    verdict: ReviewVerdict;
+    findings: ReviewFinding[];
+    /** One-sentence summary. */
+    summary: string;
+    /** `true` when this reviewer is a fallback for a preferred one. */
+    degraded: boolean;
+    /** Populated when `verdict === 'error'`. Never set on a successful review. */
+    error?: string;
+}
+/** Input shape passed to every reviewer. */
+export interface ReviewRequest {
+    diff: string;
+    commit_log: string;
+    branch: string;
+    head_sha: string;
+    /** Ref the branch was diffed against (e.g. `origin/main`). */
+    target: string;
+    /** Optional extra paths the reviewer may want to pull into context. */
+    context_hints?: string[];
+}
+/**
+ * Implementations live in `codex.ts` and `claude-self.ts`. Future entries
+ * (e.g. a cross-model OpenAI GPT-5 reviewer) land as additional classes that
+ * conform to this interface — the selector decides which one runs.
+ */
+export interface AdversarialReviewer {
+    /** Short id — `codex`, `claude-self`, etc. Used in audit records. */
+    readonly name: string;
+    /** Model id or plugin version. Cached at construction. */
+    readonly version: string;
+    /**
+     * Cheap reachability check. MUST be side-effect-free beyond a bounded
+     * syscall / env read, and MUST resolve within a couple of seconds so the
+     * selector can fall back quickly.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Run the review. Implementations that delegate to an out-of-process agent
+     * (see `CodexReviewer`) may throw rather than return `ReviewResult` — the
+     * caller is expected to check the reviewer's class before dispatching.
+     */
+    review(req: ReviewRequest): Promise<ReviewResult>;
+}

package/dist/gateway/reviewers/types.js

@@ -0,0 +1,14 @@
+/**
+ * Adversarial reviewer interface — shared shape for every pluggable reviewer
+ * rea knows how to dispatch through `hooks/push-review-gate.sh`.
+ *
+ * The push gate today hard-codes Codex. G11.2 abstracts the reviewer so we
+ * have a real fallback (same-model Claude self-review) when Codex is
+ * rate-limited or otherwise unavailable, and so G11.3/G11.4/G11.5 have a
+ * stable contract to type-check against.
+ *
+ * The types live in their own file so callers (the selector, future
+ * middleware, docs tooling) can import them without dragging in the runtime
+ * adapters (`codex.ts`, `claude-self.ts`).
+ */
+export {};

package/dist/gateway/server.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Upstream MCP server for `rea serve`.
+ *
+ * Architecture:
+ *
+ *   Claude Code (MCP client over stdio)
+ *     ↔ this Server (StdioServerTransport)
+ *       ↔ middleware chain
+ *         ↔ DownstreamPool
+ *           ↔ per-server StdioClientTransport
+ *             ↔ child MCP processes
+ *
+ * Every downstream tool call flows through the full middleware chain:
+ *
+ *   audit → kill-switch → tier → policy → blocked-paths → rate-limit →
+ *   circuit-breaker → injection → redact → result-size-cap → terminal
+ *
+ * The terminal middleware is a thin closure that dispatches to the pool and
+ * stores the response on `ctx.result`.
+ *
+ * Shutdown discipline: SIGTERM / SIGINT → stop accepting new calls, drain
+ * in-flight work, close the pool, exit 0. No orphaned child processes.
+ *
+ * ## Zero-server mode
+ *
+ * A gateway with zero downstream servers is a valid state — it means the
+ * consumer just ran `rea init` and has not yet populated `.rea/registry.yaml`.
+ * We boot normally, respond to `listTools` with an empty catalog, and log
+ * a pointer. Do not crash — breaking the daemon on an empty registry would
+ * turn first-run into a puzzle.
+ */
+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';
+export interface GatewayOptions {
+    baseDir: string;
+    policy: Policy;
+    registry: Registry;
+}
+export interface GatewayHandle {
+    /** Expose the Server for test harnesses that attach InMemoryTransport. */
+    server: Server;
+    /** Connect the Server to the provided transport (defaults to stdio). */
+    start(transport?: unknown): Promise<void>;
+    /** Graceful shutdown — drain in-flight, close pool, close server. */
+    stop(): Promise<void>;
+    /** Exposed for tests. */
+    pool: DownstreamPool;
+}
+export declare function createGateway(opts: GatewayOptions): GatewayHandle;

package/dist/gateway/server.js

@@ -0,0 +1,258 @@
+/**
+ * Upstream MCP server for `rea serve`.
+ *
+ * Architecture:
+ *
+ *   Claude Code (MCP client over stdio)
+ *     ↔ this Server (StdioServerTransport)
+ *       ↔ middleware chain
+ *         ↔ DownstreamPool
+ *           ↔ per-server StdioClientTransport
+ *             ↔ child MCP processes
+ *
+ * Every downstream tool call flows through the full middleware chain:
+ *
+ *   audit → kill-switch → tier → policy → blocked-paths → rate-limit →
+ *   circuit-breaker → injection → redact → result-size-cap → terminal
+ *
+ * The terminal middleware is a thin closure that dispatches to the pool and
+ * stores the response on `ctx.result`.
+ *
+ * Shutdown discipline: SIGTERM / SIGINT → stop accepting new calls, drain
+ * in-flight work, close the pool, exit 0. No orphaned child processes.
+ *
+ * ## Zero-server mode
+ *
+ * A gateway with zero downstream servers is a valid state — it means the
+ * consumer just ran `rea init` and has not yet populated `.rea/registry.yaml`.
+ * We boot normally, respond to `listTools` with an empty catalog, and log
+ * a pointer. Do not crash — breaking the daemon on an empty registry would
+ * turn first-run into a puzzle.
+ */
+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 { DownstreamPool, splitPrefixed } from './downstream-pool.js';
+import { createAuditMiddleware } from './middleware/audit.js';
+import { createKillSwitchMiddleware } from './middleware/kill-switch.js';
+import { createTierMiddleware } from './middleware/tier.js';
+import { createPolicyMiddleware } from './middleware/policy.js';
+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 { wrapRegex } from './redact-safe/match-timeout.js';
+import { createResultSizeCapMiddleware } from './middleware/result-size-cap.js';
+import { executeChain } from './middleware/chain.js';
+import { RateLimiter } from './rate-limiter.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { currentSessionId } from './session.js';
+import { InvocationStatus, Tier } from '../policy/types.js';
+import { log } from '../cli/utils.js';
+/**
+ * Build the ordered middleware chain used on every CallToolRequest.
+ * Order is prescriptive — DO NOT reorder without reading THREAT_MODEL.md §
+ * "Middleware ordering". The existing unit tests in
+ * `src/gateway/middleware/chain.test.ts` encode the semantic contract.
+ */
+/**
+ * G3: compile user-supplied redact patterns (already safe-regex-cleared by
+ * the policy loader) into `SafeRegex` instances with the configured timeout.
+ * The loader guarantees the regex source compiles, so we only catch errors
+ * defensively.
+ */
+function compileUserRedactPatterns(policy, matchTimeoutMs) {
+    const entries = policy.redact?.patterns ?? [];
+    const out = [];
+    for (const entry of entries) {
+        try {
+            const compiled = new RegExp(entry.regex, entry.flags);
+            out.push({
+                name: entry.name,
+                source: 'user',
+                safe: wrapRegex(compiled, { timeoutMs: matchTimeoutMs }),
+            });
+        }
+        catch (err) {
+            // Loader already validated these — warn and drop if an unreachable
+            // corner case ever slips through.
+            log(`[rea] WARN: skipping malformed user redact pattern "${entry.name}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return out;
+}
+function buildMiddlewareChain(opts) {
+    const { baseDir, policy } = opts;
+    const matchTimeoutMs = policy.redact?.match_timeout_ms ?? 100;
+    const userPatterns = compileUserRedactPatterns(policy, matchTimeoutMs);
+    return [
+        createAuditMiddleware(baseDir, policy),
+        createKillSwitchMiddleware(baseDir),
+        createTierMiddleware(),
+        createPolicyMiddleware(policy, undefined, baseDir),
+        createBlockedPathsMiddleware(policy, baseDir),
+        createRateLimitMiddleware(new RateLimiter()),
+        createCircuitBreakerMiddleware(new CircuitBreaker()),
+        createInjectionMiddleware(policy.injection_detection === 'warn' ? 'warn' : 'block', {
+            matchTimeoutMs,
+        }),
+        createRedactMiddleware({ matchTimeoutMs, userPatterns }),
+        createResultSizeCapMiddleware(),
+    ];
+}
+export function createGateway(opts) {
+    const { registry } = opts;
+    const pool = new DownstreamPool(registry);
+    const server = new Server({ name: 'rea', version: '0.2.0' }, { capabilities: { tools: {} } });
+    const staticChain = buildMiddlewareChain(opts);
+    // ── Handlers ─────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        if (pool.size === 0)
+            return { tools: [] };
+        const prefixed = await pool.listAllTools();
+        return {
+            tools: prefixed.map((t) => ({
+                name: t.name,
+                description: t.description ?? `${t.server} → ${t.name.slice(t.server.length + 2)}`,
+                inputSchema: t.inputSchema ?? { type: 'object' },
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const prefixed = req.params.name;
+        const args = (req.params.arguments ?? {});
+        // Split prefix for downstream dispatch; the terminal middleware uses the
+        // full prefixed name to call the pool (which re-splits internally).
+        let serverName;
+        let toolName;
+        try {
+            const split = splitPrefixed(prefixed);
+            serverName = split.server;
+            toolName = split.tool;
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: err instanceof Error ? err.message : String(err),
+                    },
+                ],
+            };
+        }
+        const ctx = {
+            tool_name: toolName,
+            server_name: serverName,
+            arguments: args,
+            session_id: currentSessionId(),
+            status: InvocationStatus.Allowed,
+            start_time: Date.now(),
+            metadata: {},
+        };
+        const terminal = async (context) => {
+            if (context.status !== InvocationStatus.Allowed)
+                return;
+            if (pool.size === 0) {
+                context.status = InvocationStatus.Denied;
+                context.error = 'No downstream servers in .rea/registry.yaml — add one to enable proxying';
+                return;
+            }
+            try {
+                context.result = await pool.callTool(prefixed, context.arguments);
+            }
+            catch (err) {
+                context.status = InvocationStatus.Error;
+                context.error = err instanceof Error ? err.message : String(err);
+            }
+        };
+        try {
+            await executeChain([...staticChain, terminal], ctx);
+        }
+        catch (err) {
+            // executeChain will have run the audit middleware's try/finally; any
+            // error that escapes is bubbled here. Convert to an isError response.
+            ctx.status = InvocationStatus.Error;
+            ctx.error = err instanceof Error ? err.message : String(err);
+        }
+        // ── Response mapping ──────────────────────────────────────────────────
+        if (ctx.status === InvocationStatus.Denied) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: ctx.error ?? 'denied',
+                    },
+                ],
+            };
+        }
+        if (ctx.status === InvocationStatus.Error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: ctx.error ?? 'error',
+                    },
+                ],
+            };
+        }
+        // Allowed — return the downstream's raw result. Most MCP servers return
+        // a `{ content: [...] }` object already; if not, wrap in a text content.
+        if (ctx.result !== null &&
+            typeof ctx.result === 'object' &&
+            'content' in ctx.result) {
+            return ctx.result;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: typeof ctx.result === 'string' ? ctx.result : JSON.stringify(ctx.result),
+                },
+            ],
+        };
+    });
+    let started = false;
+    let stopping = false;
+    async function start(transport) {
+        if (started)
+            return;
+        started = true;
+        // 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.');
+        }
+        else {
+            try {
+                await pool.connectAll();
+            }
+            catch (err) {
+                log(`rea serve: downstream connect error: ${err instanceof Error ? err.message : err}`);
+                // Continue — individual connections may still be healthy.
+            }
+        }
+        const activeTransport = transport ?? new StdioServerTransport();
+        await server.connect(activeTransport);
+    }
+    async function stop() {
+        if (stopping)
+            return;
+        stopping = true;
+        try {
+            await server.close();
+        }
+        catch {
+            // Best-effort — may already be closed.
+        }
+        await pool.close();
+    }
+    return { server, start, stop, pool };
+}
+// Prevent TS from complaining about the unused `Tier` import when the file is
+// compiled in isolation; keeping the import pins the semantic dependency edge
+// for future middleware that may want to inspect the tier in terminal.
+void Tier;

package/dist/gateway/session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Per-process session identifier. One `rea serve` invocation = one session_id.
+ * Matches how Claude Code's long-running sessions work today. Revisit when we
+ * add a streamable-HTTP transport that might serve multiple reconnecting
+ * clients.
+ */
+export declare function currentSessionId(): string;
+/** Exposed for tests only — resets the module-level id. */
+export declare function __resetSessionForTests(): void;