Files
rea/src/contracts/captures/captureToolContracts.ts
T
9c34c091b3 feat(captures): discover installed protocol and field definitions (#2496)
* feat(captures): discover installed protocol and field definitions

* test(captures): isolate the direct glossary oracle profile

* test(captures): accept padded kernel limit reports

* fix(captures): detach every retained glossary column

* fix(captures): describe every field discovery CLI option

* fix(captures): retain discovery operation across cleanup retries

---------

Co-authored-by: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com>
2026-10-13 15:55:25 +09:00

52 lines
3.0 KiB
TypeScript

import {
inspectPacketFieldsInputSchema,
packetFieldsCatalogSchema,
} from "../../domain/captures/packetFields.js";
import {
inspectPacketCaptureInputSchema,
packetCaptureSchema,
} from "../../domain/captures/packetCapture.js";
import type { ToolContract } from "../toolContractTypes.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,
},
},
],
},
] as const satisfies readonly ToolContract[];