rea-agents 6.4.0 → 6.7.0

package/dist/captures/TsharkCaptureProvider.js

@@ -0,0 +1,377 @@
+import { artifactFileCancellationCause } from "../artifacts/ArtifactFileOperation.js";
+import { packetFieldsCatalogSchema, } from "../domain/captures/packetFields.js";
+import { parseFieldDiscovery, FieldDiscoveryBudgetError, FIELD_RECORD_BUDGET, } from "./parseFieldDiscovery.js";
+import { BOUNDED_PRODUCER_LIMITS as LIMITS, prlimitArgumentVector, readLinuxResourceLimits, } from "../process/LinuxResourceLimits.js";
+import { parsePacketOutput } from "./parsePacketOutput.js";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactAnalysisResources, } from "../process/ArtifactAnalysisResources.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { packetCaptureSchema, } from "../domain/captures/packetCapture.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand, OwnedCommandFailure, } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+const OPERATION = "inspect_packet_capture";
+export const TSHARK_PROVIDER_IDENTITY = {
+    id: "tshark-capture",
+    name: "REA TShark capture adapter",
+    version: "tshark@4",
+};
+/** Inspect selected capture files only, retaining cleanup ownership across failures. */
+export class TsharkCaptureProvider {
+    environment;
+    launcher;
+    createRuntime;
+    platform;
+    readArtifact;
+    readLimits;
+    #resources;
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-tshark-" }), platform = process.platform, readArtifact = readStableArtifact, readLimits = readLinuxResourceLimits) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+        this.platform = platform;
+        this.readArtifact = readArtifact;
+        this.readLimits = readLimits;
+        this.#resources = new ArtifactAnalysisResources(TSHARK_PROVIDER_IDENTITY.id, OPERATION, readArtifact, readLimits, {
+            message: "A packet inspection is already active; retry after it completes.",
+            details: { max_concurrent_inspections: 1 },
+        });
+    }
+    inspect(input, options) {
+        return this.#resources.run(() => this.#executeRequest(input, options), options?.signal);
+    }
+    inspectFields(input, options) {
+        return this.#resources.run(() => this.#executeRequest(input, options), options?.signal, "inspect_packet_fields");
+    }
+    close() {
+        return this.#resources.close();
+    }
+    async #executeRequest(input, options) {
+        const operation = "path" in input ? OPERATION : "inspect_packet_fields";
+        // TShark 4.6.9 emits a 22.3 MB glossary; keep capture output capped at 4 MiB.
+        const limits = "path" in input ? LIMITS : { ...LIMITS, output_bytes: 32 * 1024 * 1024 };
+        let phase = "configuration";
+        let capturedOutput;
+        let resourcePath = "path" in input ? input.path : "TShark field glossary";
+        let effectiveLimits;
+        let root;
+        let result;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(operation, {
+                    cause: options.signal.reason,
+                });
+            await this.#resources.release();
+            if (this.platform !== "linux")
+                throw new Error("Packet inspection requires Linux with util-linux prlimit and REA_TSHARK_COMMAND so expanded captures are processed under an enforced address-space limit.");
+            const configured = this.environment.REA_TSHARK_COMMAND ?? "";
+            if (!isAbsolute(configured))
+                throw new Error("Supply absolute REA_TSHARK_COMMAND for TShark 4.x.");
+            const command = await realpath(configured);
+            await access(command, constants.X_OK);
+            const tool = await this.#resources.read(command, 64 * 1024 * 1024, options?.signal);
+            const configuredLimiter = this.environment.REA_TSHARK_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+            if (!isAbsolute(configuredLimiter))
+                throw new Error("REA_TSHARK_PRLIMIT_COMMAND must be absolute.");
+            const limiter = await realpath(configuredLimiter);
+            await access(limiter, constants.X_OK);
+            const limiterIdentity = await this.#resources.read(limiter, 64 * 1024 * 1024, options?.signal);
+            effectiveLimits = await this.#resources.readLimits(limits);
+            const limitArguments = prlimitArgumentVector(effectiveLimits, command);
+            phase = "workspace";
+            root = await this.createRuntime();
+            this.#resources.retain(root, undefined);
+            const snapshotPath = join(root.path, "capture");
+            const configurationPath = join(root.path, "configuration");
+            await mkdir(configurationPath, { mode: 0o700 });
+            const execute = async (args) => {
+                capturedOutput = undefined;
+                const output = await runOwnedCommand({
+                    command: limiter,
+                    arguments: [...limitArguments, ...args],
+                    ...(root === undefined ? {} : { cwd: root.path }),
+                    expectedCommand: null,
+                    runId: `rea-tshark-${randomUUID()}`,
+                    hostEnvironment: {
+                        ...this.environment,
+                        WIRESHARK_CONFIG_DIR: configurationPath,
+                    },
+                }, {
+                    timeoutMs: limits.command_timeout_ms,
+                    diagnosticBytes: limits.output_bytes,
+                    acceptNonZeroExit: true,
+                }, {
+                    ...(options?.signal === undefined
+                        ? {}
+                        : { signal: options.signal }),
+                    ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+                });
+                capturedOutput = {
+                    stdout: output.stdout.text,
+                    stderr: output.stderr.text,
+                    truncated: output.diagnosticTruncated ?? false,
+                    exit_code: output.exitCode ?? null,
+                    signal: output.signal ?? null,
+                };
+                // Finish bounded integrity checks after output; service handles late cancellation with Evidence.
+                const previousPhase = phase;
+                phase = "integrity";
+                resourcePath = command;
+                const current = await this.#resources.read(command, 64 * 1024 * 1024);
+                resourcePath = limiter;
+                const currentLimiter = await this.#resources.read(limiter, 64 * 1024 * 1024);
+                if (currentLimiter.sha256 !== limiterIdentity.sha256)
+                    throw new AnalysisArtifactChangedError(operation, limiter, "Configured resource limiter changed during analysis.", { capturedOutput });
+                if (current.sha256 !== tool.sha256)
+                    throw new AnalysisArtifactChangedError(operation, command, "Configured TShark executable changed during analysis.", { capturedOutput });
+                phase = previousPhase;
+                resourcePath = "path" in input ? input.path : command;
+                if (output.exitCode !== 0)
+                    throw new ProviderAdapterError(TSHARK_PROVIDER_IDENTITY.id, operation, {
+                        diagnostics: {
+                            exit_code: output.exitCode ?? null,
+                            stdout: output.stdout.text,
+                            stderr: output.stderr.text,
+                        },
+                    });
+                return output;
+            };
+            phase = "configuration";
+            const version = await execute(["--version"]);
+            if (!/^TShark \(Wireshark\) 4\.[0-9]+\.[0-9]+(?:[ .(\r\n]|$)/u.test(version.stdout.text))
+                throw new Error("Expected TShark 4.x; inspect the selected installation.");
+            const metadata = (args, diagnostics) => ({
+                diagnostics,
+                tool: {
+                    configured_path: configured,
+                    path: command,
+                    sha256: tool.sha256,
+                    version_banner: version.stdout.text,
+                    version_diagnostics: version.stderr.text,
+                    arguments: [...args],
+                },
+                resource_limiter: {
+                    configured_path: configuredLimiter,
+                    path: limiter,
+                    sha256: limiterIdentity.sha256,
+                    arguments: limitArguments,
+                },
+                limits: { ...limits, ...effectiveLimits },
+                hardware_acquisition: "not-performed",
+            });
+            if (!("path" in input)) {
+                phase = "producer";
+                const args = ["-G", "fields"];
+                const output = await execute(args);
+                const report = packetFieldsCatalogSchema.parse({
+                    selection: input,
+                    ...parseFieldDiscovery(output.stdout.text, input),
+                    ...metadata(args, output.stderr.text),
+                    limits: {
+                        ...limits,
+                        ...effectiveLimits,
+                        record_budget_bytes: FIELD_RECORD_BUDGET,
+                    },
+                    configuration: "private-empty-personal-profile",
+                });
+                result = ok(createAnalysisExecution(report, TSHARK_PROVIDER_IDENTITY, {
+                    subject: { path: command, sha256: tool.sha256, format: "file" },
+                    limitations: [
+                        "Protocol and field registrations describe the selected installation, not traffic observed in a capture. Duplicate abbreviations remain distinct producer records with source line numbers.",
+                        "Each request probes again without caching. The private empty personal profile does not fingerprint or isolate installed libraries, global configuration or plugins; they remain trusted.",
+                        "No capture file, interface or device is opened. Resource ceilings do not constitute an OS sandbox. Glossary output is capped at 32 MiB and selected record representation at 8 MiB before expansion.",
+                    ],
+                }));
+            }
+            else {
+                phase = "artifact";
+                const selected = await this.#resources.read(input.path, LIMITS.input_bytes, options?.signal);
+                phase = "workspace";
+                await writeFile(snapshotPath, selected.bytes, {
+                    flag: "wx",
+                    mode: 0o400,
+                });
+                phase = "producer";
+                const args = [
+                    "-n",
+                    "-r",
+                    "capture",
+                    "-T",
+                    "json",
+                    "--no-duplicate-keys",
+                    "--temp-dir=.",
+                    ...(input.two_pass ? ["-2"] : []),
+                    ...(input.packet_limit === null
+                        ? []
+                        : ["-c", String(input.packet_limit)]),
+                    ...(input.display_filter === null
+                        ? []
+                        : ["-Y", input.display_filter]),
+                    ...input.decode_as.flatMap((value) => ["-d", value]),
+                    ...[...new Set(["frame.number", ...input.fields])].flatMap((field) => ["-e", field]),
+                ];
+                const output = await execute(args);
+                phase = "integrity";
+                resourcePath = snapshotPath;
+                if ((await this.#resources.read(snapshotPath, LIMITS.input_bytes))
+                    .sha256 !== selected.sha256)
+                    throw new AnalysisArtifactChangedError(operation, snapshotPath, "TShark changed the private capture copy.", capturedOutput === undefined ? {} : { capturedOutput });
+                phase = "producer";
+                resourcePath = "path" in input ? input.path : command;
+                const matchingPackets = parsePacketOutput(output.stdout.text, input.fields);
+                const start = Math.min(input.match_offset, matchingPackets.length);
+                const end = input.match_limit === null
+                    ? matchingPackets.length
+                    : start +
+                        Math.min(input.match_limit, matchingPackets.length - start);
+                const packets = matchingPackets.slice(start, end);
+                const report = packetCaptureSchema.parse({
+                    artifact: {
+                        path: input.path,
+                        sha256: selected.sha256,
+                        bytes: selected.bytes.length,
+                    },
+                    selection: input,
+                    packets,
+                    output_window: {
+                        matching_packets: matchingPackets.length,
+                        returned_packets: packets.length,
+                        has_more: end < matchingPackets.length,
+                    },
+                    read_scope: input.packet_limit === null ? "to-eof" : "up-to-input-packet-limit",
+                    configuration: "private-empty-personal-profile",
+                    ...metadata(args, output.stderr.text),
+                });
+                result = ok(createAnalysisExecution(report, TSHARK_PROVIDER_IDENTITY, {
+                    subject: {
+                        path: input.path,
+                        sha256: selected.sha256,
+                        format: "file",
+                    },
+                    locations: [{ kind: "artifact-path", path: input.path }],
+                    limitations: [
+                        "Fields are TShark dissector observations under the selected filter/decode-as/pass settings, not independently verified protocol semantics. Missing fields are absent from the producer output, not known zero or empty values.",
+                        "Packet limits count input packets before display filtering. Filtered results do not establish whole-capture or device traffic absence. Two-pass reassembly cannot recover bytes missing from the recording or beyond the read limit.",
+                        "Repeated field values remain ordered string arrays; raw packet bytes are included only when explicitly selected as a supported field. Export index/score metadata are omitted. All stderr, including warnings on exit zero, is retained.",
+                        "A private empty personal configuration is used. Installed libraries, global configuration and dissector plugins are trusted and not fully fingerprinted. File-only analysis and disabled name resolution do not constitute an OS sandbox.",
+                        "Linux prlimit enforces soft and hard ceilings before execution, preserving stricter inherited limits: at most 1 GiB address space per process, 64 MiB per file, 30 CPU seconds and no core dumps. Effective limits are reported. Resident input is capped at 32 MiB, each command at 30 wall-clock seconds and combined output at 4 MiB. Output overflow fails. These are per-process/per-file limits, not aggregate memory or filesystem quotas; caller-supplied tools and the limiter are trusted.",
+                    ],
+                }));
+            }
+        }
+        catch (cause) {
+            if (root !== undefined &&
+                cause instanceof OwnedCommandFailure &&
+                cause.cleanupOwner !== undefined)
+                this.#resources.retain(root, cause.cleanupOwner);
+            result = err(this.#failure(cause, phase, resourcePath, root?.path ?? null, effectiveLimits, capturedOutput, operation, limits));
+        }
+        return this.#resources.finish(result, (execution) => createEvidence(execution.subject ?? undefined, execution.provider, {
+            operation,
+            parameters: input,
+            result: execution.result,
+            confidence: "observed",
+            locations: execution.locations,
+            limitations: execution.limitations,
+        }), operation, options?.signal);
+    }
+    #failure(cause, phase, path, workspacePath, effectiveLimits, observedOutput, operation = OPERATION, limits = LIMITS) {
+        if (cause instanceof AnalysisError)
+            return cause;
+        if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+            return this.#resources.cleanupFailure(cause, (primary) => this.#failure(primary, phase, path, workspacePath, effectiveLimits, observedOutput, operation, limits), observedOutput, operation);
+        if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
+            return new AnalysisCancelledError(operation, {
+                cause: artifactFileCancellationCause(cause),
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+            });
+        if (cause instanceof FieldDiscoveryBudgetError)
+            return new AnalysisResourceConstraintError(operation, "memory", cause.message, { record_budget_bytes: FIELD_RECORD_BUDGET }, {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+            });
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        if (cause instanceof OwnedCommandFailure)
+            return this.#resources.commandFailure(cause, limits, effectiveLimits, operation);
+        if (phase === "workspace") {
+            const code = cause instanceof Error &&
+                "code" in cause &&
+                typeof cause.code === "string"
+                ? cause.code
+                : null;
+            if (code === "ENOSPC" || code === "EDQUOT" || code === "EFBIG")
+                return new AnalysisResourceConstraintError(operation, "file-size", `Private analysis workspace failed (${code}): ${reason}`, { workspace_path: workspacePath, system_code: code }, { cause });
+            return new ProviderAdapterError(TSHARK_PROVIDER_IDENTITY.id, operation, {
+                cause,
+                userMessage: `Cannot prepare the private analysis workspace: ${reason}`,
+                diagnostics: {
+                    stage: "workspace",
+                    workspace_path: workspacePath,
+                    system_code: code,
+                    reason,
+                },
+            });
+        }
+        if (phase === "integrity") {
+            const detail = {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+            };
+            if (cause instanceof ArtifactReaderFailure &&
+                ["limit", "integrity", "path"].includes(cause.reason))
+                return new AnalysisArtifactChangedError(operation, path, `Post-run identity verification failed for ${path}: ${reason}`, detail);
+            return new ProviderAdapterError(TSHARK_PROVIDER_IDENTITY.id, operation, {
+                ...detail,
+                diagnostics: { stage: "integrity", resource_path: path, reason },
+            });
+        }
+        if (phase === "configuration")
+            return new AnalysisCapabilityUnavailableError(TSHARK_PROVIDER_IDENTITY.id, operation, reason, {
+                cause,
+                ...(observedOutput === undefined
+                    ? {}
+                    : { capturedOutput: observedOutput }),
+                userMessage: `${reason} On Linux, configure TShark 4.x through REA_TSHARK_COMMAND and util-linux prlimit through REA_TSHARK_PRLIMIT_COMMAND (default /usr/bin/prlimit).`,
+            });
+        if (phase === "artifact" &&
+            cause instanceof ArtifactReaderFailure &&
+            cause.reason === "limit")
+            return new AnalysisResourceConstraintError(operation, "file-size", reason, { input_bytes: LIMITS.input_bytes }, { cause });
+        if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")
+            return new AnalysisArtifactChangedError(operation, path, reason, {
+                cause,
+            });
+        if (phase === "artifact" &&
+            cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "EACCES" || cause.code === "EPERM"))
+            return new AnalysisAccessDeniedError(operation, path, cause.code, {
+                cause,
+            });
+        if (phase === "artifact")
+            return new AnalysisInputError(operation, { cause }, [
+                { path: ["path"], reason: "invalid_value", message: reason },
+            ]);
+        return new AnalysisOutputError(operation, reason, {
+            cause,
+            ...(observedOutput === undefined
+                ? {}
+                : { capturedOutput: observedOutput }),
+        });
+    }
+}

