rea-agents 6.3.0 → 6.5.0

package/dist/contracts/analysisViewToolContracts.js

@@ -1,19 +1,40 @@
+import { API_SURFACE_EXAMPLE } from "./analysisViewApiSurfaceExample.js";
 import { analysisViewResultSchema, inspectAnalysisViewInputSchema, } from "../domain/analysisView/analysisView.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
 const RETAINED_EXAMPLE_ID = `ev_${"a".repeat(64)}`;
-/** Selected views of already completed layout and JavaScript analysis Evidence. */
+/** Selected views of completed layout, JavaScript, native, inventory, WASM, Mach-O, Interface Builder and web network Evidence. */
 export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
     {
         name: "inspect_analysis_view",
         ...toolContractMetadata("inspect_analysis_view"),
         kind: "application",
-        description: "Inspect a selected view of completed binary-layout or JavaScript application Evidence without repeating analysis. Use an exact same-session retained evidence_id or portable inline Evidence. Select a summary, layout mitigations/linkage facet, one section/symbol/module, or a stable page with a positive limit. Module pages contain JavaScript assets, bundled modules and source modules; use node_id when paths are ambiguous or unavailable. Returns selected facts inline with artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the retained Evidence when needed.",
+        description: 'Inspect selected views of completed binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. For layout, JavaScript, inventory, WASM, Mach-O, Interface Builder, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, tool profile and execution/network states without reading WAT text. Select a layout mitigations/linkage facet, one section/symbol/module, or a stable page. Module pages include assets, bundled and source modules; use node_id for ambiguous or unavailable paths. Inventory uses view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json"], offset: 0, limit: 64}. Inventory views page nodes, occurrences, edges or integrity contradictions; occurrence logical_paths matches exact recorded strings (omitted means all available, [] means none). source_complete distinguishes complete inventories from partial source records; page exhaustion does not prove absence in a partial source. WASM views use kind wasm and facet sections/imports/exports/candidates/glue/wat/headers/details/tool_profile; text facets use UTF-16 code units and source forms remain exact. Mach-O views use kind macho and facet entrypoints/architectures/build_metadata/load_commands/dependencies/imports/exports/segments/provenance; source_exhaustive false means unreturned rows may exist. Interface Builder views use kind interface-builder and collection documents/nodes/edges/coverage; nodes and edges accept an exact document relative_path. EVM summary returns all inferred interface candidates, carrier/decoded identities and explicit unknowns without hex or duplicate stdout. EVM views use kind evm and facet functions/bytecode_hex/stdout/stderr; function pages preserve the original candidate rows, and text offsets/limits count UTF-16 code units (hex has two characters per decoded byte). Exhausting candidate pages does not establish global interface completeness. Managed artifact summaries preserve complete identity/classification, metadata status, module/MVID, frameworks, coverage and limitations without unrelated inventories. Managed pages use kind managed and collection references/resources/attributes, retaining source coverage and build-local token scope; page exhaustion does not establish complete metadata. Managed member summaries keep identity, selection with unmatched names, coverage and per-collection counts; managed-members pages use collection types/exported_types/fields/methods/member_refs/call_edges/field_accesses/user_strings and carry the source selection and coverage. Android package summaries retain all declarations, engine identity and counts without decoded manifest text. Android manifest pages use kind android, facet manifest, offset and limit in UTF-16 code units; source_status preserves partial decoded coverage even when the retained text page is exhausted. Dart AOT summary preserves target/ABI/library identity, snapshot headers and pool lower bounds. String pages use kind dart-aot, collection package_uris/dart_uris/class_like_tokens; source coverage remains partial when the producer says partial. Native function Evidence requires kind native: view: {kind: "native", facet: "procedure"}. Facets select procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings/names, native API and high-pcode. Use nonnegative offset and a positive caller-selected limit (defaults 0 and 64); pseudocode uses UTF-16 code units, other native pages use rows. Returns artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the complete retained Evidence if needed.',
         inputSchema: inspectAnalysisViewInputSchema,
         outputSchema: evidenceResultOf(analysisViewResultSchema),
         examples: [
             {
-                title: "Summarize retained JavaScript application Evidence",
+                title: "Read exact inventory paths from retained inspection Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "inventory",
+                        collection: "occurrences",
+                        logical_paths: ["package.json", "main.js"],
+                        offset: 0,
+                        limit: 32,
+                    },
+                },
+            },
+            {
+                title: "Group requests from retained HAR Evidence",
+                input: API_SURFACE_EXAMPLE.input,
+            },
+            {
+                title: "Summarize retained analysis Evidence, including WASM",
                 input: {
                     source: {
                         kind: "retained-evidence",
@@ -36,6 +57,21 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
                     },
                 },
             },
