reverseport 0.0.0-stage → 1.2.0

package/dist/contracts/enhancedInputs.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { nativeValueTraceInputSchema } from "../domain/native/nativeValueTrace.js";
+const traceLiteralInputSchema = z.strictObject({
+    query: z.string().min(1),
+    case_sensitive: z.boolean().default(false),
+});
+/** Input schemas shared by MCP registration and enhanced application dispatch. */
+export const enhancedInputSchemas = {
+    trace_native_values: nativeValueTraceInputSchema,
+    inspect_native_dispatch_metadata: z.strictObject({
+        max_records: z.number().int().min(1).max(20_000).default(5_000),
+    }),
+    get_objc_classes: z.strictObject({ pattern: z.string().default("") }),
+    get_objc_protocols: z.strictObject({}),
+    batch_decompile: z.strictObject({
+        addresses: z
+            .array(z
+            .string()
+            .describe("A procedure symbol or address, e.g. main or 0x1000"))
+            .default([]),
+    }),
+    get_call_graph: z.strictObject({
+        address: z
+            .string()
+            .describe("A procedure symbol or address to resolve to its canonical entry"),
+        direction: z
+            .enum(["forward", "backward"])
+            .default("forward")
+            .describe("forward follows callees (functions this one calls); backward follows callers (functions that call it)"),
+    }),
+    analyze_swift_types: z.strictObject({
+        category: z
+            .enum(["classes", "structs", "enums", "protocols", "extensions", "other"])
+            .optional()
+            .describe("Limit categorized results to one Swift category; unresolved category observations remain in unclassified."),
+        pattern: z
+            .string()
+            .optional()
+            .describe("Case-sensitive literal filter applied to provider procedure names and their supporting Swift manglings."),
+    }),
+    find_xrefs_to_name: z.strictObject({
+        name: z
+            .string()
+            .describe("Exact, case-sensitive symbol name as returned by list_names or search_procedures"),
+    }),
+    binary_overview: z.strictObject({}),
+    analyze_function: z.strictObject({
+        procedure: z.string().describe("A procedure name or address"),
+    }),
+    inspect_native_api: z.strictObject({
+        procedure: z.string().describe("A procedure name or address"),
+    }),
+    trace_feature: traceLiteralInputSchema,
+    trace_call_path: z.strictObject({
+        start: z.string().describe("A starting procedure symbol or address"),
+        goal: z
+            .string()
+            .describe("An optional destination procedure symbol or address")
+            .optional(),
+        direction: z
+            .enum(["forward", "backward"])
+            .default("forward")
+            .describe("forward follows callees (functions this one calls); backward follows callers (functions that call it)"),
+    }),
+    trace_native_ui_action: z.strictObject({
+        action: z
+            .string()
+            .min(1)
+            .describe("A unique compiled UI action selector, interface object ID, native symbol or exact function address"),
+        max_depth: z.number().int().min(0).max(32).default(8),
+        max_nodes: z.number().int().min(1).max(2_000).default(250),
+        max_edges: z.number().int().min(1).max(5_000).default(500),
+    }),
+};