package/dist/captures/parseFieldDiscovery.js

@@ -0,0 +1,66 @@
+export class FieldDiscoveryBudgetError extends Error {
+}
+export const FIELD_RECORD_BUDGET = 8 * 1024 * 1024;
+/** TShark -G fields: P/name/abbreviation or F/name/abbreviation/type/parent/base/mask/blurb. */
+export const parseFieldDiscovery = (text, input) => {
+    const copy = (value) => Buffer.from(value, "utf16le").toString("utf16le");
+    const query = input.query.toLowerCase();
+    const records = [];
+    let examined = 0, matching = 0, sourceLine = 0, budget = 0;
+    // Walk the bounded text once; allocate record objects only for the requested page.
+    for (let start = 0; start < text.length;) {
+        const end = text.indexOf("\n", start);
+        let line = text.slice(start, end < 0 ? text.length : end);
+        start = end < 0 ? text.length : end + 1;
+        sourceLine++;
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        const columns = line.split("\t", 9);
+        const [tag, name, abbreviation] = columns;
+        if (!((tag === "P" && columns.length === 3) ||
+            (tag === "F" && columns.length === 8)) ||
+            name === undefined ||
+            abbreviation === undefined ||
+            abbreviation === "")
+            throw new Error(`Malformed TShark field glossary record at line ${sourceLine}`);
+        if ((input.kind === "protocols") !== (tag === "P"))
+            continue;
+        examined++;
+        if (input.protocol !== null &&
+            (tag === "P" ? abbreviation : columns[4]) !== input.protocol)
+            continue;
+        if (![name, abbreviation, ...(tag === "F" ? [columns[7] ?? ""] : [])].some((value) => value.toLowerCase().includes(query)))
+            continue;
+        matching++;
+        if (matching <= input.offset ||
+            records.length >= (input.limit ?? Number.MAX_SAFE_INTEGER))
+            continue;
+        // Six bytes per source byte covers worst-case JSON escaping, plus record bookkeeping.
+        budget += Buffer.byteLength(line, "utf8") * 6 + 512;
+        if (budget > FIELD_RECORD_BUDGET)
+            throw new FieldDiscoveryBudgetError("Selected glossary records exceed the 8 MiB representation budget; narrow the query or page size");
+        // Detach retained fields from the much larger producer string.
+        records.push({
+            source_line: sourceLine,
+            kind: tag === "P" ? "protocol" : "field",
+            name: copy(name),
+            abbreviation: copy(abbreviation),
+            field_type: tag === "F" ? copy(columns[3] ?? "") : null,
+            parent_protocol: tag === "F" ? copy(columns[4] ?? "") : null,
+            display_base: tag === "F" ? copy(columns[5] ?? "") : null,
+            bitmask: tag === "F" ? copy(columns[6] ?? "") : null,
+            description: tag === "F" ? copy(columns[7] ?? "") : null,
+        });
+    }
+    if (sourceLine === 0)
+        throw new Error("TShark returned an empty field glossary");
+    return {
+        records,
+        output_window: {
+            examined,
+            matching,
+            returned: records.length,
+            has_more: Math.max(0, matching - input.offset) > records.length,
+        },
+    };
+};

