rea-agents 1.3.0 → 1.4.0

package/dist/contracts/errorSchemas.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+const categorySchema = z.enum([
+    "invalid_input",
+    "permission_required",
+    "unsupported_provider",
+    "integrity_mismatch",
+    "truncated",
+    "cancelled",
+    "timeout",
+    "unavailable",
+    "execution_failure",
+]);
+const remediationSchema = z
+    .object({
+    action: z.string().min(1),
+    restart_required: z.boolean(),
+    elicitation_supported: z.boolean().optional(),
+})
+    .strict();
+const common = {
+    category: categorySchema,
+    message: z.string().min(1),
+    retryable: z.boolean(),
+    remediation: remediationSchema,
+};
+const genericDetails = z.record(z.string(), z.json()).optional();
+const generic = (code) => z
+    .object({ code: z.literal(code), ...common, details: genericDetails })
+    .strict();
+const scopeSchema = z
+    .object({
+    capability: z.string(),
+    roots: z.array(z.string()),
+    executables: z.array(z.string()),
+    environment_names: z.array(z.string()),
+    network: z.enum(["none", "loopback", "external"]),
+    mount: z.boolean(),
+})
+    .strict();
+const missingScopeSchema = z
+    .object({
+    roots: z.array(z.string()).optional(),
+    executables: z.array(z.string()).optional(),
+    environment_names: z.array(z.string()).optional(),
+    network: z.enum(["none", "loopback", "external"]).optional(),
+    mount: z.literal(true).optional(),
+})
+    .strict();
+/** Stable discriminated schema shared by every CLI and MCP error surface. */
+export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
+    generic("invalid_request"),
+    generic("unreadable_output"),
+    generic("capability_unavailable"),
+    generic("provider_unavailable"),
+    generic("provider_timeout"),
+    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"),
+    z
+        .object({
+        code: z.literal("permission_required"),
+        ...common,
+        details: z
+            .object({
+            capability: z.string(),
+            requested: scopeSchema,
+            missing: missingScopeSchema,
+            ceiling: scopeSchema.nullable(),
+        })
+            .strict()
+            .optional(),
+    })
+        .strict(),
+    generic("process_capture_failed"),
+    generic("cleanup_incomplete"),
+    generic("revision_conflict"),
+    generic("outside_approved_root"),
+    generic("configuration_invalid"),
+    generic("target_unavailable"),
+    generic("execution_failure"),
+]);
+/** JSON Schema document used by generated API documentation and clients. */
+export const analysisErrorJsonSchema = z.toJSONSchema(analysisErrorProjectionSchema);

package/dist/contracts/toolContracts.js

@@ -158,11 +158,20 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, pseudocode, optional assembly, comments, calls, incoming references, and blocks; unsupported outgoing references and CFG edges carry explicit unavailable metadata.", enhancedInputSchemas.analyze_function),
     enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),
 ];
