rea-agents 4.0.1 → 5.0.0

package/dist/browser/execution/CdpWebRuntimeProvider.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { err, ok } from "../../domain/result.js";
+import { webExecutionSchema, } from "../../domain/webExecution.js";
+import { webEventListenersSchema, } from "../../domain/webEventListeners.js";
+import { CDP_BROWSER_PROVIDER_IDENTITY } from "../providerIdentities.js";
+import { CdpRuntimeSession } from "./CdpRuntimeSession.js";
+import { CdpRuntimeSources } from "./CdpRuntimeSources.js";
+import { captureWebExecution } from "./CdpExecutionCapture.js";
+import { captureWebEventListeners, eventListenerObjectGroup, } from "./CdpEventListeners.js";
+/** Native CDP integration with distinct inspection/instrumentation authority and confirmed cleanup. */
+export class CdpWebRuntimeProvider {
+    /** Identify this adapter independently of the captured browser version. */
+    identity() {
+        return CDP_BROWSER_PROVIDER_IDENTITY;
+    }
+    /** Observe one instrumented window while preserving the externally owned page. */
+    observeExecution(input, options = {}) {
+        return this.run(input, "observe_web_execution", options, webExecutionSchema, (sources) => captureWebExecution(input, sources));
+    }
+    /** Inspect one selected node's registered callback locations. */
+    inspectEventListeners(input, options = {}) {
+        const group = eventListenerObjectGroup();
+        return this.run(input, "inspect_web_event_listeners", options, webEventListenersSchema, (sources) => captureWebEventListeners(input, sources, group), group);
+    }
+    async run(input, operation, options, schema, capture, group) {
+        let session;
+        let result;
+        try {
+            session = await CdpRuntimeSession.open(input, operation, options);
+            result = ok(schema.parse(await capture(new CdpRuntimeSources(session))));
+        }
+        catch (cause) {
+            result = err(cause instanceof AnalysisError
+                ? cause
+                : cause instanceof z.ZodError
+                    ? new AnalysisOutputError(operation, cause.message)
+                    : new ProviderAdapterError(this.identity().id, operation, {
+                        cause,
+                    }));
+        }
+        if (session !== undefined) {
+            const failure = await session.close(result.ok ? undefined : result.error, group);
+            if (failure !== undefined)
+                return err(failure);
+        }
+        return result;
+    }
+}

package/dist/browser/modules/NativeModuleResolver.js

