rea-agents 1.7.0 → 2.1.0

package/dist/contracts/toolEffects.js

@@ -0,0 +1,174 @@
+const effects = (overrides = {}) => ({
+    mutatesTarget: false,
+    mutatesSession: false,
+    writesFilesystem: false,
+    launchesProcess: false,
+    accessesNetwork: false,
+    changesUiState: false,
+    mayDiscardData: false,
+    idempotent: true,
+    ...overrides,
+});
+const evidence = effects({ mutatesSession: true });
+const nativeEvidence = effects({ mutatesSession: true, launchesProcess: true });
+const browserEvidence = effects({
+    mutatesSession: true,
+    accessesNetwork: true,
+});
+const sessionEvidence = effects({ mutatesSession: true });
+/** Explicit effect audit for every public tool. */
+export const TOOL_EFFECTS = {
+    address_name: evidence,
+    comment: evidence,
+    current_address: evidence,
+    current_procedure: evidence,
+    current_document: evidence,
+    goto_address: effects({ mutatesSession: true, changesUiState: true }),
+    inline_comment: evidence,
+    list_bookmarks: evidence,
+    list_documents: evidence,
+    list_names: evidence,
+    list_procedures: evidence,
+    list_segments: evidence,
+    list_strings: evidence,
+    next_address: evidence,
+    prev_address: evidence,
+    procedure_address: evidence,
+    procedure_assembly: evidence,
+    procedure_callees: evidence,
+    procedure_callers: evidence,
+    procedure_info: evidence,
+    procedure_references: evidence,
+    procedure_pseudo_code: evidence,
+    resolve_containing_procedure: evidence,
+    search_procedures: evidence,
+    search_strings: evidence,
+    set_address_name: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_addresses_names: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_bookmark: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_comment: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_current_document: effects({ mutatesSession: true, changesUiState: true }),
+    set_inline_comment: effects({ mutatesTarget: true, mutatesSession: true }),
+    unset_bookmark: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        mayDiscardData: true,
+    }),
+    xrefs: evidence,
+    swift_classes: evidence,
+    get_objc_classes: evidence,
+    get_objc_protocols: evidence,
+    batch_decompile: evidence,
+    get_call_graph: evidence,
+    analyze_swift_types: evidence,
+    find_xrefs_to_name: evidence,
+    binary_overview: evidence,
+    analyze_function: evidence,
+    trace_feature: effects({ mutatesSession: true, idempotent: false }),
+    inspect_macho: nativeEvidence,
+    inspect_signature: nativeEvidence,
+    inspect_plist: nativeEvidence,
+    list_architectures: nativeEvidence,
+    demangle_swift: nativeEvidence,
+    inventory_artifact: evidence,
+    extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }),
+    inspect_managed_artifact: evidence,
+    inspect_managed_members: evidence,
+    inspect_managed_native_boundaries: evidence,
+    compare_managed_members: sessionEvidence,
+    verify_managed_native_boundaries: sessionEvidence,
+    import_managed_reconstruction: sessionEvidence,
+    plan_managed_runtime_correlation: sessionEvidence,
+    project_managed_application_graph: sessionEvidence,
+    list_browser_targets: browserEvidence,
+    inspect_web_page: browserEvidence,
+    analyze_web_bundle: browserEvidence,
+    observe_web_session: browserEvidence,
+    discover_webmcp_tools: browserEvidence,
+    compare_web_captures: browserEvidence,
+    capture_web_screenshot: browserEvidence,
+    compare_web_screenshots: browserEvidence,
+    list_electron_targets: browserEvidence,
+    inspect_electron_page: browserEvidence,
+    analyze_javascript_application: evidence,
+    reconcile_javascript_runtime: evidence,
+    trace_application_feature: evidence,
+    compare_application_versions: evidence,
+    run_controlled_replay: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    prepare_node_characterization: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+    }),
+    execute_node_characterization: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    commit_reconstruction_coverage: effects({
+        writesFilesystem: true,
+        mutatesSession: true,
+    }),
+    query_reconstruction_coverage: effects({ mutatesSession: true }),
+    open_binary: effects({ mutatesSession: true, launchesProcess: true }),
+    close_binary: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
+    binary_session: effects(),
+    export_evidence_bundle: effects({
+        writesFilesystem: true,
+        mayDiscardData: true,
+    }),
+    import_evidence_bundle: effects({ mutatesSession: true }),
+    capture_process_scenario: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        idempotent: false,
+    }),
+    compare_process_captures: sessionEvidence,
+    compare_artifacts: sessionEvidence,
+    compare_functions: sessionEvidence,
+    compare_bundles: effects({ mutatesSession: true }),
+    find_changed_behavior: sessionEvidence,
+    build_call_path: sessionEvidence,
+    correlate_static_and_runtime: sessionEvidence,
+    verify_reconstruction: sessionEvidence,
+    list_unknowns: effects(),
+    record_unknown: effects({ mutatesSession: true, idempotent: false }),
+    update_unknown: effects({ mutatesSession: true, idempotent: false }),
+    verify_unknown_resolution: effects(),
+};
+/** Derive MCP annotations without tool-name or tool-family heuristics. */
+export const annotationsFromEffects = (value) => ({
+    readOnlyHint: !(value.mutatesTarget ||
+        value.mutatesSession ||
+        value.writesFilesystem ||
+        value.launchesProcess ||
+        value.accessesNetwork ||
+        value.changesUiState ||
+        value.mayDiscardData),
+    destructiveHint: value.mayDiscardData,
+    idempotentHint: value.idempotent,
+    openWorldHint: value.launchesProcess || value.accessesNetwork,
+});
+/** Resolve the audited metadata for one public tool. */
+export const toolContractMetadata = (name) => {
+    const audited = TOOL_EFFECTS[name];
+    if (audited === undefined)
+        throw new Error(`Missing effect audit for ${name}`);
+    return {
+        title: name
+            .split("_")
+            .map((word) => word[0]?.toUpperCase() + word.slice(1))
+            .join(" "),
+        effects: audited,
+        annotations: annotationsFromEffects(audited),
+    };
+};

