rea-agents 2.5.0 → 3.1.0

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -42,11 +42,8 @@ export const targetKindSchema = z.enum([
     "archive",
     "artifact",
 ]);
-const providerCapability = z.object({
+const providerCapabilityFacts = {
     operation: z.string(),
-    available: z.boolean(),
-    reason: z.string().nullable(),
-    availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),
     input_contract_version: z.number().int().min(1),
     output_contract_version: z.number().int().min(1),
     pagination: z.enum(["none", "offset", "cursor"]),
@@ -66,7 +63,21 @@ const providerCapability = z.object({
         timeout_ms: z.number().int().min(0).nullable(),
     }),
     limitations: z.array(z.string()),
-});
+};
+export const providerCapability = z.discriminatedUnion("available", [
+    z.object({
+        ...providerCapabilityFacts,
+        available: z.literal(true),
+        reason: z.null(),
+        availability_code: z.null(),
+    }),
+    z.object({
+        ...providerCapabilityFacts,
+        available: z.literal(false),
+        reason: z.string().nullable(),
+        availability_code: z.enum(PROVIDER_REJECTION_CODES).nullable(),
+    }),
+]);
 export const providerIdentity = z.object({
     id: z.string(),
     name: z.string(),
@@ -182,21 +193,25 @@ export const clientFeatureAvailabilitySchema = z.object({
     roots: z.boolean(),
     sampling: z.boolean(),
 });
-export const toolAvailability = z.object({
+const toolAvailabilityMode = z.discriminatedUnion("available", [
+    z.object({
+        name: z.string(),
+        available: z.literal(true),
+        missing_operations: z.array(z.string()).max(0),
+        remediation: z.null(),
+    }),
+    z.object({
+        name: z.string(),
+        available: z.literal(false),
+        missing_operations: z.array(z.string()).min(1),
+        remediation: z.string().nullable(),
+    }),
+]);
+const toolAvailabilityFacts = {
     name: z.string(),
     surface: z.string(),
-    available: z.boolean(),
-    reason: z.enum([
-        "available",
-        "client_capability_missing",
-        "target_required",
-        "provider_missing",
-        "provider_unavailable",
-        "target_unsupported",
-        "unsupported_host",
-        "policy_disabled",
-    ]),
-    remediation: z.string().nullable(),
+    default_mode_available: z.boolean().optional(),
+    modes: z.array(toolAvailabilityMode).optional(),
     client_requirements: z.object({
         required: z.array(clientFeatureNameSchema),
         optional: z.array(clientFeatureNameSchema),
@@ -219,7 +234,30 @@ export const toolAvailability = z.object({
         idempotent: z.boolean(),
         open_world: z.boolean(),
     }),
-});
+};
+export const toolUnavailabilityReason = z.enum([
+    "client_capability_missing",
+    "target_required",
+    "provider_missing",
+    "provider_unavailable",
+    "target_unsupported",
+    "unsupported_host",
+    "policy_disabled",
+]);
+export const toolAvailability = z.discriminatedUnion("available", [
+    z.object({
+        ...toolAvailabilityFacts,
+        available: z.literal(true),
+        reason: z.literal("available"),
+        remediation: z.null(),
+    }),
+    z.object({
+        ...toolAvailabilityFacts,
+        available: z.literal(false),
+        reason: toolUnavailabilityReason,
+        remediation: z.string().nullable(),
+    }),
+]);
 export const sessionProvider = z.object({
     provider: providerIdentity,
     providers: z.array(providerIdentity),
@@ -315,13 +353,25 @@ const availableMemoryPermissions = z.object({
     available: z.literal(true),
     source: z.literal("ghidra-memory-block"),
 });
-export const bounded = (item) => z.object({
-    items: z.array(item),
-    total: z.number().int().min(0).nullable(),
-    returned: z.number().int().min(0),
-    truncated: z.boolean(),
-    next_offset: z.number().int().min(0).nullable(),
-});
+export const bounded = (item) => {
+    const facts = {
+        items: z.array(item),
+        total: z.number().int().min(0).nullable(),
+        returned: z.number().int().min(0),
+    };
+    return z.discriminatedUnion("truncated", [
+        z.object({
+            ...facts,
+            truncated: z.literal(false),
+            next_offset: z.null(),
+        }),
+        z.object({
+            ...facts,
+            truncated: z.literal(true),
+            next_offset: z.number().int().min(0).nullable(),
+        }),
+    ]);
+};
 const addressedValue = z.object({
     address: z.string(),
     value: z.string(),

package/dist/contracts/toolSchemaMetadata.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+const PROPERTY_DESCRIPTIONS = {
+    addresses: "Ordered provider-normalized procedure addresses to analyze.",
+    approved: "Explicit operator approval to perform this operation.",
+    after: "The later or right-hand observation to compare.",
+    before: "The earlier or left-hand observation to compare.",
+    boundary_id: "Exact reconstruction boundary identifier to evaluate.",
+    case_sensitive: "Whether text matching distinguishes uppercase and lowercase.",
+    cdp_endpoint: "Approved literal loopback Chrome DevTools Protocol endpoint.",
+    comment: "Exact analyst comment text to write.",
+    comparisons: "Validated comparison Evidence records to aggregate.",
+    coverage: "Exact reconstruction-coverage commitment to verify.",
+    detail: "Requested response detail level.",
+    direction: "Direction in which to traverse or compare relationships.",
+    document: "Exact provider document or program identity.",
+    error: "Structured, caller-actionable error when the operation fails.",
+    evidence: "Evidence v2 record produced by this operation.",
+    evidence_id: "Stable identifier of the recorded Evidence v2 observation.",
+    evidence_uri: "Session resource URI for the recorded Evidence v2 observation.",
+    executable: "Approved absolute path of the executable to run.",
+    format: "Declared input artifact format.",
+    name: "Exact name used by this operation.",
+    pattern: "Text or bounded pattern used to filter matching results.",
+    phase: "Current plan or execution phase of the operation.",
+    plan: "Content-bound execution plan and its approval commitment.",
+    query: "Non-empty feature or text query to investigate.",
+    question: "Concrete unresolved question to retain for later investigation.",
+    result: "Primary structured result returned by this operation.",
+    left: "Left-hand input used for comparison or differential execution.",
+    limit: "Maximum number of results to return in this page.",
+    limits: "Bounded resource-consumption and result-size limits for this operation.",
+    mode: "Operation mode that selects the requested behavior.",
+    offset: "Zero-based index of the first result to return.",
+    overwrite: "Whether an existing destination may be replaced.",
+    path: "Local filesystem path used by this operation.",
+    provider_id: "Exact deep-analysis provider ID, or automatic selection when omitted.",
+    right: "Right-hand input used for comparison or differential execution.",
+    schema_version: "Version of this structured result schema.",
+    source_evidence: "Evidence records supporting the prepared source transformation.",
+    status: "Current lifecycle or verification status.",
+    summary: "Concise evidence-backed summary of the result.",
+    symbols: "Ordered bounded Swift symbols to demangle.",
+    target_id: "Exact authorized CDP target identifier.",
+    unknown_id: "Exact residual-unknown identifier.",
+    unknown_registry_approved: "Explicit approval to record bounded residual uncertainty in the session registry.",
+    workspace_path: "Approved local path of the persistent investigation workspace.",
+};
+/** Attach caller guidance to a canonical schema for the SDK wire projection. */
+export const toolInputSchemaWithMetadata = (contract) => {
+    const schema = contract.inputSchema.meta(z.globalRegistry.get(contract.inputSchema) ?? {});
+    const standard = schema["~standard"];
+    const inputJsonSchema = standard.jsonSchema?.input;
+    if (inputJsonSchema === undefined)
+        throw new TypeError("Tool input schema does not expose Standard JSON Schema");
+    // Zod's input projection drops root metadata when a descendant transforms.
+    // Preserve the parser and let the SDK own conversion of everything else.
+    Object.defineProperty(schema, "~standard", {
+        value: {
+            ...standard,
+            jsonSchema: {
+                ...standard.jsonSchema,
+                input: (options) => ({
+                    ...describeProperties(inputJsonSchema(options)),
+                    examples: contract.examples.map(({ input }) => input),
+                }),
+            },
+        },
+    });
+    return schema;
+};
+const describeProperties = (value) => Object.fromEntries(Object.entries(value).map(([key, child]) => {
+    if (key !== "properties" || !isObject(child))
+        return [key, describeValue(child)];
+    return [
+        key,
+        Object.fromEntries(Object.entries(child).map(([property, propertySchema]) => [
+            property,
+            isObject(propertySchema) &&
+                typeof propertySchema.description !== "string"
+                ? {
+                    ...describeProperties(propertySchema),
+                    description: fallbackPropertyDescription(property),
+                }
+                : describeValue(propertySchema),
+        ])),
+    ];
+}));
+const describeValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(describeValue);
+    return isObject(value) ? describeProperties(value) : value;
+};
+const fallbackPropertyDescription = (property) => {
+    const explicit = PROPERTY_DESCRIPTIONS[property];
+    if (explicit !== undefined)
+        return explicit;
+    const words = property.replaceAll("_", " ");
+    if (property.endsWith("_approved"))
+        return `Explicit operator approval for ${words.slice(0, -9)}.`;
+    if (property.endsWith("_offset"))
+        return `Zero-based index of the first ${words.slice(0, -7)} to return.`;
+    if (property.endsWith("_limit"))
+        return `Maximum number of ${words.slice(0, -6)} entries to return.`;
+    if (property.startsWith("max_"))
+        return `Maximum permitted ${words.slice(4)} for this operation.`;
+    if (property.startsWith("include_"))
+        return `Whether to include ${words.slice(8)} in the result.`;
+    if (property.startsWith("expected_"))
+        return `Expected ${words.slice(9)} used to reject stale or mismatched input.`;
+    if (property.endsWith("_sha256"))
+        return `Exact SHA-256 digest of ${words.slice(0, -7)}.`;
+    if (property.endsWith("_evidence_id"))
+        return `Exact Evidence v2 identifier for the ${words.slice(0, -12)} observation.`;
+    if (property.endsWith("_evidence_ids"))
+        return `Ordered Evidence v2 identifiers for the ${words.slice(0, -13)} observations.`;
+    if (property.endsWith("_path"))
+        return `Local filesystem path for ${words.slice(0, -5)}.`;
+    if (property.endsWith("_uri"))
+        return `Canonical URI for ${words.slice(0, -4)}.`;
+    if (property.endsWith("_bytes"))
+        return `Bounded byte count for ${words.slice(0, -6)}.`;
+    if (property.endsWith("_root") || property.endsWith("_roots"))
+        return `Approved canonical filesystem ${words}.`;
+    if (property.startsWith("is_") || property.startsWith("has_"))
+        return `Whether ${words}.`;
+    return `Value for ${words}.`;
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/doctorRuntime.js

@@ -58,7 +58,7 @@ const inspectJavaScriptReplay = async () => {
             detail: config.error.message,
             remediation: "Fix the reported REA_JAVASCRIPT_REPLAY_* configuration.",
         };
-    if (!config.value.javascriptReplayPolicy.enabled)
+    if (config.value.javascriptReplayPolicy.status === "disabled")
         return {
             name: "javascript-replay",
             ok: true,

package/dist/domain/analysisErrorPresentation.js

@@ -2,6 +2,8 @@ import { AnalysisInputError, ArtifactOperationError, BinaryTargetError, BrowserO
 export const analysisErrorRemediationAction = (error) => {
     if (error instanceof AnalysisInputError)
         return "Correct the listed arguments and retry.";
+    if (error instanceof UnknownRegistryError && error.reason === "not-found")
+        return "Check that the unknown_id belongs to this session, then retry.";
     if (error instanceof ReplayPlanStaleError)
         return "Review the rebuilt replay plan and explicitly approve its new digest.";
     if (error instanceof PermissionRequiredError)
@@ -64,7 +66,7 @@ const artifactErrorCategory = (reason) => {
         return "truncated";
     if (reason === "cancelled")
         return "cancelled";
-    if (reason === "unavailable")
+    if (reason === "policy" || reason === "unavailable")
         return "unavailable";
     return "execution_failure";
 };
@@ -103,6 +105,8 @@ export const analysisErrorUserMessage = (error) => {
         return evidenceFileMessage(error.reason);
     if (error instanceof InvestigationWorkspaceError)
         return investigationWorkspaceMessage(error.reason);
+    if (error instanceof UnknownRegistryError && error.reason === "not-found")
+        return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
     if (error instanceof UnknownRegistryError)
         return "Evidence state changed before the update completed. Refresh the current state and try again.";
     if (error instanceof ConfigurationError)
@@ -163,8 +167,10 @@ const artifactMessage = (reason) => {
         return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
     if (reason === "path")
         return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
+    if (reason === "policy")
+        return "Artifact integrity continuation is disabled by policy. Configure REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED=true and retry only if continuing after mismatches is approved.";
     if (reason === "unavailable")
-        return "Artifact format is not available on this system. Choose another artifact or supported environment.";
+        return "Artifact processing is unavailable for the current target or policy. Check artifact support and required approvals.";
     if (reason === "format" || reason === "integrity")
         return "Artifact is invalid or has changed. Get a fresh copy and try again.";
     return "Artifact could not be read or written. Check file access and try again.";

package/dist/domain/analysisErrorProjection.js

@@ -152,6 +152,7 @@ const requestErrorDetails = (error) => {
             issues: error.issues.map((issue) => ({
                 path: [...issue.path],
                 reason: issue.reason,
+                ...(issue.message === undefined ? {} : { message: issue.message }),
                 ...(issue.expected === undefined ? {} : { expected: issue.expected }),
                 ...(issue.minimum === undefined ? {} : { minimum: issue.minimum }),
                 ...(issue.maximum === undefined ? {} : { maximum: issue.maximum }),

package/dist/domain/androidApplication.js

@@ -146,6 +146,8 @@ const classify = (all) => ({
 });
 const retain = (groups, maximum) => {
     let remaining = maximum;
+    // SAFETY: the projection preserves every key from Groups and replaces only
+    // each readonly Component array with a bounded mutable Component array.
     return Object.fromEntries(Object.entries(groups).map(([key, values]) => {
         const selected = [...values]
             .sort((left, right) => compare(left.path, right.path))

package/dist/domain/appleApplication.js

@@ -140,6 +140,8 @@ const classifyComponents = (all, roots) => {
 };
 const retainComponents = (groups, maximum) => {
     let remaining = maximum;
+    // SAFETY: the projection preserves every key from Groups and replaces only
+    // each readonly Component array with a bounded mutable Component array.
     return Object.fromEntries(Object.entries(groups).map(([key, values]) => {
         const retained = [...values]
             .sort((left, right) => compare(left.path, right.path))

package/dist/domain/binaryTarget.js

@@ -36,14 +36,16 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
                     format: "analysis-database",
                 });
             const artifactFormat = await detectArtifactFormat(path, handle);
-            if (artifactFormat !== undefined)
-                return ok({
+            if (artifactFormat !== undefined) {
+                const identity = {
                     path,
                     sourcePath: canonical,
                     sha256: await sha256Handle(handle),
-                    kind: isArchiveFormat(artifactFormat) ? "archive" : "artifact",
-                    format: artifactFormat,
-                });
+                };
+                return isArchiveFormat(artifactFormat)
+                    ? ok({ ...identity, kind: "archive", format: artifactFormat })
+                    : ok({ ...identity, kind: "artifact", format: artifactFormat });
+            }
             const detected = await readExecutableMetadata(handle, hostArchitecture);
             if (!detected.ok)
                 return err(new BinaryTargetError(path, detected.error));

package/dist/domain/binaryTargetTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/browserCaptureComparison.js

@@ -1,75 +1,27 @@
 import { z } from "zod";
 import { browserScenarioDiffSchema, compareBrowserScenarios, compareBrowserScenariosInputSchema, } from "./browserScenarioDiff.js";
 import { compareWebCaptures, captureSnapshotSchema, webCaptureDiffSchema, } from "./webCaptureDiff.js";
-/** Top-level MCP shape for legacy page or step-indexed scenario comparison. */
-export const browserCaptureComparisonWireSchema = z
-    .strictObject({
-    before: captureSnapshotSchema
-        .optional()
-        .describe("Earlier passive web-page capture; pair with after."),
-    after: captureSnapshotSchema
-        .optional()
-        .describe("Later passive web-page capture; pair with before."),
-    before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario
-        .optional()
-        .describe("Earlier browser scenario capture; pair with after_scenario."),
-    after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario
-        .optional()
-        .describe("Later browser scenario capture; pair with before_scenario."),
-    normalization: compareBrowserScenariosInputSchema.shape.normalization.describe("Scenario-only exact-literal normalization policy."),
-    max_changes: z
-        .number()
-        .int()
-        .min(1)
-        .max(20_000)
-        .default(2_000)
-        .describe("Maximum normalized change records to retain."),
-})
-    .superRefine((input, context) => {
-    const hasPassive = input.before !== undefined || input.after !== undefined;
-    const hasScenario = input.before_scenario !== undefined || input.after_scenario !== undefined;
-    if (hasPassive === hasScenario)
-        context.addIssue({
-            code: "custom",
-            message: "Provide exactly one complete pair: before/after or before_scenario/after_scenario",
-        });
-    if (hasPassive && (input.before === undefined || input.after === undefined))
-        context.addIssue({
-            code: "custom",
-            message: "Passive comparison requires both before and after",
-        });
-    if (hasScenario &&
-        (input.before_scenario === undefined ||
-            input.after_scenario === undefined))
-        context.addIssue({
-            code: "custom",
-            message: "Browser scenario comparison requires both before_scenario and after_scenario",
-        });
-    if (hasPassive && input.normalization.rules.length > 0)
-        context.addIssue({
-            code: "custom",
-            path: ["normalization"],
-            message: "Literal normalization rules apply only to browser scenario captures",
-        });
-});
-/** Parsed legacy page snapshots or step-indexed browser scenarios. */
-export const browserCaptureComparisonInputSchema = browserCaptureComparisonWireSchema.transform((input) => {
-    if (input.before_scenario !== undefined &&
-        input.after_scenario !== undefined)
-        return {
-            before_scenario: input.before_scenario,
-            after_scenario: input.after_scenario,
-            normalization: input.normalization,
-            max_changes: input.max_changes,
-        };
-    if (input.before !== undefined && input.after !== undefined)
-        return {
-            before: input.before,
-            after: input.after,
-            max_changes: input.max_changes,
-        };
-    throw new TypeError("Capture comparison pair refinement failed");
-});
+const maxChangesSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(20_000)
+    .default(2_000)
+    .describe("Maximum normalized change records to retain.");
+/** Top-level MCP shape for exactly one complete passive or scenario pair. */
+export const browserCaptureComparisonInputSchema = z.union([
+    z.strictObject({
+        before: captureSnapshotSchema.describe("Earlier passive web-page capture."),
+        after: captureSnapshotSchema.describe("Later passive web-page capture."),
+        max_changes: maxChangesSchema,
+    }),
+    z.strictObject({
+        before_scenario: compareBrowserScenariosInputSchema.shape.before_scenario.describe("Earlier browser scenario capture."),
+        after_scenario: compareBrowserScenariosInputSchema.shape.after_scenario.describe("Later browser scenario capture."),
+        normalization: compareBrowserScenariosInputSchema.shape.normalization.describe("Exact-literal normalization policy."),
+        max_changes: maxChangesSchema,
+    }),
+]);
 /** Result from passive page or browser scenario comparison. */
 export const browserCaptureComparisonSchema = z.union([
     browserScenarioDiffSchema,

package/dist/domain/browserObservation.js

@@ -186,9 +186,7 @@ const DEFAULT_BROWSER_INSPECTION_LIMITS = {
     max_websocket_shape_bytes: 64 * 1_024,
     max_total_websocket_shape_bytes: 1_024 * 1_024,
 };
-/** Public input for one passive, bounded inspection of an existing page. */
-export const inspectWebPageInputSchema = z
-    .object({
+const inspectWebPageInputFacts = {
     ...approvedBrowserInput,
     target_id: z.string().trim().min(1).max(256),
     observation_ms: z.number().int().min(0).max(10_000).default(500),
@@ -199,12 +197,21 @@ export const inspectWebPageInputSchema = z
     json_body_schema_approved: z.boolean().default(false),
     include_websocket_shapes: z.boolean().default(false),
     websocket_shape_approved: z.boolean().default(false),
-    include_script_sources: z.boolean().default(false),
     include_storage_keys: z.boolean().default(false),
     include_storage_fingerprints: z.boolean().default(false),
     limits: browserInspectionLimitsSchema.default(DEFAULT_BROWSER_INSPECTION_LIMITS),
-})
-    .superRefine((input, context) => {
+};
+const inspectWebPageWithoutSourceSchema = z.strictObject({
+    ...inspectWebPageInputFacts,
+    include_script_sources: z.literal(false).default(false),
+    source_capture_approved: z.literal(false).default(false),
+});
+const inspectWebPageWithSourceShapeSchema = z.strictObject({
+    ...inspectWebPageInputFacts,
+    include_script_sources: z.literal(true).default(true),
+    source_capture_approved: z.literal(true),
+});
+const refineInspectWebPageInput = (input, context) => {
     if (input.include_storage_fingerprints && !input.include_storage_keys)
         context.addIssue({
             code: "custom",
@@ -260,14 +267,20 @@ export const inspectWebPageInputSchema = z
             path: ["limits", "max_websocket_shape_bytes"],
             message: "Per-frame WebSocket limit cannot exceed the total frame limit",
         });
-    if (input.limits.max_ax_text_field_bytes >
-        input.limits.max_total_ax_text_bytes)
+    if (input.limits.max_ax_text_field_bytes > input.limits.max_total_ax_text_bytes)
         context.addIssue({
             code: "custom",
             path: ["limits", "max_ax_text_field_bytes"],
             message: "Per-field accessibility text limit cannot exceed the total text limit",
         });
-});
+};
+/** Source-capturing inspection input, reusable by static bundle analysis. */
+export const inspectWebPageWithSourceInputSchema = inspectWebPageWithSourceShapeSchema.superRefine(refineInspectWebPageInput);
+/** Public input for one passive, bounded inspection of an existing page. */
+export const inspectWebPageInputSchema = z.union([
+    inspectWebPageWithoutSourceSchema.superRefine(refineInspectWebPageInput),
+    inspectWebPageWithSourceInputSchema,
+]);
 export const sanitizedBrowserUrlSchema = z.object({
     url: z.string().max(MAX_SANITIZED_BROWSER_URL_CHARS),
     origin: z.string().max(2_048).nullable(),