@@ -0,0 +1,210 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../../domain/browserObservationError.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { err, ok } from "../../domain/result.js";
+import { webModuleResolutionSchema } from "../../domain/webModuleTrace.js";
+import { ProviderStartupDeadline } from "../../process/ProviderDeadline.js";
+const OPERATION = "trace_web_module_imports";
+const TIMEOUT_MS = 20000;
+const reportSchema = z.strictObject({
+    importer_url: z.string(),
+    entries: z.array(z.strictObject({
+        specifier: z.string(),
+        resolution: webModuleResolutionSchema,
+    })),
+});
+const launch = async (options) => (await import("playwright-core")).chromium.launch(options);
+/** Use native import.meta.resolve in an owned context with locally fulfilled requests. */
+export class NativeModuleResolver {
+    environment;
+    launcher;
+    constructor(environment, launcher = launch) {
+        this.environment = environment;
+        this.launcher = launcher;
+    }
+    async resolve(input, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(OPERATION));
+        const executable = this.environment.REA_BROWSER_EXECUTABLE;
+        if (executable === undefined || !isAbsolute(executable))
+            return err(new AnalysisCapabilityUnavailableError("native-module-resolver", OPERATION, "missing_browser_executable", {
+                userMessage: "Provide an absolute REA_BROWSER_EXECUTABLE for a caller-supplied Chromium browser supporting import.meta.resolve. REA installs no browser.",
+            }));
+        const deadline = new ProviderStartupDeadline(TIMEOUT_MS, options?.signal);
+        let browser;
+        let cleanup;
+        const close = () => {
+            if (cleanup === undefined && browser !== undefined)
+                cleanup = browser.close();
+            return cleanup ?? Promise.resolve();
+        };
+        const onAbort = () => {
+            if (browser !== undefined) {
+                const pending = close();
+                void pending.catch(() => undefined);
+            }
+        };
+        deadline.signal.addEventListener("abort", onAbort, { once: true });
+        let result;
+        try {
+            browser = await this.launcher({
+                executablePath: executable,
+                headless: true,
+                timeout: Math.max(1, deadline.remainingMs()),
+                handleSIGINT: false,
+                handleSIGTERM: false,
+                handleSIGHUP: false,
+                args: [
+                    "--disable-dev-shm-usage",
+                    "--disable-background-networking",
+                    "--renderer-process-limit=1",
+                    "--js-flags=--max-old-space-size=128",
+                    ...(this.environment.REA_BROWSER_NO_SANDBOX === "true"
+                        ? ["--no-sandbox"]
+                        : []),
+                ],
+            });
+            deadline.signal.throwIfAborted();
+            const context = await browser.newContext({
+                serviceWorkers: "block",
+                acceptDownloads: false,
+            });
+            const page = await context.newPage();
+            const diagnostics = [];
+            let diagnosticBytes = 0;
+            page.on("console", (message) => {
+                const text = message.text();
+                diagnosticBytes += Buffer.byteLength(text);
+                if (diagnosticBytes <= 1024 * 1024)
+                    diagnostics.push(`${message.type()}: ${text}`);
+            });
+            const requests = [];
+            const importerUrl = new URL(input.importerUrl).href;
+            const documentUrl = new URL("/.rea-module-resolver/document", importerUrl)
+                .href;
+            const transportUrl = new URL(importerUrl);
+            transportUrl.hash = "";
+            let stubSent = false;
+            await context.route("**/*", async (route) => {
+                const request = route.request();
+                if (request.resourceType() === "document" &&
+                    request.url() === documentUrl.split("#")[0]) {
+                    requests.push({
+                        url: request.url(),
+                        resource_type: "document",
+                        effect: "fulfilled",
+                    });
+                    await route.fulfill({
+                        status: 200,
+                        contentType: "text/html",
+                        body: `<!doctype html>${input.importMap === null ? "" : `<base href="${htmlAttribute(new URL(input.importMap.baseUrl).href)}"><script type="importmap">${scriptJson(input.importMap.value)}</script>`}`,
+                    });
+                }
+                else if (!stubSent &&
+                    request.resourceType() === "script" &&
+                    request.url() === transportUrl.href) {
+                    stubSent = true;
+                    requests.push({
+                        url: request.url(),
+                        resource_type: "script",
+                        effect: "fulfilled",
+                    });
+                    await route.fulfill({
+                        status: 200,
+                        contentType: "text/javascript",
+                        headers: { "Access-Control-Allow-Origin": "*" },
+                        body: `if (typeof import.meta.resolve !== "function") {globalThis.__reaModuleUnsupported = true;} else {globalThis.__reaModuleResult = {importer_url: import.meta.url, entries: ${scriptJson(input.specifiers)}.map(specifier => {try {return {specifier, resolution: {state: "resolved", url: import.meta.resolve(specifier)}}} catch (error) {return {specifier, resolution: {state: "rejected", message: String(error)}}}})};}`,
+                    });
+                }
+                else {
+                    requests.push({
+                        url: request.url(),
+                        resource_type: request.resourceType(),
+                        effect: "blocked",
+                    });
+                    await route.abort();
+                }
+            });
+            await page.goto(documentUrl, {
+                timeout: Math.max(1, deadline.remainingMs()),
+            });
+            await page.evaluate(`{const script = document.createElement("script"); script.type = "module"; script.src = ${scriptJson(importerUrl)}; script.onerror = () => {globalThis.__reaModuleFailure = "Trusted resolver stub could not be loaded in the selected context.";}; document.head.append(script);}`);
+            await page.waitForFunction(() => Reflect.has(globalThis, "__reaModuleResult") ||
+                Reflect.has(globalThis, "__reaModuleUnsupported") ||
+                Reflect.has(globalThis, "__reaModuleFailure"), undefined, { timeout: Math.max(1, deadline.remainingMs()) });
+            const unsupported = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleUnsupported"));
+            if (unsupported === true)
+                throw new AnalysisCapabilityUnavailableError("native-module-resolver", OPERATION, "native_resolution_unsupported", {
+                    userMessage: `Configured Chromium ${browser.version()} does not supply import.meta.resolve; use a browser supporting native module resolution.`,
+                });
+            const raw = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleResult"));
+            const failure = await page.evaluate(() => Reflect.get(globalThis, "__reaModuleFailure"));
+            if (typeof failure === "string")
+                throw new AnalysisOutputError(OPERATION, `${failure} Native diagnostics: ${diagnostics.join("\n")}`);
+            const parsed = reportSchema.safeParse(raw);
+            if (!parsed.success ||
+                parsed.data.importer_url !== importerUrl ||
+                parsed.data.entries.length !== input.specifiers.length ||
+                parsed.data.entries.some((entry, index) => entry.specifier !== input.specifiers[index]))
+                throw new AnalysisOutputError(OPERATION, "Native resolver report has invalid shape or does not match the selected importer/specifiers.");
+            if (diagnosticBytes > 1024 * 1024)
+                throw new BrowserObservationError(OPERATION, "payload_limit");
+            deadline.signal.throwIfAborted();
+            const engine = {
+                id: "chromium-native-module-resolver",
+                version: browser.version(),
+            };
+            result = ok({
+                engine,
+                resolutions: parsed.data.entries.map((entry) => entry.resolution),
+                diagnostics,
+                rawResult: jsonObjectSchema.parse({
+                    native_report: parsed.data,
+                    requests,
+                    diagnostics,
+                    engine,
+                    executable_path: executable,
+                }),
+            });
+        }
+        catch (cause) {
+            result = err(deadline.interruption === "cancelled"
+                ? new AnalysisCancelledError(OPERATION)
+                : deadline.interruption === "timeout"
+                    ? new AnalysisTimeoutError(OPERATION, TIMEOUT_MS)
+                    : cause instanceof AnalysisOutputError ||
+                        cause instanceof AnalysisCapabilityUnavailableError ||
+                        cause instanceof BrowserObservationError
+                        ? cause
+                        : new ProviderAdapterError("native-module-resolver", OPERATION, {
+                            cause,
+                            diagnostics: {
+                                executable,
+                                error_message: cause instanceof Error ? cause.message : String(cause),
+                            },
+                        }));
+        }
+        finally {
+            deadline.signal.removeEventListener("abort", onAbort);
+            deadline.dispose();
+            try {
+                await close();
+            }
+            catch (cause) {
+                result = err(new BrowserObservationError(OPERATION, "cleanup_failed", { cause }));
+            }
+        }
+        if (result.ok && options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        return result;
+    }
+}
+const scriptJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
+const htmlAttribute = (value) => value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");