package/dist/contracts/toolOutputSchemaGroups.js

@@ -0,0 +1,232 @@
+import { z } from "zod";
+import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
+import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
+import { residualUnknownSchema } from "../domain/residualUnknown.js";
+import { referenceKindSchema } from "../domain/hopperValues.js";
+import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
+import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
+import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
+import { managedReconstructionImportResultSchema } from "../domain/managedReconstruction.js";
+import { managedRuntimeCorrelationResultSchema } from "../domain/managedRuntimeCorrelation.js";
+import { managedApplicationGraphResultSchema } from "../domain/managedApplicationGraph.js";
+import { artifactComparisonResultSchema } from "../domain/artifactComparison.js";
+import { functionComparisonResultSchema } from "../domain/functionComparison.js";
+import { bundleComparisonResultSchema } from "../domain/bundleComparison.js";
+import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
+import { callPathResultSchema } from "../domain/callPath.js";
+import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
+import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
+import { analysisErrorProjectionSchema } from "./errorSchemas.js";
+import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+/** Exact structured-content schemas shared by direct analysis providers. */
+export const officialOutputSchemas = {
+    address_name: resultOf(nullableText),
+    comment: resultOf(nullableText),
+    current_address: resultOf(z.string()),
+    current_procedure: resultOf(z.string()),
+    current_document: resultOf(z.string()),
+    goto_address: resultOf(z.string()),
+    inline_comment: resultOf(nullableText),
+    list_bookmarks: resultOf(z.array(addressedEntry)),
+    list_documents: resultOf(z.array(z.string())),
+    list_names: resultOf(pageOutput),
+    list_procedures: resultOf(pageOutput),
+    list_segments: segmentOutput,
+    list_strings: resultOf(pageOutput),
+    next_address: resultOf(z.string()),
+    prev_address: resultOf(z.string()),
+    procedure_address: resultOf(z.string()),
+    procedure_assembly: resultOf(z.string()),
+    procedure_callees: resultOf(addressList),
+    procedure_callers: resultOf(addressList),
+    procedure_info: procedureInfoOutput,
+    procedure_references: resultOf(z.object({
+        procedure: procedureIdentity,
+        direction: z.enum(["incoming", "outgoing"]),
+        references: bounded(z.object({
+            source_address: z.string(),
+            target_address: z.string(),
+            source_procedure: procedureIdentity.nullable(),
+            target_procedure: procedureIdentity.nullable(),
+            kind: referenceKindSchema,
+        })),
+        instructions_scanned: z.number().int().min(0),
+        instruction_scan_truncated: z.boolean(),
+    })),
+    procedure_pseudo_code: resultOf(nullableText),
+    resolve_containing_procedure: resultOf(containingProcedureResolution),
+    search_procedures: resultOf(searchPageOutput),
+    search_strings: resultOf(searchPageOutput),
+    set_address_name: resultOf(z.boolean()),
+    set_addresses_names: resultOf(z.record(z.string(), z.boolean())),
+    set_bookmark: resultOf(z.boolean()),
+    set_comment: resultOf(z.boolean()),
+    set_current_document: resultOf(z.string()),
+    set_inline_comment: resultOf(z.boolean()),
+    unset_bookmark: resultOf(z.boolean()),
+    xrefs: resultOf(addressList),
+};
+/** Exact structured-content schemas for composed analysis workflows. */
+export const enhancedOutputSchemas = {
+    swift_classes: symbolDiscoveryOutput("classes"),
+    get_objc_classes: symbolDiscoveryOutput("classes"),
+    get_objc_protocols: symbolDiscoveryOutput("protocols"),
+    batch_decompile: resultOf(z.object({
+        items: z.array(z.discriminatedUnion("status", [
+            z.object({
+                address: z.string(),
+                status: z.literal("ok"),
+                pseudocode: z.string().min(1),
+            }),
+            z.object({
+                address: z.string(),
+                status: z.literal("error"),
+                error: analysisErrorProjectionSchema,
+            }),
+        ])),
+        total: z.number().int().min(0),
+        succeeded: z.number().int().min(0),
+        failed: z.number().int().min(0),
+    })),
+    get_call_graph: resultOf(z.record(z.string(), z.array(graphNode))),
+    analyze_swift_types: resultOf(z.object({
+        total: z.number().int().min(0),
+        categories: z.record(z.string(), z.object({
+            count: z.number().int().min(0),
+            items: z.array(addressedEntry),
+        })),
+    })),
+    find_xrefs_to_name: resultOf(z.discriminatedUnion("status", [
+        z.object({
+            status: z.literal("resolved"),
+            name: z.string(),
+            address: z.string(),
+            xrefs: addressList,
+        }),
+        z.object({
+            status: z.literal("unresolved"),
+            name: z.string(),
+            reason: z.literal("name_not_found"),
+        }),
+    ])),
+    binary_overview: resultOf(z.object({
+        document: z.string(),
+        detail: z.enum(["concise", "detailed"]),
+        segments: z.array(z.object({
+            name: z.string(),
+            start: z.string(),
+            end: z.string(),
+            length: z.number().min(0).optional(),
+        })),
+        segment_count: z.number().int().min(0),
+        procedure_count: z.number().int().min(0),
+        string_count: z.number().int().min(0),
+    })),
+    analyze_function: functionDossierOutput,
+    trace_feature: resultOf(z.object({
+        query: z.string(),
+        search_mode: z.literal("literal"),
+        operations_used: z.number().int().min(0),
+        operation_budget: z.number().int().min(1),
+        matches: z.array(z.object({
+            type: z.enum(["string", "procedure"]),
+            address: z.string(),
+            value: z.string(),
+        })),
+        references: z.array(z.object({
+            target_address: z.string(),
+            source_address: z.string(),
+            containing_procedure: containingProcedureResolution,
+        })),
+        truncated: z.boolean(),
+        residual_unknowns: z.array(z.string()),
+    })),
+};
+/** Exact Evidence v2 schemas for provider-neutral native inspection. */
+export const nativeOutputSchemas = {
+    inspect_macho: resultOf(inspectMachoSchema),
+    inspect_signature: resultOf(inspectSignatureSchema),
+    inspect_plist: resultOf(inspectPlistSchema),
+    list_architectures: resultOf(listArchitecturesSchema),
+    demangle_swift: resultOf(demangleSwiftSchema),
+};
+/** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
+export const artifactOutputSchemas = {
+    inventory_artifact: resultOf(artifactInventoryResultSchema),
+    extract_artifact: resultOf(artifactExtractionResultSchema),
+};
+/** Exact Evidence v2 schema for execution-free managed static analysis. */
+export const managedOutputSchemas = {
+    inspect_managed_artifact: resultOf(managedArtifactInspectionSchema),
+    inspect_managed_members: resultOf(managedMemberInspectionSchema),
+    inspect_managed_native_boundaries: resultOf(managedNativeBoundaryInspectionSchema),
+};
+/** Exact Evidence v2 schema for provider-neutral managed workflows. */
+export const managedWorkflowOutputSchemas = {
+    compare_managed_members: resultOf(managedMemberComparisonResultSchema),
+    verify_managed_native_boundaries: resultOf(managedNativeVerificationResultSchema),
+    import_managed_reconstruction: resultOf(managedReconstructionImportResultSchema),
+    plan_managed_runtime_correlation: resultOf(managedRuntimeCorrelationResultSchema),
+    project_managed_application_graph: resultOf(managedApplicationGraphResultSchema),
+};
+/** Exact structured-content schemas for target lifecycle operations. */
+export const sessionOutputSchemas = {
+    open_binary: lifecycleResultOf(z.object({
+        path: z.string(),
+        format: targetFormatSchema,
+        kind: targetKindSchema,
+        loaderArgs: z.array(z.string()),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+    })),
+    close_binary: lifecycleResultOf(z.union([
+        z.null(),
+        z.object({
+            path: z.string(),
+            bytes: z.number().int().min(0),
+            entries: z.number().int().min(0),
+        }),
+    ])),
+    binary_session: lifecycleResultOf(z.union([
+        sessionProvider.extend({ open: z.literal(false) }),
+        sessionProvider.extend({
+            open: z.literal(true),
+            path: z.string(),
+            format: targetFormatSchema,
+            kind: targetKindSchema,
+            sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+            architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+        }),
+    ])),
+    export_evidence_bundle: lifecycleResultOf(z.union([
+        evidenceBundleSchema,
+        z.object({
+            path: z.string(),
+            bytes: z.number().int().min(0),
+            records: z.number().int().min(0),
+        }),
+    ])),
+    import_evidence_bundle: lifecycleResultOf(z.object({
+        imported: z.number().int().min(0),
+        total: z.number().int().min(0),
+    })),
+    capture_process_scenario: resultOf(processCaptureSchema),
+    compare_process_captures: resultOf(processCaptureComparisonSchema),
+    compare_artifacts: resultOf(artifactComparisonResultSchema),
+    compare_functions: resultOf(functionComparisonResultSchema),
+    compare_bundles: resultOf(bundleComparisonResultSchema),
+    find_changed_behavior: resultOf(changedBehaviorResultSchema),
+    build_call_path: resultOf(callPathResultSchema),
+    correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
+    verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
+    list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
+    record_unknown: lifecycleResultOf(residualUnknownSchema),
+    update_unknown: lifecycleResultOf(residualUnknownSchema),
+    verify_unknown_resolution: lifecycleResultOf(z.object({
+        valid: z.boolean(),
+        truthVerified: z.boolean(),
+        unknown: residualUnknownSchema,
+    })),
+};