package/dist/contracts/enhancedToolContracts.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { enhancedOutputSchemas } from "./toolOutputSchemaGroups.js";
+import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
+import { examplesFor } from "./toolContractHelpers.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
+const enhanced = (name, description, inputSchema) => ({
+    name,
+    ...toolContractMetadata(name),
+    description,
+    kind: "enhanced",
+    inputSchema,
+    outputSchema: requireOutputSchema(enhancedOutputSchemas, name),
+    examples: examplesFor(name, inputSchema),
+});
+/** Workflow tools composed from one or more provider operations. */
+export const ENHANCED_TOOL_CONTRACTS = [
+    enhanced("inspect_native_dispatch_metadata", "Inspect the bound provider's name inventory for Objective-C class/method symbols and Swift mangled symbols, returning at most max_records decoded names. Includes target SHA-256 when available, provider identity/version, analysis-profile digest, facet coverage, and per-record Evidence. This is symbol-level evidence, not runtime metadata: ivar layouts, protocol conformances, witness/class tables, and relative pointers are explicitly marked unsupported unless a provider supplies those decoders. The provider controls how its name inventory is acquired.", enhancedInputSchemas.inspect_native_dispatch_metadata),
+    enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels, optionally filtering by literal substring.", enhancedInputSchemas.get_objc_classes),
+    enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels.", enhancedInputSchemas.get_objc_protocols),
+    enhanced("batch_decompile", "Decompile each explicit procedure symbol or address concurrently. Preserves each input selector in address and reports the observed canonical entry and entry label in procedure; identity or label failures remain explicit without discarding usable pseudocode. Returns ordered per-item success or error results and aggregate counts.", enhancedInputSchemas.batch_decompile),
+    enhanced("get_call_graph", "Resolve one symbol or address to its canonical procedure entry, then traverse the bound provider's caller or callee relationships until the reachable graph is exhausted. Every node uses a canonical address and has an ok/error status; failures use safe typed projections. Unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("analyze_swift_types", 'Categorize analyzed Swift procedure names using their manglings or same-address Swift symbol aliases. Decodes legacy and literal modern nominal contexts into classes, structs, enums, protocols, and extensions. Preserves provider names and supporting mangled_names; unresolved categories appear in other and in unclassified, which remains inline even under category filters. Returns deduplicated procedure-name counts, not unique source types, plus identification limitations. Optionally select one category and/or apply a case-sensitive literal filter to provider names or supporting manglings; for example, use {category: "structs", pattern: "Pair"}.', enhancedInputSchemas.analyze_swift_types),
+    enhanced("find_xrefs_to_name", "Resolve an exact name against the bound provider's name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
+    enhanced("binary_overview", "Return native-binary metadata, every segment with its length, and exhaustive procedure/string counts. Use search_procedures, list_procedures, or analyze_function directly when you already know which procedure to inspect.", enhancedInputSchemas.binary_overview),
+    ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
+    enhanced("trace_feature", "Trace the complete literal query, preserving spaces, through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
+    enhanced("trace_call_path", "Resolve start and optional goal symbols or addresses to canonical procedure entries, then trace direct callers or callees until the graph is exhausted or the goal is reached. Results use canonical addresses; Evidence preserves supplied selectors. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns. A requested goal is unknown when unresolved expansions prevent proving it absent; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
+    enhanced("trace_native_ui_action", "Trace one unique compiled UI action, object ID, native symbol or exact function address through authored connections, encoded or symbolized Objective-C handlers, and bounded static call references. Typed direct and resolved indirect calls, ambiguous candidates, inferred untyped provider callees, and targetless sites remain distinct. Runtime reachability is unknown; use trace_native_values for recovered value dependencies.", enhancedInputSchemas.trace_native_ui_action),
+    enhanced("trace_native_values", "Trace a bounded static dependency graph from one explicit native procedure. Includes high-p-code def-use, constants, operators, memory and branch operations, resolved call edges, and derived argument/parameter and return/output bindings. Missing bindings, alias semantics, persistent state and RNG roles remain unknown. Budgets bound depth, decompilations, graph size and payloads; nodes are paginated.", enhancedInputSchemas.trace_native_values),
+];

package/dist/contracts/errorSchemas.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const categorySchema = z.enum([
+    "invalid_input",
+    "unsupported_provider",
+    "unsupported_target",
+    "integrity_mismatch",
+    "truncated",
+    "cancelled",
+    "timeout",
+    "resource_constraint",
+    "unavailable",
+    "execution_failure",
+]);
+const remediationSchema = z
+    .object({
+    action: z.string().min(1),
+})
+    .strict();
+const common = {
+    category: categorySchema,
+    message: z.string().min(1),
+    retryable: z.boolean(),
+    remediation: remediationSchema,
+};
+const genericDetails = z.record(z.string(), jsonValueSchema).optional();
+const generic = (code) => z
+    .object({ code: z.literal(code), ...common, details: genericDetails })
+    .strict();
+/** Stable discriminated schema shared by every CLI and MCP error surface. */
+export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
+    generic("invalid_request"),
+    generic("access_denied"),
+    generic("artifact_changed"),
+    generic("unreadable_output"),
+    generic("capability_unavailable"),
+    generic("unsupported_target"),
+    generic("provider_unavailable"),
+    generic("provider_timeout"),
+    generic("resource_constraint"),
+    generic("cancelled"),
+    z
+        .object({
+        code: z.literal("artifact_integrity_mismatch"),
+        ...common,
+        details: z
+            .object({
+            logical_path: z.string(),
+            declared_sha256: z.string().nullable(),
+            calculated_sha256: z.string().nullable(),
+            unpacked: z.boolean(),
+        })
+            .strict(),
+    })
+        .strict(),
+    generic("artifact_operation_failed"),
+    generic("evidence_integrity_mismatch"),
+    generic("truncated"),
+    generic("process_capture_failed"),
+    generic("cleanup_incomplete"),
+    generic("revision_conflict"),
+    generic("configuration_invalid"),
+    generic("target_unavailable"),
+    generic("execution_failure"),
+]);
+/** CLI label and input diagnostics surrounding the strict canonical error projection. */
+export const analysisCliErrorEnvelopeSchema = z
+    .object({
+    error: z.string().min(1),
+    input_path: z.string().optional(),
+    input_reason: z
+        .enum(["invalid-json", "read-failed", "too-large"])
+        .optional(),
+})
+    .passthrough()
+    .superRefine((value, context) => {
+    const { error: _label, input_path: _inputPath, input_reason: _inputReason, ...projection } = value;
+    const parsed = analysisErrorProjectionSchema.safeParse(projection);
+    if (!parsed.success) {
+        context.addIssue({
+            code: "custom",
+            message: "CLI error envelope must contain a canonical analysis error projection",
+        });
+    }
+});
+/** JSON Schema document used by generated API documentation and clients. */
+export const analysisErrorJsonSchema = z.toJSONSchema(analysisErrorProjectionSchema);

package/dist/contracts/evidenceInputContracts.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { evidenceSchema } from "../domain/evidence.js";
+import { prefixedDigestSchema } from "../domain/digests.js";
+/** Exact reference to Evidence already retained by the current session. */
+export const retainedEvidenceReferenceSchema = z.strictObject({
+    kind: z.literal("retained-evidence"),
+    evidence_id: prefixedDigestSchema("ev"),
+});
+/** Portable inline Evidence or an exact, session-scoped reference. */
+export const evidenceInputSchema = z.union([
+    evidenceSchema,
+    retainedEvidenceReferenceSchema,
+]);

package/dist/contracts/evm/evmToolContracts.js

@@ -0,0 +1,20 @@
+import { inspectEvmInterfaceInputSchema, evmInterfaceSchema, } from "../../domain/evm/evmInterface.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Target-free EVM capabilities are independent of archive/Apple artifact providers. */
+export const EVM_TOOL_CONTRACTS = [
+    {
+        name: "inspect_evm_interface",
+        ...toolContractMetadata("inspect_evm_interface"),
+        kind: "artifact-provider",
+        description: "Inspect an explicit local flat EVM bytecode carrier and infer dispatch selectors, argument strings and mutability without executing the target or accessing a chain/RPC endpoint. Choose raw or hex encoding explicitly. Returns original carrier and decoded-byte SHA-256, full bytecode and interface candidates inline as inferred Evidence; bytecode kind, hardfork, deployed authenticity and discovery completeness remain unknown. Initial real-verified Linux x64 profile uses unchanged bundled EVMole 0.9.3/WASM in a bounded owned worker; EOF-style EF00 containers are unsupported. No signature lookup, wallet action or transaction broadcast.",
+        inputSchema: inspectEvmInterfaceInputSchema,
+        outputSchema: evidenceResultOf(evmInterfaceSchema),
+        examples: [
+            {
+                title: "Inspect a local runtime bytecode hex carrier",
+                input: { path: "/artifacts/runtime.hex", encoding: "hex" },
+            },
+        ],
+    },
+];

package/dist/contracts/firmware/firmwareToolContracts.js

@@ -0,0 +1,38 @@
+import { firmwareInputSchemas, firmwareResultSchemas, } from "../../domain/firmware/firmwareAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** Explicit local firmware observations and extraction, backed by caller-supplied tools. */
+export const FIRMWARE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_firmware_regions",
+        ...toolContractMetadata("inspect_firmware_regions"),
+        kind: "firmware-provider",
+        description: "Inspect signature candidates in a local firmware file with Binwalk 3.1.x (verified with 3.1.0). Returns offsets, reported lengths, descriptions and raw confidence values. Length validation and runtime addresses remain unknown. No extraction or target execution. Linux, caller-supplied tool and util-linux prlimit required; 128 MiB input limit, one worker and 120-second deadline.",
+        inputSchema: firmwareInputSchemas.inspect_firmware_regions,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.inspect_firmware_regions),
+        examples: [
+            {
+                title: "Inspect firmware regions",
+                input: { path: "/tmp/firmware.bin" },
+            },
+        ],
+    },
+    {
+        name: "extract_firmware",
+        ...toolContractMetadata("extract_firmware"),
+        kind: "firmware-provider",
+        description: "Extract caller-selected firmware bytes with Unblob 26.6.x (verified with 26.6.4) into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks and extraction diagnostics inline. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
+        inputSchema: firmwareInputSchemas.extract_firmware,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.extract_firmware),
+        examples: [
+            {
+                title: "Extract selected firmware",
+                input: {
+                    path: "/tmp/firmware.bin",
+                    output_directory: "/tmp/firmware-output",
+                    range: { offset: 64, length: 4096 },
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/functionComparisonExample.js

@@ -0,0 +1,51 @@
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+const dossier = (text) => jsonValueSchema.parse({
+    procedure: {
+        address: "0x1000",
+        name: "main",
+        classification: null,
+        body: {
+            available: false,
+            reason: "The fixture omits function-body extent observations.",
+        },
+        signature: "int main(void)",
+        locals: [],
+    },
+    pseudocode: text,
+    assembly: [],
+    comments: [],
+    callers: [],
+    callees: [],
+    incoming_references: [],
+    outgoing_references: [],
+    referenced_strings: [],
+    referenced_names: [],
+    basic_blocks: [{ start: "0x1000", end: "0x1001", successors: [] }],
+    native_api: null,
+    native_value_flow: null,
+    limitations: ["The fixture omits native API and value-flow observations."],
+});
+const observe = (digit, text) => createEvidence({
+    path: `/tmp/function-${digit}`,
+    sha256: digit.repeat(64),
+    format: "mach-o",
+}, {
+    id: "rea-workflow",
+    name: "REA composed investigation workflow",
+    version: "1",
+}, {
+    operation: "analyze_function",
+    parameters: enhancedInputSchemas.analyze_function.parse({
+        procedure: "main",
+    }),
+    result: dossier(text),
+    confidence: "derived",
+    authority: "shipped-artifact",
+});
+/** Canonical explicit function pair used in public contract examples. */
+export const FUNCTION_COMPARISON_EXAMPLE = {
+    left: observe("0", "return 0;"),
+    right: observe("1", "return 1;"),
+};

package/dist/contracts/functionInstructionContract.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+/** Provider-neutral input for a function's complete raw instruction list. */
+export const functionInstructionInputSchema = z.object({
+    procedure: z.string().describe("The procedure name or address"),
+    document: z.string().optional().describe("The document name"),
+});

package/dist/contracts/functionWorkflowToolContracts.js

@@ -0,0 +1,29 @@
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { enhancedOutputSchemas } from "./toolOutputSchemaGroups.js";
+import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
+const functionWorkflow = (name, description) => {
+    const inputSchema = enhancedInputSchemas[name];
+    const outputSchema = requireOutputSchema(enhancedOutputSchemas, name);
+    return {
+        name,
+        ...toolContractMetadata(name),
+        description,
+        kind: "enhanced",
+        inputSchema,
+        outputSchema,
+        examples: [
+            {
+                title: `Example ${name.replaceAll("_", " ")} request`,
+                input: jsonObjectSchema.parse(inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {})),
+            },
+        ],
+    };
+};
+/** Function dossier and native API reconstruction workflow contracts. */
+export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
+    functionWorkflow("analyze_function", "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive analyzed body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations with available callee identities."),
+    functionWorkflow("inspect_native_api", "Analyze a native API boundary in one function identified by symbol or provider-returned address. Returns confidence, evidence, jump-table dispatch/data/case mappings, separately evidenced default targets, unsupported branches, and residual unknowns. Null case values mean unresolved cases, never a known default."),
+];

package/dist/contracts/go/goToolContracts.js

@@ -0,0 +1,20 @@
+import { goBinarySchema, inspectGoBinaryInputSchema, } from "../../domain/go/goBinary.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Static Go metadata is independent of active native-analysis providers and host toolchains. */
+export const GO_TOOL_CONTRACTS = [
+    {
+        name: "inspect_go_binary",
+        ...toolContractMetadata("inspect_go_binary"),
+        kind: "artifact-provider",
+        description: "Inspect embedded Go compiler version, main module, dependency/replacement versions and build settings in an explicit local ELF, PE or thin Mach-O image. Returns original artifact SHA-256, exact build-info source ranges, raw framed module bytes and unparsed module-text lines inline as observed Evidence. Supports inline and historical pointer encodings without installing Go, opening a disassembler, executing the target, writing temporary files or accessing the network. Missing metadata is reported as unknown, not proof that an image is not Go. Does not recover functions, source mappings, types or runtime behavior. Resource guards bound files to 256 MiB, aggregate embedded strings to 1 MiB, structural table decoding to 16 MiB and complete inline metadata to 8 MiB; malformed, unsupported and oversized inputs receive typed failures rather than partial success.",
+        inputSchema: inspectGoBinaryInputSchema,
+        outputSchema: evidenceResultOf(goBinarySchema),
+        examples: [
+            {
+                title: "Inspect embedded build provenance",
+                input: { path: "/artifacts/application" },
+            },
+        ],
+    },
+];

package/dist/contracts/hopperMemoryContracts.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { address, document } from "./toolContractHelpers.js";
+/** Hopper memory and file-mapping contracts. */
+export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
+    {
+        name: "read_bytes",
+        description: "Read analyzed bytes from one provider-normalized virtual address. The hexadecimal payload reports the exact returned length; incomplete reads remain explicit and unsupported provider APIs return typed capability unavailability.",
+        inputSchema: z.object({
+            address,
+            length: z.number().int().min(1).default(256),
+            document,
+        }),
+    },
+    {
+        name: "address_to_file_offset",
+        description: "Map one provider-normalized virtual address to its original nonnegative file offset. Hopper verifies the original bytes against the selected executable digest and translates FAT image-relative offsets using the loaded header. Results preserve the provider coordinate, image base, and source path. Unmapped addresses fail explicitly; changed or unavailable sources return typed errors retaining native mapping facts as partial evidence.",
+        inputSchema: z.object({ address, document }),
+    },
+];