package/dist/browser/modules/WebModuleArtifacts.js

@@ -0,0 +1,40 @@
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
+import { LocalWebScriptArtifacts } from "../assets/LocalWebScriptArtifacts.js";
+import { readWebArtifactJson, webArtifactReadError, } from "../assets/WebArtifactReads.js";
+/** Add an explicitly selected import map to a verified captured-script source. */
+export class LocalWebModuleArtifacts {
+    scripts;
+    constructor(scripts = new LocalWebScriptArtifacts("trace_web_module_imports")) {
+        this.scripts = scripts;
+    }
+    /** Read selected source and optional map without website requests. */
+    async load(input, options) {
+        const loaded = await this.scripts.load(input, options);
+        if (!loaded.ok)
+            return loaded;
+        if (input.import_map === undefined)
+            return ok({ ...loaded.value, importMap: null });
+        const selected = input.import_map;
+        try {
+            const data = await readWebArtifactJson(selected.path, 4 * 1024 * 1024, options?.signal);
+            const importMap = {
+                file: {
+                    path: selected.path,
+                    sha256: data.sha256,
+                    bytes: data.bytes.length,
+                },
+                baseUrl: selected.base_url,
+                value: jsonObjectSchema.parse(data.value),
+            };
+            return ok({ ...loaded.value, importMap });
+        }
+        catch (cause) {
+            return err(webArtifactReadError(cause, {
+                operation: "trace_web_module_imports",
+                field: ["import_map", "path"],
+                targetPath: selected.path,
+            }, options?.signal));
+        }
+    }
+}

