See the live app state behind the UI

Inspect exposed runtime objects in your Android app to understand the state driving its behavior.

Reflection tools let you examine exposed runtime objects when a screen alone does not explain an app’s behavior. Keep roots and traversal narrow, and enable inspection, mutation, or invocation only under the required tool policy.

Install

Published artifact: ai.ansight:ansight-tools-reflection-android.

dependencies {
    debugImplementation("ai.ansight:ansight-tools-reflection-android:latest.release")
}

Register the Suite

import ai.ansight.runtime.AnsightOptions
import ai.ansight.tools.reflection.AndroidReflectionRootRegistry
import ai.ansight.tools.reflection.withReflectionTools

AndroidReflectionRootRegistry.register(
    id = "session",
    value = sessionViewModel,
    displayName = "Current Session",
)

val options = AnsightOptions.createBuilder()
    .withReflectionTools {
        allowRoot("session")
        allowTypePrefix("com.example.")
    }
    .withReadOnlyToolAccess()
    .build()

The read-only guard enables reflect.list_roots and reflect.describe_type. Inspecting live object values with reflect.inspect_object, setting members, or invoking methods uses Critical and requires withAllToolAccess() for that local development workflow.

Registration API

AndroidReflectionRootRegistry.register(...): exposes a live object root.
AndroidReflectionRootRegistry.registerGetter(...): exposes a root through a getter.
AndroidReflectionRootRegistry.deregister(...): removes one root.
AndroidReflectionRootRegistry.clear(): removes all roots.
withReflectionTools(...): registers the reflection suite.
allowRoot(...) / allowTypePrefix(...): narrows reflection traversal.

Specific Concerns

Reflection can expose private state, model graphs, and user data.
Register narrow roots instead of broad application objects.
List and describe use Read; inspect, set, and invoke use Critical because they can disclose sensitive state or execute arbitrary app code.

Tool Matrix

Name	Id	Policy	Description
`List Reflection Roots`	`reflect.list_roots`	`Read`	Lists registered reflection roots and availability.
`Inspect Object`	`reflect.inspect_object`	`Critical`	Returns a snapshot of a registered live object or nested path.
`Describe Type`	`reflect.describe_type`	`Read`	Returns runtime type metadata.
`Set Member Value`	`reflect.set_member_value`	`Critical`	Writes a settable field or property reachable from a registered root.
`Invoke Method`	`reflect.invoke_method`	`Critical`	Invokes a method reachable from a registered root.

Tool Details

Use read tools to list roots and describe types. Object snapshots, mutation, and invocation require critical access, even when an inspection does not change app state. Keep roots and type traversal narrowly scoped when enabling withAllToolAccess().

Root descriptors returned by reflect.list_roots include hostRuntime, which identifies the runtime that owns the root. Android roots report kind: "jvm" with the Android JVM/ART runtime display name, so clients can route reflection commands to the native runtime boundary instead of inferring ownership from root ids or labels.