package/dist/contracts/inputSchemaPresentation.js

@@ -0,0 +1,181 @@
+import { isDeepStrictEqual } from "node:util";
+export const schemaMaps = new Set([
+    "$defs",
+    "definitions",
+    "properties",
+    "patternProperties",
+    "dependentSchemas",
+    "dependencies",
+]);
+export const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+export const schemaChildren = new Set([
+    "items",
+    "additionalItems",
+    "contains",
+    "additionalProperties",
+    "unevaluatedProperties",
+    "unevaluatedItems",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+]);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const resolveReference = (root, reference) => {
+    if (!reference.startsWith("#/"))
+        return undefined;
+    let value = root;
+    for (const token of reference.slice(2).split("/")) {
+        const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (!isObject(value) || !Object.hasOwn(value, key))
+            return undefined;
+        value = value[key];
+    }
+    return value;
+};
+const referencedDescription = (root, schema) => {
+    let value = schema;
+    const active = new Set();
+    while (isObject(value)) {
+        if (typeof value.description === "string")
+            return value.description;
+        if (typeof value.$ref !== "string" || active.has(value.$ref))
+            return undefined;
+        active.add(value.$ref);
+        value = resolveReference(root, value.$ref);
+    }
+    return undefined;
+};
+const describeSchema = (schema, root, describeProperty) => {
+    if (!isObject(schema))
+        return schema;
+    return Object.fromEntries(Object.entries(schema).map(([key, value]) => {
+        if (schemaMaps.has(key) && isObject(value))
+            return [
+                key,
+                Object.fromEntries(Object.entries(value).map(([name, child]) => {
+                    const described = describeSchema(child, root, describeProperty);
+                    if (key !== "properties" || !isObject(described))
+                        return [name, described];
+                    const description = referencedDescription(root, described) ??
+                        describeProperty(name);
+                    return [
+                        name,
+                        description === undefined
+                            ? described
+                            : { ...described, description },
+                    ];
+                })),
+            ];
+        if (schemaArrays.has(key) && Array.isArray(value))
+            return [
+                key,
+                value.map((child) => describeSchema(child, root, describeProperty)),
+            ];
+        if (schemaChildren.has(key))
+            return [
+                key,
+                Array.isArray(value)
+                    ? value.map((child) => describeSchema(child, root, describeProperty))
+                    : describeSchema(value, root, describeProperty),
+            ];
+        // Annotation values and literal const/enum data are not schemas.
+        return [key, value];
+    }));
+};
+const objectBranch = (root, branch) => {
+    // Reference siblings evaluate separately from the target in 2020-12, so a
+    // merged object could accept inputs the branch rejects.
+    const resolved = isObject(branch) && typeof branch.$ref === "string"
+        ? Object.keys(branch).length === 1
+            ? resolveReference(root, branch.$ref)
+            : undefined
+        : branch;
+    return isObject(resolved) &&
+        resolved.type === "object" &&
+        isObject(resolved.properties)
+        ? resolved
+        : undefined;
+};
+const requiredProperties = (branch) => Array.isArray(branch.required)
+    ? branch.required.filter((name) => typeof name === "string")
+    : [];
+const sharedRequiredProperties = (branches) => {
+    const [first = [], ...others] = branches.map(requiredProperties);
+    return first.filter((name) => others.every((names) => names.includes(name)));
+};
+const inputGroup = (branch) => {
+    const required = requiredProperties(branch);
+    const optional = Object.keys(branch.properties ?? {})
+        .filter((name) => !required.includes(name))
+        .map((name) => `[${name}]`);
+    return [...required, ...optional].join(" + ");
+};
+// Anthropic tool input schemas reject anyOf, oneOf, and allOf at the root, and
+// clients then drop the tool or advertise it without parameters. Present a
+// root union of strict object groups as one object whose properties are the
+// union of the groups. The canonical Zod schema still enforces the exact group.
+const flattenRootObjectUnion = (root) => {
+    const { anyOf, oneOf, ...rest } = root;
+    const alternatives = Array.isArray(anyOf) ? anyOf : oneOf;
+    if (!Array.isArray(alternatives) ||
+        alternatives.length === 0 ||
+        root.properties !== undefined)
+        return root;
+    const branches = alternatives.map((branch) => objectBranch(root, branch));
+    if (!branches.every((branch) => branch !== undefined))
+        return root;
+    const variants = new Map();
+    for (const branch of branches)
+        for (const [name, schema] of Object.entries(branch.properties ?? {})) {
+            const known = variants.get(name) ?? [];
+            if (!known.some((seen) => isDeepStrictEqual(seen, schema)))
+                known.push(schema);
+            variants.set(name, known);
+        }
+    const required = sharedRequiredProperties(branches);
+    // A field unique to a group still needs that group's required partners.
+    // Counting properties alone would let optional fields pad an incomplete pair.
+    const dependencies = Object.fromEntries([...variants.keys()].flatMap((name) => {
+        const owners = branches.filter((branch) => Object.hasOwn(branch.properties ?? {}, name));
+        const partners = sharedRequiredProperties(owners).filter((partner) => partner !== name && !required.includes(partner));
+        return partners.length > 0 ? [[name, partners]] : [];
+    }));
+    const fewestRequired = Math.min(...branches.map((branch) => requiredProperties(branch).length));
+    // Groups that differ only in property values add no caller guidance.
+    const groups = [...new Set(branches.map(inputGroup))];
+    const description = [
+        typeof rest.description === "string" ? rest.description : undefined,
+        groups.length > 1
+            ? `Provide a complete input group: ${groups.join("; ")}.`
+            : undefined,
+    ].filter((text) => text !== undefined);
+    return {
+        ...rest,
+        type: "object",
+        ...(description.length > 0 ? { description: description.join(" ") } : {}),
+        properties: Object.fromEntries([...variants].map(([name, schemas]) => [
+            name,
+            schemas.length === 1 ? schemas[0] : { anyOf: schemas },
+        ])),
+        ...(required.length > 0 ? { required } : {}),
+        ...(fewestRequired > 0 ? { minProperties: fewestRequired } : {}),
+        ...(Object.keys(dependencies).length > 0
+            ? {
+                [root.$schema === "http://json-schema.org/draft-07/schema#"
+                    ? "dependencies"
+                    : "dependentRequired"]: dependencies,
+            }
+            : {}),
+        ...(branches.every((branch) => branch.additionalProperties === false)
+            ? { additionalProperties: false }
+            : {}),
+    };
+};
+/** Describe canonical input fields and present the root as one object. */
+export const presentInputJsonSchema = (root, describeProperty) => {
+    const flattened = flattenRootObjectUnion(root);
+    const described = describeSchema(flattened, flattened, describeProperty);
+    return isObject(described) ? described : flattened;
+};