package/dist/browser/network/PlaywrightNetworkContent.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { withPlaywrightExecutionBoundary } from "../PlaywrightExecutionBoundary.js";
+const credentialHeaders = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+]);
+const errorMessage = (cause, secrets) => secrets.redact(cause instanceof Error && cause.message !== ""
+    ? cause.message
+    : "Network read failed");
+/** Read actual producer headers without flattening duplicates or exposing credentials. */
+export const captureNetworkHeaders = async (source, secrets, options) => {
+    try {
+        const headers = await withPlaywrightExecutionBoundary(() => source.headersArray(), options.timeoutMs, options.signal);
+        return {
+            state: "captured",
+            items: headers.map(({ name, value }) => {
+                const safeName = secrets.redact(name);
+                const credential = credentialHeaders.has(name.toLowerCase());
+                const safeValue = credential
+                    ? null
+                    : secrets.redactBytes(Buffer.from(value)).toString("utf8");
+                return {
+                    name: safeName,
+                    value: safeValue,
+                    redacted: credential || safeName !== name || safeValue !== value,
+                };
+            }),
+        };
+    }
+    catch (cause) {
+        return { state: "unavailable", message: errorMessage(cause, secrets) };
+    }
+};
+/** Retain only bytes exposed by the browser; no fetch or wire-byte reconstruction occurs. */
+export const captureNetworkBody = async (read, phase, source, secrets, options) => {
+    try {
+        const observed = await withPlaywrightExecutionBoundary(read, options.timeoutMs, options.signal);
+        if (observed === null)
+            return { state: "not_exposed" };
+        const retained = secrets.redactBytes(observed);
+        const contentType = source.headers()["content-type"];
+        return {
+            state: "captured",
+            representation: phase === "request"
+                ? "browser-exposed-request-bytes"
+                : "browser-decoded-response-bytes",
+            encoding: "base64",
+            content: retained.toString("base64"),
+            bytes: retained.length,
+            sha256: createHash("sha256").update(retained).digest("hex"),
+            media_type: contentType === undefined
+                ? null
+                : secrets.redactBytes(Buffer.from(contentType)).toString("utf8"),
+            redacted: !retained.equals(observed),
+        };
+    }
+    catch (cause) {
+        return {
+            state: "unavailable",
+            reason: cause instanceof AnalysisCancelledError
+                ? "cancelled"
+                : cause instanceof AnalysisTimeoutError
+                    ? "body-read-timeout"
+                    : "body-read-failed",
+            message: errorMessage(cause, secrets),
+        };
+    }
+};

package/dist/browser/network/PlaywrightScenarioNetwork.js