+/** Caller observations used to compare a live server with expected identity. */
+export const binarySessionInputSchema = z.object({
+    expected_package_version: z.string().min(1).optional(),
+    expected_catalog_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    expected_server_path: z.string().min(1).optional(),
+});
 /** Target lifecycle tools available only on the long-lived MCP adapter. */
 export const SESSION_TOOL_CONTRACTS = [
     session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or Hopper database after validation. An optional provider-neutral snapshot is imported atomically and must match the binary digest, format, and architecture exactly; provider resources may still start before an MCP cache replay.", openBinaryInputSchema),
     session("close_binary", "Optionally write a provider-neutral analysis snapshot atomically, then close the active target and every provider resource started for it. Snapshot files require an operator-approved root and explicit overwrite; a failed save leaves the session open so cached analysis is not lost.", closeBinaryInputSchema),
-    session("binary_session", "Report provider identity, deterministic capability descriptors, and whether a target is open; open targets include canonical path, format, and kind. Use availability, effects, limits, and limitations before selecting analysis operations.", z.object({})),
+    session("binary_session", "Report provider identity, deterministic capability descriptors, and whether a target is open; open targets include canonical path, format, and kind. Use availability, effects, limits, and limitations before selecting analysis operations.", binarySessionInputSchema),
     session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", z.object({
         path: z.string().min(1).optional(),
         overwrite: z.boolean().default(false),

package/dist/contracts/toolOutputSchemas.js

@@ -13,6 +13,7 @@ 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";
 const resultOf = (schema) => evidenceSchema
     .omit({ normalized_result: true })
     .extend({ normalized_result: schema });
@@ -78,6 +79,67 @@ const sessionProvider = z.object({
     provider: providerIdentity,
     providers: z.array(providerIdentity),
     capabilities: z.array(providerCapability),
+    tool_availability: z.array(z.object({
+        name: z.string(),
+        surface: z.string(),
+        available: z.boolean(),
+        reason: z.enum([
+            "available",
+            "target_required",
+            "provider_missing",
+            "provider_unavailable",
+            "target_unsupported",
+            "unsupported_host",
+            "policy_disabled",
+        ]),
+        remediation: z.string().nullable(),
+        annotations: z.object({
+            read_only: z.boolean(),
+            destructive: z.boolean(),
+            idempotent: z.boolean(),
+            open_world: z.boolean(),
+        }),
+    })),
+    client_features: z.object({
+        elicitation_form: z.boolean(),
+        elicitation_url: z.boolean(),
+        roots: z.boolean(),
+        sampling: z.boolean(),
+    }),
+    server_identity: z.object({
+        package: z.object({
+            name: z.string(),
+            version: z.string(),
+            root_path: z.string(),
+            build_commit: z.string().nullable(),
+        }),
+        server: z.object({
+            name: z.string(),
+            version: z.string(),
+            started_at: z.string(),
+            command_path: z.string(),
+        }),
+        sdk: z.object({
+            server: z.string(),
+            client_test: z.string(),
+            core: z.string(),
+        }),
+        negotiated_protocol_version: z.string().nullable(),
+        client: z.object({ name: z.string(), version: z.string() }).nullable(),
+        skill: z.object({ name: z.string(), expected_version: z.string() }),
+        catalog: z.record(z.string(), z.json()),
+        protocol_features: z.object({
+            progress: z.boolean(),
+            cancellation: z.boolean(),
+            evidence_resources: z.boolean(),
+            elicitation: z.boolean(),
+        }),
+        alignment: z.object({
+            state: z.enum(["aligned", "mcp_server_restart_required", "unknown"]),
+            reasons: z.array(z.string()),
+            remediation: z.string().nullable(),
+        }),
+    }),
 });
 const nullableText = z.string().nullable();
 const addressList = z.array(z.string());
@@ -149,36 +211,6 @@ const symbolDiscoveryOutput = (property) => resultOf(z.object({
     count: z.number().int().min(0),
     [property]: z.array(addressedEntry),
 }));
-const analysisErrorProjectionSchema = z
-    .object({
-    category: z.enum([
-        "invalid_input",
-        "permission_required",
-        "unsupported_provider",
-        "integrity_mismatch",
-        "truncated",
-        "cancelled",
-        "timeout",
-        "unavailable",
-        "execution_failure",
-    ]),
-    message: z.string(),
-    code: z
-        .enum([
-        "private_display_unavailable",
-        "x11_authorization_failed",
-        "unsupported_hopper_build",
-        "invalid_launch_command",
-        "process_ownership_mismatch",
-        "hopper_exited_during_startup",
-        "unsupported_demo_dialog",
-        "unexpected_display_geometry",
-        "x11_input_failed",
-        "runtime_dependency_unavailable",
-    ])
-        .optional(),
-})
-    .strict();
 const graphNode = z.discriminatedUnion("status", [
     z.object({
         address: z.string(),

package/dist/domain/artifactComparison.js

@@ -11,8 +11,15 @@ const comparisonStatusSchema = z.enum([
     "changed",
     "truncated",
     "unknown",
+    "contradiction",
+]);
+const changeKindSchema = z.enum([
+    "added",
+    "removed",
+    "changed",
+    "unknown",
+    "contradiction",
 ]);
-const changeKindSchema = z.enum(["added", "removed", "changed", "unknown"]);
 const comparisonDimensionSchema = z.enum([
     "content",
     "kind",
@@ -22,6 +29,7 @@ const comparisonDimensionSchema = z.enum([
     "relations",
     "metadata",
     "availability",
+    "integrity",
 ]);
 /** Strict Evidence-backed input for deterministic artifact comparison. */
 export const artifactComparisonInputSchema = z.object({
@@ -68,6 +76,7 @@ export const artifactComparisonResultSchema = z.object({
         removed: z.number().int().min(0),
         changed: z.number().int().min(0),
         unknown: z.number().int().min(0),
+        contradiction: z.number().int().min(0).default(0),
     }),
     changes: z.object({
         items: z.array(artifactChangeSchema).max(500),
@@ -84,8 +93,8 @@ export const compareArtifacts = (leftEvidence, rightEvidence, offset, limit) =>
     const right = parseArtifactInventoryEvidence(rightEvidence);
     const leftComplete = left.inventory.complete;
     const rightComplete = right.inventory.complete;
-    const leftCovered = leftComplete && left.inventory.limitations.length === 0;
-    const rightCovered = rightComplete && right.inventory.limitations.length === 0;
+    const leftCovered = leftComplete && !hasCoverageLimitation(left.inventory.limitations);
+    const rightCovered = rightComplete && !hasCoverageLimitation(right.inventory.limitations);
     const limitations = [
         ...left.inventory.limitations.map((item) => `Left: ${item}`),
         ...right.inventory.limitations.map((item) => `Right: ${item}`),
@@ -101,13 +110,15 @@ export const compareArtifacts = (leftEvidence, rightEvidence, offset, limit) =>
     return artifactComparisonResultSchema.parse({
         status: !leftComplete || !rightComplete
             ? "truncated"
-            : !leftCovered || !rightCovered
-                ? "unknown"
-                : changes.some(({ classification }) => classification === "unknown")
+            : changes.some(({ classification }) => classification === "contradiction")
+                ? "contradiction"
+                : !leftCovered || !rightCovered
                     ? "unknown"
-                    : changes.length === 0
-                        ? "unchanged"
-                        : "changed",
+                    : changes.some(({ classification }) => classification === "unknown")
+                        ? "unknown"
+                        : changes.length === 0
+                            ? "unchanged"
+                            : "changed",
         left_manifest_id: left.inventory.manifest.manifest_id,
         right_manifest_id: right.inventory.manifest.manifest_id,
         summary,
@@ -172,6 +183,13 @@ const classifyPath = (input) => {
             classification: input.complete ? "removed" : "unknown",
             dimensions: [input.complete ? "content" : "availability"],
         };
+    if (input.leftOccurrence.hash_status === "mismatched" ||
+        input.rightOccurrence.hash_status === "mismatched")
+        return {
+            ...base,
+            classification: "contradiction",
+            dimensions: ["integrity"],
+        };
     if (input.leftOccurrence.hash_status !== "verified" ||
         input.rightOccurrence.hash_status !== "verified" ||
         input.leftNode === undefined ||
@@ -253,13 +271,20 @@ const relationsByPath = (inventory) => {
     return output;
 };
 const summarize = (left, right, changes, covered) => {
-    const counts = { added: 0, removed: 0, changed: 0, unknown: 0 };
+    const counts = {
+        added: 0,
+        removed: 0,
+        changed: 0,
+        unknown: 0,
+        contradiction: 0,
+    };
     for (const change of changes)
         counts[change.classification] += 1;
     return {
         unchanged: covered
             ? Math.max(0, Math.min(left.occurrences.length, right.occurrences.length) -
                 counts.changed -
+                counts.contradiction -
                 counts.unknown)
             : 0,
         ...counts,
@@ -268,6 +293,8 @@ const summarize = (left, right, changes, covered) => {
             : Math.max(counts.unknown, Math.max(left.manifest.occurrence_count, right.manifest.occurrence_count) -
                 counts.added -
                 counts.removed -
-                counts.changed),
+                counts.changed -
+                counts.contradiction),
     };
 };
+const hasCoverageLimitation = (limitations) => limitations.some((limitation) => !/integrity contradiction\(s\) were recorded/u.test(limitation));

package/dist/domain/artifactGraph.js

@@ -5,6 +5,7 @@ const occurrenceIdSchema = z.string().regex(/^occ_[a-f0-9]{64}$/u);
 const edgeIdSchema = z.string().regex(/^edge_[a-f0-9]{64}$/u);
 const manifestIdSchema = z.string().regex(/^agm_[a-f0-9]{64}$/u);
 const extractionIdSchema = z.string().regex(/^aex_[a-f0-9]{64}$/u);
+const contradictionIdSchema = z.string().regex(/^ic_[a-f0-9]{64}$/u);
 const boundedRelativePathSchema = z
     .string()
     .min(1)
@@ -106,10 +107,29 @@ const artifactOccurrenceSchema = z.object({
         .nullable(),
     executable: z.boolean(),
     encrypted: z.boolean(),
-    hash_status: z.enum(["verified", "not-hashed-limit", "unavailable"]),
+    hash_status: z.enum([
+        "verified",
+        "mismatched",
+        "not-hashed-limit",
+        "unavailable",
+    ]),
     source_location: artifactByteRangeSchema.nullable(),
     limitations: z.array(z.string()),
 });
+/** Observed bytes that contradict a container's declared integrity identity. */
+const integrityContradictionSchema = z.object({
+    contradiction_id: contradictionIdSchema,
+    occurrence_id: occurrenceIdSchema,
+    parent_artifact_id: artifactIdSchema,
+    logical_path: boundedRelativePathSchema,
+    declared_sha256: sha256Schema,
+    observed_sha256: sha256Schema,
+    entry_kind: z.enum(["file", "slice"]),
+    unpacked: z.boolean(),
+    trust: z.literal("observed-untrusted"),
+    provenance: z.literal("container-integrity-metadata-versus-observed-bytes"),
+    limitations: z.array(z.string()).min(1),
+});
 /** Parent-child derivation relation between two content-addressed artifacts. */
 const artifactEdgeSchema = z.object({
     edge_id: edgeIdSchema,
@@ -157,6 +177,10 @@ export const artifactInventoryResultSchema = z.object({
     edges: artifactPageSchema(artifactEdgeSchema),
     limits: artifactTraversalLimitsSchema,
     provenance: z.array(artifactCommandSchema).max(256),
+    integrity_contradictions: z
+        .array(integrityContradictionSchema)
+        .max(100)
+        .default([]),
     limitations: z.array(z.string()),
 });
 /** One safely materialized artifact beneath caller-approved output root. */

package/dist/domain/artifactInventoryEvidence.js

@@ -39,6 +39,9 @@ const assembleInventorySet = (pages) => {
     for (const page of pages) {
         if (canonicalJson(page.inventory.manifest) !== manifestJson)
             throw new TypeError("Artifact inventory pages do not share one manifest");
+        if (canonicalJson(page.inventory.integrity_contradictions) !==
+            canonicalJson(first.inventory.integrity_contradictions))
+            throw new TypeError("Artifact inventory pages do not share integrity contradictions");
         for (const node of page.inventory.nodes.items)
             mergeExact(nodes, node.artifact_id, node, "node");
         for (const occurrence of page.inventory.occurrences.items) {
@@ -66,6 +69,7 @@ const orderedInventory = (first, pages, values) => {
         nodes,
         occurrences,
         edges,
+        integrityContradictions: first.integrity_contradictions,
         limitations: [
             ...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
         ].sort((left, right) => left.localeCompare(right)),
@@ -84,10 +88,24 @@ const validateCompleteInventory = (inventory) => {
         validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
     for (const edge of inventory.edges)
         validateEdge(edge, nodeIds, occurrenceIds);
+    for (const contradiction of inventory.integrityContradictions) {
+        if (!nodeIds.has(contradiction.parent_artifact_id) ||
+            !occurrenceIds.has(contradiction.occurrence_id))
+            throw new TypeError("Integrity contradiction references a missing graph member");
+        const expectedId = `ic_${digestCanonical({
+            root_artifact_id: inventory.manifest.root_artifact_id,
+            logical_path: contradiction.logical_path,
+            declared_sha256: contradiction.declared_sha256,
+            observed_sha256: contradiction.observed_sha256,
+        })}`;
+        if (contradiction.contradiction_id !== expectedId)
+            throw new TypeError("Integrity contradiction ID does not match its identity");
+    }
     const graphSha256 = digestCanonical({
         nodes: inventory.nodes,
         occurrences: inventory.occurrences,
         edges: inventory.edges,
+        integrity_contradictions: inventory.integrityContradictions,
     });
     if (graphSha256 !== inventory.manifest.graph_sha256)
         throw new TypeError("Artifact graph commitment does not match its members");

package/dist/domain/changedBehavior.js

@@ -247,9 +247,11 @@ const artifactFindings = (evidence) => {
         dimension: `artifact:${change.logical_path}`,
         scope: "static_candidate",
         status: change.classification,
-        classification: change.classification === "unknown"
-            ? "unresolved_branch"
-            : "derived_relationship",
+        classification: change.classification === "contradiction"
+            ? "contradiction"
+            : change.classification === "unknown"
+                ? "unresolved_branch"
+                : "derived_relationship",
         limitations: result.limitations,
         links: change.evidence_links,
     }));