+            {
+                title: "Page native high-pcode operations from retained Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "native",
+                        facet: "value_flow_operations",
+                        offset: 0,
+                        limit: 32,
+                    },
+                },
+            },
             {
                 title: "Page module identities from retained application Evidence",
                 input: {

package/dist/contracts/android/androidToolContracts.js

@@ -1,4 +1,6 @@
-import { androidInputSchemas, androidResultSchemas, } from "../../domain/android/androidAnalysis.js";
+import { z } from "zod";
+import { androidInputSchemas, androidPackageInspectionInputSchema, androidResultSchemas, } from "../../domain/android/androidAnalysis.js";
+import { androidPackageSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js";
 import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
 import { toolContractMetadata } from "../toolEffects.js";
 /** Static APK operations backed by a separately supplied headless engine. */
@@ -6,18 +8,25 @@ export const ANDROID_TOOL_CONTRACTS = [
     {
         name: "inspect_android_package",
         ...toolContractMetadata("inspect_android_package"),
-        description: "Inspect a local APK's package, SDK and permission declarations, decoded manifest and class/resource counts. Does not execute the APK or verify signatures. Requires a caller-supplied JADX MCP JAR and JDK; uses one worker in an isolated temporary workspace.",
+        description: 'Inspect a local APK\'s package, SDK and permission declarations, decoded manifest and class/resource counts. Omitted or complete detail preserves the complete result. Select detail: "summary" for all declarations, engine identity and counts without decoded manifest text or duplicate raw calls; retains the complete source and returns a distinct linked inspect_analysis_view summary. Read the exact retained manifest with view kind android, facet manifest, offset and limit (UTF-16 code units), using normalized_result.parent_evidence_id. Does not execute the APK or verify signatures. Requires a caller-supplied JADX MCP JAR and JDK; uses one worker in an isolated temporary workspace.',
         kind: "android-provider",
-        inputSchema: androidInputSchemas.inspect_android_package,
-        outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_package),
+        inputSchema: androidPackageInspectionInputSchema,
+        outputSchema: evidenceResultOf(z.union([
+            androidResultSchemas.inspect_android_package,
+            androidPackageSummaryViewResultSchema,
+        ])),
         examples: [
             { title: "Inspect an APK", input: { path: "/tmp/Example.apk" } },
+            {
+                title: "Inspect APK declarations with retained manifest",
+                input: { path: "/tmp/Example.apk", detail: "summary" },
+            },
         ],
     },
     {
         name: "search_android_classes",
         ...toolContractMetadata("search_android_classes"),
-        description: "Search complete decompiler class names in an explicit local APK by case-sensitive substring. Empty query inventories all classes. Retains artifact and engine identity; no APK execution.",
+        description: "Search complete decompiler class-name rows in an explicit local APK by case-sensitive substring. Empty query inventories all rows. Repeated names remain repeated and appear in duplicate_names; the provider accepts only class names for lookup, so these rows do not identify which same-name class node a later lookup selects. Retains artifact and engine identity; no APK execution.",
         kind: "android-provider",
         inputSchema: androidInputSchemas.search_android_classes,
         outputSchema: evidenceResultOf(androidResultSchemas.search_android_classes),
@@ -31,7 +40,7 @@ export const ANDROID_TOOL_CONTRACTS = [
     {
         name: "inspect_android_class",
         ...toolContractMetadata("inspect_android_class"),
-        description: "Inspect one exact Android class's parsed methods, fields and inner classes, including synthetic members. Returns display signatures and explicit unknown DEX descriptors without generating source. Overload indices remain consistent within the artifact and engine session.",
+        description: "Inspect one exact Android class's parsed methods, fields and inner classes, including synthetic members. Returns display signatures and exact DEX prototypes without generating source. A prototype is not a complete raw method ID; overload indices remain consistent within the artifact and engine session.",
         kind: "android-provider",
         inputSchema: androidInputSchemas.inspect_android_class,
         outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_class),
@@ -45,7 +54,7 @@ export const ANDROID_TOOL_CONTRACTS = [
     {
         name: "inspect_android_method",
         ...toolContractMetadata("inspect_android_method"),
-        description: "Decompile one Android method with smali fallback. Requires explicit overload_index when multiple methods share a name. Reports representation, fallback markers and source truncation; never treats display signatures as exact DEX identities.",
+        description: "Decompile one Android method with smali fallback. Requires explicit overload_index when multiple methods share a name. Reports its DEX prototype, representation, fallback markers and source truncation; display signatures may be aliases.",
         kind: "android-provider",
         inputSchema: androidInputSchemas.inspect_android_method,
         outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_method),
@@ -63,7 +72,7 @@ export const ANDROID_TOOL_CONTRACTS = [
     {
         name: "trace_android_references",
         ...toolContractMetadata("trace_android_references"),
-        description: "Trace incoming static references to an exact Android class or unique method. Overloaded method reference queries are explicitly unsupported by the current engine. Source lines and DEX offsets remain unknown; no runtime calls are inferred.",
+        description: "Trace incoming static using nodes to an exact Android class or selected method overload. The total counts containing nodes, not individual invoke instructions. Use inspect_android_class to choose an overload_index when names collide. Source lines and the containing node dex_offset remain unknown. direct_invokes carries exact DEX code-unit instruction offsets when available; direct_invokes_exhaustive false marks byte-bounded partial instruction evidence, and null means coverage is unknown. Using-node coverage remains separate; no runtime calls are inferred.",
         kind: "android-provider",
         inputSchema: androidInputSchemas.trace_android_references,
         outputSchema: evidenceResultOf(androidResultSchemas.trace_android_references),

package/dist/contracts/apktool/apktoolToolContracts.js

@@ -0,0 +1,33 @@
+import { apktoolInputSchemas, apktoolResultSchemas, } from "../../domain/apktool/apktoolResourceAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** Apktool resource decoding served by a caller-supplied launcher. */
+export const APKTOOL_TOOL_CONTRACTS = [
+    {
+        name: "inspect_apktool_client",
+        ...toolContractMetadata("inspect_apktool_client"),
+        description: "Inspect the caller-selected apktool launcher: resolved command, selection source, and version. Decodes nothing. REA never installs Apktool or Java; select a launcher with REA_APKTOOL_COMMAND (absolute) or apktool on PATH.",
+        kind: "apktool-provider",
+        inputSchema: apktoolInputSchemas.inspect_apktool_client,
+        outputSchema: evidenceResultOf(apktoolResultSchemas.inspect_apktool_client),
+        examples: [{ title: "Check the Apktool launcher", input: {} }],
+    },
+    {
+        name: "decode_android_resources",
+        ...toolContractMetadata("decode_android_resources"),
+        description: "Decode one local APK's resources with `apktool d --no-src` in a provider-owned workspace that is removed after projection: the readable AndroidManifest.xml, apktool.yml version and SDK facts, the app's string resources (default or one locale, bounded to 2000 entries), available string locales, and the decoded file count. The target APK is digest with SHA-256 before decoding; smali is skipped because Java-source recovery belongs to the JADX family.",
+        kind: "apktool-provider",
+        inputSchema: apktoolInputSchemas.decode_android_resources,
+        outputSchema: evidenceResultOf(apktoolResultSchemas.decode_android_resources),
+        examples: [
+            {
+                title: "Decode an APK's resources",
+                input: { path: "/targets/Example.apk" },
+            },
+            {
+                title: "Decode one locale's strings",
+                input: { path: "/targets/Example.apk", locale: "de" },
+            },
+        ],
+    },
+];

package/dist/contracts/applicationToolContracts.js

@@ -9,11 +9,12 @@ import { reconstructionClosureResultSchema } from "../domain/reconstructionCover
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
 import { androidApplicationProjectionInputSchema, androidApplicationProjectionResultSchema, } from "../domain/android/androidApplication.js";
 import { appleApplicationProjectionInputSchema, appleApplicationProjectionResultSchema, } from "../domain/apple/appleApplication.js";
+import { harmonyApplicationProjectionInputSchema, harmonyApplicationProjectionResultSchema, } from "../domain/harmony/harmonyApplication.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
 import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascript/javascriptApplicationWorkflowExamples.js";
 import { JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE } from "./javascript/javascriptExportShapeComparisonExample.js";
-import { ANDROID_APPLICATION_GRAPH_EXAMPLE, APPLE_APPLICATION_GRAPH_EXAMPLE, MACOS_APPLICATION_GRAPH_EXAMPLE, } from "./mobileApplicationGraphExamples.js";
+import { ANDROID_APPLICATION_GRAPH_EXAMPLE, APPLE_APPLICATION_GRAPH_EXAMPLE, HARMONY_APPLICATION_GRAPH_EXAMPLE, MACOS_APPLICATION_GRAPH_EXAMPLE, } from "./mobileApplicationGraphExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
 const semanticTraceOutputSchema = evidenceResultOf(javaScriptSemanticTraceResultSchema);
 const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
@@ -158,7 +159,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "evaluate_reconstruction_coverage",
         ...toolContractMetadata("evaluate_reconstruction_coverage"),
-        description: "Evaluate inline evidence-backed reconstruction coverage against one named boundary. Missing ownership or inventory is partial; stale, weak, truncated, skipped, or unresolved proof is unknown; contradictions, failed proof, missing owners, and authority routing fail closed.",
+        description: "Evaluate inline evidence-backed reconstruction coverage against one named boundary. Missing ownership or inventory is partial; stale, weak, truncated, skipped, unresolved, or conflicting tied verifier proof is unknown; contradictions, failed proof, missing owners, and authority routing fail closed.",
         kind: "application",
         inputSchema: reconstructionCoverageEvaluationInputSchema,
         outputSchema: reconstructionClosureResultSchema,
@@ -237,6 +238,20 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "project_harmony_application_graph",
+        ...toolContractMetadata("project_harmony_application_graph"),
+        description: "Project authenticated HarmonyOS HAP, HSP, or App Pack inventory Evidence into an execution-free application inventory. Reports packaging-model hints (Stage module.json versus FA config.json), exact component paths and hashes (manifests, Ark bytecode, resources, native libraries, JavaScript, signing), App Pack child packages, runtime-family hints, and path-based N-API bridge hypotheses without decoding Ark bytecode, parsing manifest semantics, or claiming observed runtime calls.",
+        kind: "application",
+        inputSchema: harmonyApplicationProjectionInputSchema,
+        outputSchema: evidenceResultOf(harmonyApplicationProjectionResultSchema),
+        examples: [
+            {
+                title: "Project HAP inventory Evidence into a HarmonyOS application graph",
+                input: HARMONY_APPLICATION_GRAPH_EXAMPLE,
+            },
+        ],
+    },
 ];
 export function applicationToolContract(name) {
     const contract = APPLICATION_TOOL_CONTRACTS.find(({ name: candidate }) => candidate === name);

package/dist/contracts/artifactToolContracts.js

@@ -1,19 +1,30 @@
 import { z } from "zod";
 import { artifactOutputSchemas } from "./toolOutputSchemaGroups.js";
+import { artifactIntegrityPolicySchema } from "../domain/artifactIntegrityPolicy.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
 import { appleAssetCatalogInputSchema } from "../domain/apple/appleAssetCatalog.js";
 import { dylibResolutionInputSchema } from "../domain/apple/dylibResolution.js";
 import { keyedArchiveInputSchema } from "../domain/apple/keyedArchive.js";
+import { analysisDetailSchema } from "./analysisDetail.js";
 /** Exact caller boundary for deterministic artifact inventory. */
 export const artifactInventoryInputSchema = z.strictObject({
-    integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
+    integrity_policy: artifactIntegrityPolicySchema,
+});
+/** Delivery selection belongs to the adapter, not the inventory producer. */
+export const artifactInspectionInputSchema = artifactInventoryInputSchema.extend({
+    detail: analysisDetailSchema
+        .unwrap()
+        .optional()
+        .describe("Omitted or complete returns the complete inspection Evidence. summary retains that complete Evidence in this session and returns its inspect_analysis_view summary; use normalized_result.parent_evidence_id for inventory views."),
 });
 /** Extraction needs no selector: it materializes every regular child file. */
-export const artifactExtractionInputSchema = z.strictObject({});
+export const artifactExtractionInputSchema = z.strictObject({
+    integrity_policy: artifactIntegrityPolicySchema,
+});
 /** Provider input containing the destination chosen by the local adapter. */
-export const artifactExtractionExecutionSchema = z.strictObject({
+export const artifactExtractionExecutionSchema = artifactExtractionInputSchema.extend({
     output_root: z.string().min(1),
 });
 const exampleInputSchema = z.record(z.string(), jsonValueSchema);
@@ -47,12 +58,16 @@ const artifact = (name, description, inputSchema) => {
 };
 /** Artifact-graph inventory and safe extraction contracts. */
 export const ARTIFACT_TOOL_CONTRACTS = [
-    artifact("inspect_artifact", "Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph, source Evidence, observations, relationships, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.", artifactInventoryInputSchema),
-    artifact("extract_artifact", "Extract all regular files from the active archive or application package into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, enforces archive integrity checks, and verifies cleanup.", artifactExtractionInputSchema),
-    artifact("decode_interface_builder", "Decode compiled storyboard and nib archives inside the active Apple app bundle, including keyed property lists and NIBArchive object tables, into a bounded object, hierarchy, and connection graph. This is static archive parsing; unrecognized archive classes and unresolved code handlers remain explicit unknowns.", z.strictObject({
+    artifact("inspect_artifact", "Inspect an active archive or application package in one call. By default returns the complete content-addressed artifact graph once, as the typed nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Optional detail summary retains the complete inspection and returns its derived summary view; read exact paths or inventory pages with inspect_analysis_view using parent_evidence_id. This changes delivery, not inventory coverage. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.", artifactInspectionInputSchema),
+    artifact("extract_artifact", "Extract all regular files from the active archive or application package into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, and verifies cleanup. Integrity mismatches fail by default; record-and-continue extracts the observed bytes and returns each mismatch as an explicitly untrusted integrity contradiction.", artifactExtractionInputSchema),
+    artifact("decode_interface_builder", "Decode compiled storyboard and nib archives inside the active Apple app bundle, including keyed property lists and NIBArchive object tables, into a bounded object, hierarchy, and connection graph. This is static archive parsing; unrecognized archive classes and unresolved code handlers remain explicit unknowns. A full app graph is often several megabytes; detail summary retains it and returns documents with node, edge and coverage counts, then page rows, optionally one document's, with inspect_analysis_view kind interface-builder.", z.strictObject({
         max_documents: z.number().int().min(1).max(64).default(64),
         max_objects: z.number().int().min(1).max(20_000).default(20_000),
         max_connections: z.number().int().min(1).max(40_000).default(40_000),
+        detail: analysisDetailSchema
+            .unwrap()
+            .optional()
+            .describe("Omitted or complete returns the complete decoded graph Evidence. summary retains that complete Evidence in this session and returns its inspect_analysis_view summary; use normalized_result.parent_evidence_id for interface-builder pages."),
     })),
     artifact("inspect_keyed_archive", "Inspect one Foundation NSKeyedArchiver plist in the active app bundle as original object-table nodes, class descriptors, named roots, and UID edges. Preserves shared and cyclic references without instantiating classes. The path is relative to the bundle; root selection and object pagination preserve original identities.", keyedArchiveInputSchema),
     artifact("inspect_asset_catalog", "Inspect compiled Assets.car metadata in an active Apple app bundle. Returns stable paginated catalog and rendition records with raw assetutil metadata and catalog digests; rendition bytes are not extracted.", appleAssetCatalogInputSchema),

package/dist/contracts/browserToolContracts.js

@@ -54,6 +54,7 @@ const exampleScenarioCapture = () => ({
             response_body: false,
             header_values: false,
         },
+        event_families: [],
     },
     duration_ms: 10,
     steps: [
@@ -186,7 +187,7 @@ export const BROWSER_TOOL_CONTRACTS = [
     {
         name: "compare_web_captures",
         ...toolContractMetadata("compare_web_captures"),
-        description: "Compare passive web captures by providing before and after, each with the complete inspect_web_page normalized_result in inspection and an optional complete discover_webmcp_tools normalized_result in webmcp; or compare recorded scenarios by passing complete capture_browser_scenario normalized_result objects in before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
+        description: "Compare passive web captures by providing before and after, each with the complete inspect_web_page normalized_result in inspection and an optional complete discover_webmcp_tools normalized_result in webmcp; or compare recorded scenarios by passing complete capture_browser_scenario normalized_result objects in before_scenario and after_scenario with an optional normalization policy. Use exactly one input group. Network comparison includes observed HTTP requests and WebSocket frame streams; same-URL connections are compared as an unordered collection of ordered streams, retaining connection counts without claiming stable identity between individual connections. Scenario comparison aligns exact step IDs, records deterministic literal normalization, and returns every artifact-level difference plus alignment failures inline. Missing or truncated evidence never proves equality.",
         kind: "browser-provider",
         inputSchema: browserCaptureComparisonInputSchema,
         outputSchema: captureDiffOutputSchema,

package/dist/contracts/captures/captureToolContracts.js

@@ -0,0 +1,42 @@
+import { inspectPacketFieldsInputSchema, packetFieldsCatalogSchema, } from "../../domain/captures/packetFields.js";
+import { inspectPacketCaptureInputSchema, packetCaptureSchema, } from "../../domain/captures/packetCapture.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+export const CAPTURE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_packet_fields",
+        ...toolContractMetadata("inspect_packet_fields"),
+        kind: "artifact-provider",
+        description: "Discover protocols or field names/types registered in the installed TShark 4.x. kind defaults to protocols; use fields and optional exact protocol abbreviation to select field definitions. query searches name/abbreviation/description by case-insensitive literal substring. Return 50 matches by default with offset/limit paging; null requests all remaining within resource limits. Preserve type/base/bitmask/description, duplicate registrations, source line numbers, coverage, tool identity and diagnostics. Linux, REA_TSHARK_COMMAND and prlimit required. No capture file, interface or binary target needed. Registrations describe tool capabilities, not observed traffic. Each call rereads the glossary; use selected fields with inspect_packet_capture.",
+        inputSchema: inspectPacketFieldsInputSchema,
+        outputSchema: evidenceResultOf(packetFieldsCatalogSchema),
+        examples: [
+            { title: "Find USB protocol registrations", input: { query: "usb" } },
+            {
+                title: "Find the installed USB vendor-ID field",
+                input: { kind: "fields", protocol: "usb", query: "idVendor" },
+            },
+        ],
+    },
+    {
+        name: "inspect_packet_capture",
+        ...toolContractMetadata("inspect_packet_capture"),
+        kind: "artifact-provider",
+        description: "Inspect caller-selected fields in an existing local packet capture with TShark 4.x. Return 50 matching frames by default, with match_offset/match_limit paging and coverage counts; match_limit:null requests all remaining matches. Preserve repeated values, frame numbers, display filter, decode-as rules and pass mode in inline Evidence with source/tool identity and diagnostics. Optional packet_limit counts input packets before filtering; output paging does not shorten dissection or two-pass reassembly. Requires Linux, util-linux prlimit, and absolute REA_TSHARK_COMMAND. File-only analysis; no live capture or device communication. Missing fields or no matches do not establish absence of device traffic.",
+        inputSchema: inspectPacketCaptureInputSchema,
+        outputSchema: evidenceResultOf(packetCaptureSchema),
+        examples: [
+            {
+                title: "Inspect UDP exchanges in a recording",
+                input: {
+                    path: "/artifacts/device.pcapng",
+                    fields: ["ip.addr", "udp.port", "data.data"],
+                    display_filter: "udp",
+                    decode_as: [],
+                    packet_limit: null,
+                    two_pass: true,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/compactInputSchema.js

@@ -0,0 +1,276 @@
+import { schemaArrays, schemaChildren, schemaMaps, } from "./inputSchemaPresentation.js";
+// Kimi expands schema-local references before sending tools to Moonshot.
+// Compact advertisements must fit after expansion, independently of client
+// reference handling. Canonical server-side validation remains unchanged.
+/** Annotation keys that carry guidance but no validation semantics. */
+const annotationKeys = new Set(["description", "examples", "default", "title"]);
+/** Keys whose values are literal data, never nested schemas to rewrite. */
+const dataKeys = new Set(["const", "enum", "examples", "default"]);
+const definitionKeys = new Set(["$defs", "definitions"]);
+// An empty schema accepts every JSON value. Kimi otherwise infers string.
+const jsonValueTypes = [
+    "null",
+    "boolean",
+    "object",
+    "array",
+    "number",
+    "string",
+];
+const isSchemaObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const schemaDepth = (value, depth = 0) => {
+    if (Array.isArray(value))
+        return Math.max(depth, ...value.map((child) => schemaDepth(child, depth + 1)));
+    if (!isSchemaObject(value))
+        return depth;
+    return Math.max(depth, ...Object.values(value).map((child) => schemaDepth(child, depth + 1)));
+};
+/** Strict clients commonly reject advertised schemas deeper than ten nodes. */
+const COMPACT_SCHEMA_MAX_DEPTH = 10;
+/** Rewrite every schema-valued position; literal data stays opaque. */
+const rebuildSchemaPositions = (node, rebuild) => {
+    if (Array.isArray(node))
+        return node.map((child) => rebuild(child));
+    if (!isSchemaObject(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (dataKeys.has(key)) {
+            out[key] = value;
+            continue;
+        }
+        if (schemaMaps.has(key) && isSchemaObject(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, rebuild(child)]));
+            continue;
+        }
+        if (schemaArrays.has(key) && Array.isArray(value)) {
+            out[key] = value.map((child) => rebuild(child));
+            continue;
+        }
+        if (schemaChildren.has(key)) {
+            out[key] = Array.isArray(value)
+                ? value.map((child) => rebuild(child))
+                : rebuild(value);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+};
+/**
+ * Drop annotation prose from every subschema while preserving all validation
+ * keywords. The root keeps its own description because the root-union
+ * projection encodes accepted input groups there; the root's echoed literal
+ * examples leave with the rest of the annotation prose.
+ */
+const stripAnnotations = (schema) => {
+    const rebuilt = rebuildSchemaPositions(schema, stripChildAnnotations);
+    const out = {};
+    for (const [key, value] of Object.entries(rebuilt)) {
+        if (annotationKeys.has(key) && key !== "description")
+            continue;
+        out[key] = value;
+    }
+    return out;
+};
+const stripChildAnnotations = (child) => {
+    const rebuilt = rebuildSchemaPositions(child, stripChildAnnotations);
+    if (!isSchemaObject(rebuilt))
+        return rebuilt;
+    const kept = {};
+    for (const [key, value] of Object.entries(rebuilt))
+        if (!annotationKeys.has(key))
+            kept[key] = value;
+    return kept;
+};
+const resolveLocalReference = (root, reference) => {
+    if (reference === "#")
+        return root;
+    if (!reference.startsWith("#/"))
+        return undefined;
+    let value = root;
+    for (const token of reference.slice(2).split("/")) {
+        const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (!isSchemaObject(value) || !Object.hasOwn(value, key))
+            return undefined;
+        value = value[key];
+    }
+    return value;
+};
+/** Stop serialization at the budget before allocating an expanded schema. */
+const inlineWithinBudget = (root, budgetBytes) => {
+    let resolved = true;
+    function* serialize(value, position, active) {
+        if (Array.isArray(value)) {
+            yield "[";
+            for (const [index, child] of value.entries()) {
+                if (index > 0)
+                    yield ",";
+                yield* serialize(child, position, active);
+            }
+            yield "]";
+        }
+        else if (isSchemaObject(value)) {
+            if (position === "schema" && Object.keys(value).length === 0) {
+                yield JSON.stringify({ type: jsonValueTypes });
+                return;
+            }
+            if (position === "schema" && typeof value.$ref === "string") {
+                const target = resolveLocalReference(root, value.$ref);
+                if (target === undefined || active.has(value.$ref)) {
+                    resolved = false;
+                    return;
+                }
+                const { $ref, ...siblings } = value;
+                // Reference siblings are independent constraints in draft 2020-12.
+                // Merging their keys into the target would overwrite validation rules.
+                yield* serialize(Object.keys(siblings).length === 0
+                    ? target
+                    : { allOf: [target, siblings] }, "schema", new Set([...active, $ref]));
+                return;
+            }
+            yield "{";
+            let first = true;
+            for (const [key, child] of Object.entries(value)) {
+                if (position === "schema" && definitionKeys.has(key))
+                    continue;
+                if (!first)
+                    yield ",";
+                first = false;
+                yield JSON.stringify(key) + ":";
+                const childPosition = position === "map"
+                    ? "schema"
+                    : position === "schema" && schemaMaps.has(key)
+                        ? "map"
+                        : position === "schema" &&
+                            (schemaArrays.has(key) || schemaChildren.has(key))
+                            ? "schema"
+                            : "data";
+                yield* serialize(child, childPosition, active);
+            }
+            yield "}";
+        }
+        else {
+            yield JSON.stringify(value);
+        }
+    }
+    const chunks = [];
+    let bytes = 0;
+    for (const chunk of serialize(root, "schema", new Set())) {
+        bytes += Buffer.byteLength(chunk, "utf8");
+        if (bytes > budgetBytes || !resolved)
+            return undefined;
+        chunks.push(chunk);
+    }
+    return resolved
+        ? JSON.parse(chunks.join(""))
+        : undefined;
+};
+/** Preserve every possible type, including referenced and nullable unions. */
+const detectedTypes = (schema, root, active = new Set()) => {
+    if (!isSchemaObject(schema))
+        return undefined;
+    if (typeof schema.$ref === "string") {
+        if (active.has(schema.$ref))
+            return undefined;
+        return detectedTypes(resolveLocalReference(root, schema.$ref), root, new Set([...active, schema.$ref]));
+    }
+    if (typeof schema.type === "string")
+        return [schema.type];
+    if (Array.isArray(schema.type) &&
+        schema.type.every((type) => typeof type === "string"))
+        return schema.type;
+    const alternatives = Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : Array.isArray(schema.oneOf)
+            ? schema.oneOf
+            : [];
+    if (alternatives.length === 0)
+        return undefined;
+    const types = alternatives.map((branch) => detectedTypes(branch, root, active));
+    if (types.some((type) => type === undefined))
+        return undefined;
+    return [...new Set(types.flatMap((type) => type ?? []))];
+};
+const REDUCED_ANNOTATION = "Advertised in reduced form by the compact input schema profile; the server still validates complete canonical inputs.";
+/**
+ * Present only the root property shape with per-property guidance. Used for
+ * schemas whose validation structure alone exceeds the compact budget; the
+ * canonical schema still rejects malformed calls server-side.
+ */
+const reduceToShallowProperties = (schema) => {
+    const properties = isSchemaObject(schema.properties) ? schema.properties : {};
+    const description = [
+        typeof schema.description === "string" ? schema.description : undefined,
+        ...Object.entries(isSchemaObject(schema.dependentRequired)
+            ? schema.dependentRequired
+            : isSchemaObject(schema.dependencies)
+                ? schema.dependencies
+                : {}).flatMap(([property, partners]) => Array.isArray(partners) &&
+            partners.every((partner) => typeof partner === "string")
+            ? [
+                `When ${property} is provided, also provide ${partners.join(" and ")}.`,
+            ]
+            : []),
+        REDUCED_ANNOTATION,
+    ]
+        .filter((text) => text !== undefined)
+        .join(" ");
+    const shallow = Object.fromEntries(Object.entries(properties).map(([name, value]) => {
+        const types = detectedTypes(value, schema);
+        const type = types?.length === 1 ? types[0] : types;
+        const description = isSchemaObject(value) && typeof value.description === "string"
+            ? { description: value.description }
+            : {};
+        return [
+            name,
+            { ...(type === undefined ? {} : { type }), ...description },
+        ];
+    }));
+    return {
+        ...(typeof schema.$schema === "string" ? { $schema: schema.$schema } : {}),
+        type: "object",
+        description,
+        properties: shallow,
+        ...(Array.isArray(schema.required)
+            ? { required: [...schema.required] }
+            : {}),
+        ...(typeof schema.minProperties === "number"
+            ? { minProperties: schema.minProperties }
+            : {}),
+        ...(schema.additionalProperties === false
+            ? { additionalProperties: false }
+            : {}),
+    };
+};
+/**
+ * Render an advertised input schema within a per-schema byte budget for
+ * providers that validate the literal serialized schema size. Validation
+ * keywords and the canonical contract are preserved; only
+ * annotation prose and, for structurally oversized schemas, nested
+ * validation detail leave the advertised form.
+ */
+export const compactAdvertisedInputSchema = (schema, budgetBytes) => {
+    const inline = inlineWithinBudget(stripAnnotations(schema), budgetBytes);
+    if (inline !== undefined && schemaDepth(inline) <= COMPACT_SCHEMA_MAX_DEPTH)
+        return { schema: inline, presentation: "inline" };
+    const reduced = reduceToShallowProperties(schema);
+    if (serializedBytes(reduced) <= budgetBytes)
+        return { schema: reduced, presentation: "reduced" };
+    // A future contract with an extreme root-property count still advertises
+    // an honest, budget-fitting shape instead of an oversized one.
+    return {
+        schema: reduceToShallowProperties({
+            type: "object",
+            description: (typeof schema.description === "string"
+                ? `${schema.description} `
+                : "") + REDUCED_ANNOTATION,
+        }),
+        presentation: "reduced",
+    };
+};
+/** Return the JSON schema clients receive for the selected input presentation. */
+export const presentAdvertisedInputSchema = (schema, compactPresentation) => compactPresentation === undefined
+    ? schema
+    : compactAdvertisedInputSchema(schema, compactPresentation.budgetBytes)
+        .schema;