@@ -0,0 +1,180 @@
+import { captureNetworkBody, captureNetworkHeaders, } from "./PlaywrightNetworkContent.js";
+/** Captures correlated network phases and drains selected content before browser cleanup. */
+export class PlaywrightScenarioNetwork {
+    options;
+    transactions = new Map();
+    pending = [];
+    gaps = new Set();
+    accepting = true;
+    readOptions;
+    constructor(options) {
+        this.options = options;
+        this.readOptions = {
+            timeoutMs: options.readTimeoutMs ?? 5_000,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        };
+    }
+    /** Observe a request start, retaining the producer's redirect relationship when known. */
+    request(request) {
+        if (!this.accepting)
+            return;
+        const transaction = this.transaction(request);
+        const sequence = this.options.emit({
+            ...this.metadata(request, transaction),
+            kind: "request",
+            status: null,
+            failure: null,
+        });
+        if (this.options.selection.request_body ||
+            this.options.selection.header_values)
+            this.collect(transaction, sequence, "request", request, this.options.selection.request_body
+                ? captureNetworkBody(async () => request.postDataBuffer(), "request", request, this.options.secrets, this.readOptions)
+                : Promise.resolve({ state: "not_requested" }));
+    }
+    /** Observe response metadata without starting a potentially unfinished body read. */
+    response(response) {
+        if (!this.accepting)
+            return;
+        const request = response.request();
+        const transaction = this.transaction(request);
+        const sequence = this.options.emit({
+            ...this.metadata(request, transaction),
+            kind: "response",
+            url: this.options.secrets.sanitizeUrl(response.url()),
+            status: response.status(),
+            header_names: this.headerNames(response),
+            failure: null,
+        });
+        transaction.response = { source: response, sequence };
+    }
+    /** Record completion and read the original completed response, never a later refetch. */
+    finished(request) {
+        if (!this.accepting)
+            return;
+        const transaction = this.transaction(request);
+        transaction.terminal = "finished";
+        this.options.emit({
+            ...this.metadata(request, transaction),
+            kind: "request-finished",
+            status: null,
+            failure: null,
+        });
+        this.responseContent(transaction);
+    }
+    /** Preserve request failure separately from missing or unreadable response content. */
+    failed(request) {
+        if (!this.accepting)
+            return;
+        const transaction = this.transaction(request);
+        transaction.terminal = "failed";
+        const message = this.options.secrets.redact(request.failure()?.errorText || "Unknown request failure");
+        this.options.emit({
+            ...this.metadata(request, transaction),
+            kind: "request-failed",
+            status: null,
+            failure: message,
+        });
+        this.responseContent(transaction, {
+            state: "unavailable",
+            reason: "request-failed",
+            message,
+        });
+    }
+    /** Stop observing, mark unfinished transactions, and settle bounded content reads. */
+    async finish() {
+        if (!this.accepting) {
+            await Promise.all(this.pending);
+            return;
+        }
+        this.accepting = false;
+        for (const [request, transaction] of this.transactions) {
+            if (transaction.terminal === undefined) {
+                this.gaps.add("Some network requests had not completed when capture ended; later activity is unknown.");
+                this.options.emit({
+                    ...this.metadata(request, transaction),
+                    kind: "request-unfinished",
+                    status: null,
+                    failure: null,
+                    reason: this.options.signal?.aborted === true
+                        ? "cancelled"
+                        : "capture-ended",
+                });
+                this.responseContent(transaction, {
+                    state: "unavailable",
+                    reason: this.options.signal?.aborted === true
+                        ? "cancelled"
+                        : "response-unfinished",
+                    message: "The response had not finished at the capture cutoff; no body read or refetch was attempted.",
+                });
+            }
+        }
+        await Promise.all(this.pending);
+    }
+    /** Missing selected content contributes to aggregate completeness. */
+    limitations() {
+        return [...this.gaps];
+    }
+    transaction(request) {
+        const known = this.transactions.get(request);
+        if (known !== undefined)
+            return known;
+        const predecessor = request.redirectedFrom();
+        const transaction = {
+            id: `request-${this.transactions.size + 1}`,
+            redirectedFrom: predecessor === null
+                ? null
+                : (this.transactions.get(predecessor)?.id ?? null),
+            responseScheduled: false,
+        };
+        this.transactions.set(request, transaction);
+        return transaction;
+    }
+    headerNames(source) {
+        return Object.keys(source.headers())
+            .map((name) => this.options.secrets.redact(name))
+            .sort();
+    }
+    metadata(request, transaction) {
+        return {
+            transaction_id: transaction.id,
+            redirected_from_transaction_id: transaction.redirectedFrom,
+            method: this.options.secrets.redact(request.method()),
+            url: this.options.secrets.sanitizeUrl(request.url()),
+            resource_type: this.options.secrets.redact(request.resourceType()),
+            header_names: this.headerNames(request),
+        };
+    }
+    responseContent(transaction, unavailable) {
+        const response = transaction.response;
+        if (response === undefined ||
+            transaction.responseScheduled ||
+            (!this.options.selection.response_body &&
+                !this.options.selection.header_values))
+            return;
+        transaction.responseScheduled = true;
+        this.collect(transaction, response.sequence, "response", response.source, this.options.selection.response_body
+            ? unavailable === undefined
+                ? captureNetworkBody(() => response.source.body(), "response", response.source, this.options.secrets, this.readOptions)
+                : Promise.resolve(unavailable)
+            : Promise.resolve({ state: "not_requested" }));
+    }
+    collect(transaction, sequence, phase, source, body) {
+        const headers = this.options.selection.header_values
+            ? captureNetworkHeaders(source, this.options.secrets, this.readOptions)
+            : Promise.resolve({ state: "not_requested" });
+        this.pending.push(Promise.all([headers, body]).then(([retainedHeaders, retainedBody]) => {
+            if (retainedHeaders.state === "unavailable" ||
+                retainedBody.state === "unavailable" ||
+                retainedBody.state === "not_exposed")
+                this.gaps.add("Some selected network content was unavailable; per-transaction content states retain the reason.");
+            this.options.emit({
+                kind: "network-content",
+                transaction_id: transaction.id,
+                source_event_sequence: sequence,
+                phase,
+                headers: retainedHeaders,
+                body: retainedBody,
+            });
+        }));
+    }
+}