package/dist/captures/parsePacketOutput.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { packetFieldsSchema } from "../domain/captures/packetCapture.js";
+// _index/_score are TShark export metadata, not captured packet fields.
+const producerSchema = z.array(z.object({ _source: z.object({ layers: packetFieldsSchema }) }));
+export const parsePacketOutput = (text, fields) => {
+    const decoded = JSON.parse(text);
+    const packets = producerSchema
+        .parse(decoded)
+        .map((packet) => packet._source.layers);
+    const selected = new Set(["frame.number", ...fields]);
+    let previous = 0n;
+    for (const packet of packets) {
+        const frame = BigInt(packet["frame.number"][0]);
+        if (frame <= previous ||
+            Object.keys(packet).some((name) => !selected.has(name)))
+            throw new AnalysisOutputError("inspect_packet_capture", "TShark returned unordered frames or unselected fields.");
+        previous = frame;
+    }
+    return packets;
+};

package/dist/catalogIdentity.js

@@ -1,75 +1,91 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
-import { z } from "zod";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
-const sortedToolContracts = [...TOOL_CONTRACTS].sort((left, right) => left.name.localeCompare(right.name));
-const createToolCatalog = () => sortedToolContracts.map((contract) => ({
+import { compareUnicodeCodePoints } from "./domain/unicodeCodePointOrder.js";
+import { advertisedInputJsonSchema, toolOutputSchemaWithMetadata, } from "./contracts/toolSchemaMetadata.js";
+import { presentAdvertisedInputSchema, } from "./contracts/compactInputSchema.js";
+import { RECORDED_CATALOG_DIGESTS } from "./recordedCatalogDigests.js";
+const sortByName = (contracts) => [...contracts].sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+const sortedToolContracts = sortByName(TOOL_CONTRACTS);
+/**
+ * Digested per-tool projection. Every contract field that changes what a
+ * client receives belongs here, including `returns_target_content`: a server
+ * that predates the untrusted-content framing must not digest equal to one
+ * that emits `_meta.provenance`, or a stale process would report aligned.
+ */
+const createToolCatalog = (contracts, compactPresentation) => contracts.map((contract) => ({
     name: contract.name,
     title: contract.title,
     surface: contract.kind,
     description: contract.description,
     effects: { ...contract.effects },
+    returns_target_content: contract.returnsTargetContent,
     annotations: contract.annotations,
-    input_schema: {
-        type: "object",
-        ...z.toJSONSchema(contract.inputSchema, {
-            unrepresentable: "any",
-        }),
-    },
-    output_schema: {
-        type: "object",
-        ...z.toJSONSchema(contract.outputSchema, {
-            unrepresentable: "any",
-        }),
-    },
+    input_schema: presentAdvertisedInputSchema(advertisedInputJsonSchema(contract), compactPresentation),
+    output_schema: toolOutputSchemaWithMetadata(contract)["~standard"].jsonSchema.output({ target: "draft-2020-12" }),
 }));
-const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
+const createPromptCatalog = (contracts) => contracts
+    .map((contract) => ({
     name: contract.name,
     title: contract.title,
     description: contract.description,
+    objective: contract.objective,
     arguments: contract.arguments,
     steps: contract.steps,
-})).sort((left, right) => left.name.localeCompare(right.name));
+}))
+    .sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+const promptCatalog = createPromptCatalog(PROMPT_CONTRACTS);
 const digest = (value) => {
     const encoded = canonicalize(value);
     if (encoded === undefined)
         throw new TypeError("Catalog is not canonical JSON");
     return createHash("sha256").update(encoded).digest("hex");
 };
