rea-agents 3.0.0 → 3.2.0

package/dist/contracts/toolOutputSchemaGroups.js

@@ -1,12 +1,14 @@
 import { z } from "zod";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { residualUnknownSchema } from "../domain/residualUnknown.js";
+import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
+import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
 import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
 import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
 import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
-import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { artifactExtractionResultSchema } from "../domain/artifactGraph.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
+import { interfaceBuilderAnalysisSchema } from "../domain/interfaceBuilderGraph.js";
 import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
 import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
 import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
@@ -22,7 +24,9 @@ import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCor
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, analysisActivity, addressedEntry, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { nativeDispatchMetadataResultSchema } from "../domain/objcSwiftMetadata.js";
+import { nativeInvestigationTraceSchema } from "../domain/nativeInvestigationGraph.js";
+import { addressList, addressedValue, addressedEntry, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, segmentOutput, sessionProvider, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 const contextFacetSchema = z.discriminatedUnion("state", [
     z.object({ state: z.literal("available"), value: jsonValueSchema }),
     z.object({
@@ -31,6 +35,25 @@ const contextFacetSchema = z.discriminatedUnion("state", [
         remediation: z.string(),
     }),
 ]);
+const bookmarkFacetSchema = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("available"), value: z.array(addressedEntry) }),
+    z.object({
+        state: z.literal("unavailable"),
+        reason: z.string(),
+        remediation: z.string(),
+    }),
+]);
+const addressedString = z.object({
+    address: z.string(),
+    value: z.string(),
+    string: z
+        .object({
+        encoding: z.string().min(1),
+        termination: z.enum(["missing", "present_or_not_required"]),
+        byte_length: z.number().int().min(0),
+    })
+        .optional(),
+});
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -42,10 +65,10 @@ export const officialOutputSchemas = {
     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_names: resultOf(z.array(addressedValue)),
+    list_procedures: resultOf(z.array(addressedValue)),
     list_segments: segmentOutput,
-    list_strings: resultOf(pageOutput),
+    list_strings: resultOf(z.array(addressedString)),
     next_address: resultOf(z.string()),
     prev_address: resultOf(z.string()),
     procedure_address: resultOf(z.string()),
@@ -56,8 +79,8 @@ export const officialOutputSchemas = {
     read_function_instructions: resultOf(functionInstructionWindowSchema),
     read_bytes: resultOf(z.object({
         address: z.string(),
-        requested_bytes: z.number().int().min(1).max(4_096),
-        returned_bytes: z.number().int().min(0).max(4_096),
+        requested_bytes: z.number().int().min(1),
+        returned_bytes: z.number().int().min(0),
         bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
         complete: z.boolean(),
     })),
@@ -68,20 +91,18 @@ export const officialOutputSchemas = {
     procedure_references: resultOf(z.object({
         procedure: procedureIdentity,
         direction: z.enum(["incoming", "outgoing"]),
-        references: bounded(z.object({
+        references: z.array(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),
+    search_procedures: resultOf(z.array(z.object({ address: z.string(), value: z.string() }))),
+    search_strings: resultOf(z.array(z.object({ address: z.string(), value: z.string() }))),
     set_address_name: resultOf(z.boolean()),
     set_addresses_names: resultOf(z.record(z.string(), z.boolean())),
     set_bookmark: resultOf(z.boolean()),
@@ -94,8 +115,6 @@ export const officialOutputSchemas = {
 const literalTraceOutput = 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(),
@@ -128,13 +147,8 @@ const callPathTraceOutput = resultOf(z.object({
         address: z.string(),
         error: analysisErrorProjectionSchema,
     })),
-    frontier: z.array(z.string()),
-    limits: z.object({
-        max_depth: z.number().int().min(1),
-        max_nodes: z.number().int().min(1),
-        max_operations: z.number().int().min(1),
+    traversal: z.object({
         nodes_visited: z.number().int().min(1),
-        operations_used: z.number().int().min(0),
     }),
     truncated: z.boolean(),
     residual_unknowns: z.array(z.string()),
@@ -142,7 +156,8 @@ const callPathTraceOutput = resultOf(z.object({
 }));
 /** Exact structured-content schemas for composed analysis workflows. */
 export const enhancedOutputSchemas = {
-    swift_classes: symbolDiscoveryOutput("classes"),
+    inspect_native_dispatch_metadata: resultOf(nativeDispatchMetadataResultSchema),
+    trace_native_ui_action: resultOf(nativeInvestigationTraceSchema),
     get_objc_classes: symbolDiscoveryOutput("classes"),
     get_objc_protocols: symbolDiscoveryOutput("protocols"),
     batch_decompile: resultOf(z.object({
@@ -185,12 +200,11 @@ export const enhancedOutputSchemas = {
     ])),
     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(),
+            length: z.number().min(0),
         })),
         segment_count: z.number().int().min(0),
         procedure_count: z.number().int().min(0),
@@ -202,7 +216,7 @@ export const enhancedOutputSchemas = {
     find_code_for_string: literalTraceOutput,
     trace_call_path: callPathTraceOutput,
 };
-/** Exact Evidence v2 schemas for provider-neutral native inspection. */
+/** Exact Evidence schemas for provider-neutral native inspection. */
 export const nativeOutputSchemas = {
     inspect_macho: resultOf(inspectMachoSchema),
     inspect_signature: resultOf(inspectSignatureSchema),
@@ -210,19 +224,19 @@ export const nativeOutputSchemas = {
     list_architectures: resultOf(listArchitecturesSchema),
     demangle_swift: resultOf(demangleSwiftSchema),
 };
-/** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
+/** Exact Evidence schemas for provider-neutral artifact graph operations. */
 export const artifactOutputSchemas = {
-    inventory_artifact: resultOf(artifactInventoryResultSchema),
     inspect_artifact: resultOf(artifactInspectionResultSchema),
     extract_artifact: resultOf(artifactExtractionResultSchema),
+    decode_interface_builder: resultOf(interfaceBuilderAnalysisSchema),
 };
-/** Exact Evidence v2 schema for execution-free managed static analysis. */
+/** Exact Evidence 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. */
+/** Exact Evidence schema for provider-neutral managed workflows. */
 export const managedWorkflowOutputSchemas = {
     compare_managed_members: resultOf(managedMemberComparisonResultSchema),
     verify_managed_native_boundaries: resultOf(managedNativeVerificationResultSchema),
@@ -249,51 +263,11 @@ export const sessionOutputSchemas = {
         }),
     ])),
     binary_session: lifecycleResultOf(z.union([
-        z.object({
-            view: z.literal("summary"),
-            open: z.boolean(),
-            provider: providerIdentity,
-            active_provider: providerIdentity.nullable(),
-            target: z
-                .object({
-                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(),
-            })
-                .nullable(),
-            alignment: z.object({
-                state: z.enum(["aligned", "mcp_server_restart_required", "unknown"]),
-                reasons: z.array(z.string()),
-                remediation: z.string().nullable(),
-            }),
-            analysis_activity: analysisActivity,
-            recommended_actions: z.array(z.string()),
-        }),
-        z.object({
-            view: z.literal("capabilities"),
-            open: z.boolean(),
-            provider: providerIdentity,
-            active_provider: providerIdentity.nullable(),
-            capability_family: z.string().nullable(),
-            capabilities: z.object({
-                items: z.array(toolAvailability),
-                cursor: z.number().int().min(0),
-                limit: z.number().int().min(1),
-                total: z.number().int().min(0),
-                next_cursor: z.number().int().min(0).nullable(),
-                has_more: z.boolean(),
-            }),
-            client_features: clientFeatureAvailabilitySchema,
-        }),
         z.union([
             sessionProvider.extend({
-                view: z.literal("full"),
                 open: z.literal(false),
             }),
             sessionProvider.extend({
-                view: z.literal("full"),
                 open: z.literal(true),
                 path: z.string(),
                 format: targetFormatSchema,
@@ -309,14 +283,7 @@ export const sessionOutputSchemas = {
         records: z.number().int().min(0),
         unknowns: z.number().int().min(0),
     })),
-    snapshot_evidence_bundle: lifecycleResultOf(z.object({
-        bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
-        bundle_version: z.literal(2),
-        bytes: z.number().int().min(0),
-        records: z.number().int().min(0),
-        unknowns: z.number().int().min(0),
-        bundle_uri: z.string().regex(/^rea:\/\/evidence-bundle\/[a-f0-9]{64}$/u),
-    })),
+    get_evidence_bundle: lifecycleResultOf(evidenceBundleSchema),
     get_navigation_context: lifecycleResultOf(z.object({
         document: z.string(),
         address: z.string(),
@@ -329,10 +296,11 @@ export const sessionOutputSchemas = {
         procedure: contextFacetSchema,
         comment: contextFacetSchema,
         inline_comment: contextFacetSchema,
-        bookmarks: contextFacetSchema,
+        bookmarks: bookmarkFacetSchema,
     })),
     import_evidence_bundle: lifecycleResultOf(z.object({
         imported: z.number().int().min(0),
+        unknowns_added: z.number().int().min(0),
         total: z.number().int().min(0),
     })),
     capture_process_scenario: resultOf(processCaptureSchema),
@@ -345,15 +313,8 @@ export const sessionOutputSchemas = {
     correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
     verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
     list_unknowns: lifecycleResultOf(z.object({
-        items: z.array(z.object({
-            unknown: residualUnknownSchema,
-            uri: z.string().regex(/^rea:\/\/unknown\/unk_[a-f0-9]{64}$/u),
-        })),
-        offset: z.number().int().min(0),
-        limit: z.number().int().min(1).max(500),
+        items: z.array(residualUnknownSchema),
         total: z.number().int().min(0),
-        next_offset: z.number().int().min(0).nullable(),
-        has_more: z.boolean(),
     })),
     record_unknown: lifecycleResultOf(residualUnknownSchema),
     update_unknown: lifecycleResultOf(residualUnknownSchema),

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -1,13 +1,18 @@
 import { z } from "zod";
 import { procedureClassificationSchema, procedureIdentitySchema, localVariableSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { analysisProfileSchema } from "../domain/analysisProfile.js";
+import { evidenceEnvelopeSchema } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { PROVIDER_REJECTION_CODES, } from "./providerSelection.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-/** Compact MCP result with an immutable link to complete session Evidence. */
+/** Inline result with its complete Evidence record. */
+export const inlineEvidenceRecordSchema = evidenceEnvelopeSchema.omit({
+    normalized_result: true,
+});
 export const evidenceResultOf = (schema) => z.strictObject({
     result: schema,
     evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-    evidence_uri: z.string().regex(/^rea:\/\/evidence\/ev_[a-f0-9]{64}$/u),
+    evidence: inlineEvidenceRecordSchema,
 });
 const resultOf = evidenceResultOf;
 export const lifecycleResultOf = (schema) => z.object({ result: schema });
@@ -42,15 +47,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"]),
-    exhaustive: z.boolean(),
     effects: z.object({
         mutates_artifact: z.boolean(),
         launches_process: z.boolean(),
@@ -60,13 +58,22 @@ const providerCapability = z.object({
         changes_permissions: z.boolean(),
         requires_root: z.boolean(),
     }),
-    limits: z.object({
-        max_results: z.number().int().min(0).nullable(),
-        max_payload_bytes: z.number().int().min(0).nullable(),
-        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(),
@@ -86,7 +93,6 @@ const processLineageObservation = z.discriminatedUnion("status", [
     z.object({
         status: z.literal("verified"),
         observed_at: z.iso.datetime(),
-        schema_version: z.literal(1),
         ...processCoordinates,
         launcher_parent_pid: z.number().int().min(0),
         descendants: z.array(z.object({
@@ -112,7 +118,7 @@ const analysisRun = z
 })
     .nullable();
 export const analysisActivity = z.object({
-    status: z.enum(["not_observed", "idle", "busy", "timed_out_busy"]),
+    status: z.enum(["not_observed", "idle", "busy"]),
     providers: z.array(z.object({
         provider: providerIdentity,
         active: z
@@ -120,15 +126,14 @@ export const analysisActivity = z.object({
             request_id: z.number().int().min(1),
             operation: z.string().min(1),
             elapsed_ms: z.number().int().min(0),
-            timeout_ms: z.number().int().min(0),
-            caller_state: z.enum(["waiting", "timed_out", "cancelled"]),
+            caller_state: z.enum(["waiting", "cancelled"]),
         })
             .nullable(),
         queued_requests: z.number().int().min(0),
     })),
 });
 const providerRejectionCode = z.enum(PROVIDER_REJECTION_CODES);
-const providerDiagnostics = z.record(z.string(), z.json());
+const providerDiagnostics = z.record(z.string(), jsonValueSchema);
 const providerAvailability = z.discriminatedUnion("status", [
     z.object({
         status: z.literal("available"),
@@ -182,21 +187,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()).length(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,8 +228,32 @@ export const toolAvailability = z.object({
         idempotent: z.boolean(),
         open_world: z.boolean(),
     }),
-});
-export const sessionProvider = z.object({
+};
+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),
     capabilities: z.array(providerCapability),
@@ -276,7 +309,6 @@ export const sessionProvider = z.object({
         protocol_features: z.object({
             progress: z.boolean(),
             cancellation: z.boolean(),
-            evidence_resources: z.boolean(),
             elicitation: z.boolean(),
         }),
         alignment: z.object({
@@ -285,7 +317,8 @@ export const sessionProvider = z.object({
             remediation: z.string().nullable(),
         }),
     }),
-});
+})
+    .passthrough();
 export const nullableText = z.string().nullable();
 export const addressList = z.array(z.string());
 export const addressedEntry = z.object({
@@ -315,17 +348,9 @@ 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(),
-});
-const addressedValue = z.object({
+export const addressedValue = z.object({
     address: z.string(),
     value: z.string(),
-    value_truncated: z.boolean().optional(),
     symbol: z
         .object({
         primary: z.boolean(),
@@ -350,21 +375,6 @@ const addressedValue = z.object({
     })
         .optional(),
 });
-export const pageOutput = z.object({
-    items: z.array(addressedValue),
-    offset: z.number().int().min(0),
-    limit: z.number().int().min(1),
-    total: z.number().int().min(0),
-    next_offset: z.number().int().min(0).nullable(),
-    has_more: z.boolean(),
-});
-export const searchPageOutput = pageOutput.extend({
-    items: z.array(z.object({
-        address: z.string(),
-        value: z.string(),
-        value_truncated: z.boolean(),
-    })),
-});
 const memoryRegionOutput = z.object({
     name: z.string(),
     start: z.string(),

package/dist/contracts/toolSchemaMetadata.js

@@ -0,0 +1,117 @@
+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.",
+    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 record produced by this operation.",
+    evidence_id: "Stable identifier of the recorded Evidence observation.",
+    executable: "Approved absolute path of the executable to run.",
+    format: "Declared input artifact format.",
+    name: "Exact name used by this operation.",
+    pattern: "Literal text or regular expression 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.",
+    limits: "Resource budgets that bound execution and retained output for this operation.",
+    mode: "Operation mode that selects the requested behavior.",
+    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.",
+    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 Swift symbols to demangle.",
+    target_id: "Exact authorized CDP target identifier.",
+    unknown_id: "Exact residual-unknown identifier.",
+};
+/** 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.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 identifier for the ${words.slice(0, -12)} observation.`;
+    if (property.endsWith("_evidence_ids"))
+        return `Ordered Evidence 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 `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/contracts/unknownContractExamples.js

@@ -2,7 +2,6 @@
 export const UNKNOWN_CONTRACT_EXAMPLES = {
     list_unknowns: {},
     record_unknown: {
-        approved: true,
         question: "Does this branch require an unavailable external service?",
         severity: "medium",
         domain: "protocol",
@@ -15,7 +14,6 @@ export const UNKNOWN_CONTRACT_EXAMPLES = {
         relationships: [],
     },
     update_unknown: {
-        approved: true,
         unknown_id: `unk_${"0".repeat(64)}`,
         expected_revision: 1,
         status: "investigating",

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,