package/dist/browser/providerIdentities.js

@@ -0,0 +1,24 @@
+/** Identity available without loading the CdpBrowserProvider implementation. */
+export const CDP_BROWSER_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-cdp-browser",
+    name: "REA Chrome DevTools Protocol observation provider",
+    version: "2",
+});
+/** Identity available without loading the PlaywrightBrowserScenarioProvider implementation. */
+export const PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-playwright-browser-scenario",
+    name: "REA Playwright browser scenario capture provider",
+    version: "1",
+});
+/** Identity available without loading the CdpElectronProvider implementation. */
+export const CDP_ELECTRON_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-cdp-electron",
+    name: "REA Electron file-page CDP observation provider",
+    version: "1",
+});
+/** Identity available without loading the PlaywrightElectronActiveProvider implementation. */
+export const PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY = Object.freeze({
+    id: "rea-playwright-electron-active",
+    name: "REA Playwright active Electron observation provider",
+    version: "1",
+});

package/dist/catalogIdentity.js

@@ -5,7 +5,8 @@ import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
 export { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
-const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
+const sortedToolContracts = [...TOOL_CONTRACTS].sort((left, right) => left.name.localeCompare(right.name));
+const createToolCatalog = () => sortedToolContracts.map((contract) => ({
     name: contract.name,
     title: contract.title,
     surface: contract.kind,
@@ -24,7 +25,7 @@ const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
             unrepresentable: "any",
         }),
     },
-})).sort((left, right) => left.name.localeCompare(right.name));
+}));
 const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
     name: contract.name,
     title: contract.title,
@@ -38,26 +39,33 @@ const digest = (value) => {
         throw new TypeError("Catalog is not canonical JSON");
     return createHash("sha256").update(encoded).digest("hex");
 };
-/** Stable, schema-sensitive identity for every public REA surface. */
-export const CATALOG_IDENTITY = {
-    counts: {
-        cli_commands: CLI_COMMAND_NAMES.length,
-        mcp_tools: toolCatalog.length,
-        mcp_prompts: promptCatalog.length,
-    },
-    digests: {
-        tools_sha256: digest(toolCatalog),
+const createCatalogDigests = () => {
+    const tools = createToolCatalog();
+    return {
+        tools_sha256: digest(tools),
         prompts_sha256: digest(promptCatalog),
         combined_sha256: digest({
             cli: CLI_COMMAND_NAMES,
-            tools: toolCatalog,
+            tools,
             prompts: promptCatalog,
         }),
+    };
+};
+let catalogDigests;
+/** Stable, schema-sensitive identity; schema digests are computed on first use. */
+export const CATALOG_IDENTITY = {
+    counts: {
+        cli_commands: CLI_COMMAND_NAMES.length,
+        mcp_tools: sortedToolContracts.length,
+        mcp_prompts: promptCatalog.length,
+    },
+    get digests() {
+        return (catalogDigests ??= createCatalogDigests());
     },
-    tools: toolCatalog.map(({ name, surface, effects, annotations }) => ({
+    tools: sortedToolContracts.map(({ name, kind, effects, annotations }) => ({
         name,
-        surface,
-        effects,
+        surface: kind,
+        effects: { ...effects },
         annotations: {
             read_only: annotations.readOnlyHint ?? false,
             destructive: annotations.destructiveHint ?? false,