-const createCatalogDigests = () => {
-    const tools = createToolCatalog();
+/**
+ * Catalog digests over the given tool contracts. Exported so tests can prove
+ * which contract fields the identity covers; production uses
+ * {@link CATALOG_IDENTITY}.
+ */
+export const createCatalogDigests = (contracts = TOOL_CONTRACTS, promptContracts = PROMPT_CONTRACTS, compactPresentation = undefined, outputSchemaProfile = "full") => {
+    const tools = {
+        output_schema_profile: outputSchemaProfile,
+        catalog: createToolCatalog(sortByName(contracts), compactPresentation),
+    };
+    const prompts = createPromptCatalog(promptContracts);
     return {
         tools_sha256: digest(tools),
-        prompts_sha256: digest(promptCatalog),
+        prompts_sha256: digest(prompts),
         combined_sha256: digest({
             cli: CLI_COMMAND_NAMES,
             tools,
-            prompts: promptCatalog,
+            prompts,
         }),
     };
 };
-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: sortedToolContracts.map(({ name, kind, effects, annotations }) => ({
-        name,
-        surface: kind,
-        effects: { ...effects },
-        annotations: {
-            read_only: annotations.readOnlyHint ?? false,
-            destructive: annotations.destructiveHint ?? false,
-            idempotent: annotations.idempotentHint ?? false,
-            open_world: annotations.openWorldHint ?? true,
+export const createCatalogIdentity = (compactPresentation = undefined, outputSchemaProfile = "full") => {
+    const selectedPresentation = compactPresentation === undefined
+        ? undefined
+        : { budgetBytes: compactPresentation.budgetBytes };
+    // Building and canonicalizing every advertised schema dominates doctor and
+    // server startup, so the compiled runtime records the default digests once.
+    let catalogDigests = selectedPresentation === undefined && outputSchemaProfile === "full"
+        ? RECORDED_CATALOG_DIGESTS
+        : undefined;
+    return {
+        counts: {
+            cli_commands: CLI_COMMAND_NAMES.length,
+            mcp_tools: sortedToolContracts.length,
+            mcp_prompts: promptCatalog.length,
+        },
+        get digests() {
+            return (catalogDigests ??= createCatalogDigests(TOOL_CONTRACTS, PROMPT_CONTRACTS, selectedPresentation, outputSchemaProfile));
         },
-    })),
+    };
 };
+/**
+ * Stable, schema-sensitive identity; schema digests are recorded at build time
+ * or computed on first use.
+ */
+export const CATALOG_IDENTITY = createCatalogIdentity();