Tools

Add React Native native tool suites, React inspection tools, artifact providers, JavaScript custom tools, or native custom tools, gate them with ToolGuard, and keep them limited to local development workflows.

React Native exposes native tool suites from iOS and Android plus JavaScript-backed and native custom tools registered in app code.

Important Security Rule

Do not ship broad native tools, JavaScript custom tools, or React action tools in App Store, Play Store, CI release, or other distributable builds unless the capability is explicitly approved.

Do this:

enable broad tools only behind an app-owned local development condition
use the narrowest guard that works for the workflow
keep React props, state, actions, secure storage, and file-system access opt-in

Do not do this:

ship fullAccess broadly
enable React actions unless a workflow explicitly needs them
expose secret, file, or runtime mutation tools without allow-lists

Native Tool Registration

The native bridge registers FileSystem, Database, Preferences, Reflection, and SecureStorage suites during initialization. VisualTree is opt-in because it exposes rendered UI structure and screenshots. When native all-in-one defaults are enabled, the Android aggregate also registers file-descriptor and JNI-reference diagnostics. Suite-specific JavaScript options flow through remoteTools.

await Ansight.initializeAndActivate(
  Ansight.createOptionsBuilder()
    .withReadOnlyToolAccess()
    .withVisualTreeTools()
    .withDatabaseTools({
      includePlatformRoots: true,
      additionalRoots: [{ alias: "fixtures", path: "/tmp/app-db" }],
    })
    .withFileSystemTools({
      additionalRoots: [{ alias: "exports", path: "/tmp/app-exports" }],
    })
    .withPreferencesTools({
      allowedStores: ["standard"],
      allowedKeyPrefixes: ["debug."],
    })
    .withReflectionTools({
      includeBuiltInRoots: true,
      allowedRootIds: ["application"],
      allowedTypePrefixes: ["com.example."],
    })
    .withRemoteTools({
      secureStorage: {
        allowedKeys: ["debug_token"],
        allowedKeyPrefixes: ["debug."],
      },
    })
    .build(),
);

secureStorage.preferencesName is Android-specific. secureStorage.appleService is iOS-specific. The top-level secureStorage option is accepted as a compatibility alias for remoteTools.secureStorage.

Runtime Availability

Native catalog entries expose current availability, unmet state, remediation, and retryability through runtime, with a top-level executable flag. The native runtime rechecks availability immediately before execution. JavaScript-backed React and custom tools are considered available while registered because their registration API does not currently expose a pre-invocation availability callback; unregister them when unavailable or return a stable handler failure.

Suite Registration API

Surface	Common API
VisualTree	`withVisualTreeTools()`, `remoteTools.visualTree`
Native Database	`withDatabaseTools(...)`, `remoteTools.database`
Native FileSystem	`withFileSystemTools(...)`, `remoteTools.fileSystem`
Native File Descriptor Diagnostics	Native all-in-one defaults; no suite-specific JavaScript option
Native Android JNI Reference Diagnostics	Native all-in-one defaults; no suite-specific JavaScript option
Native Preferences	`withPreferencesTools(...)`, `remoteTools.preferences`
Native SecureStorage	`withRemoteTools({ secureStorage: ... })`, `remoteTools.secureStorage`, top-level `secureStorage` alias
Native Reflection	`withReflectionTools(...)`, `remoteTools.reflection`
React Inspection	`installReactTools(...)`, `uninstallReactTools()`
JavaScript Custom Tools	`registerTool(...)`, `unregisterTool(...)`, `listRegisteredTools()`, `clearRegisteredTools()`
Native Custom Tools	iOS `AnsightRuntime.shared.registerTool(...)`, Android `AnsightRuntime.registerTool(...)`
Artifacts	`registerArtifactProvider(...)`, `registerArtifactProviders(...)`, `unregisterArtifactProvider(...)`, `clearArtifactProviders()`

Guard Levels

Guard	What it allows
`withToolsDisabled()` / `"disabled"`	No discovery, no execution.
`withReadOnlyToolAccess()` / `"readOnly"`	Maximum policy `read`.
`withReadWriteToolAccess()` / `"readWrite"`	Maximum policy `write`.
`withAllToolAccess()` / `"fullAccess"`	Maximum policy `critical`.

Tool Suites

Native tool ids match the underlying iOS and Android SDKs. Artifacts are documented separately in Artifacts.

Suite	Typical use
VisualTree	Inspect native hierarchy, capture screenshots, and manage overlays.
Database	Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	List directories, read files, download files, push, copy, move, and delete files inside approved roots.
Native File Descriptor Diagnostics	Use `file_descriptors.*` to count and inspect open descriptors when the native aggregate defaults are active. Configure the suite in native code when custom target visibility is required.
Native Android JNI Reference Diagnostics	Use `jni_references.capture_graph` for an explicit bounded JNI-rooted heap investigation when native all-in-one defaults are active. Configure suite maxima in native Android code.
Preferences	Read and mutate native preferences under store/key allow-lists.
SecureStorage	Read and mutate native secure storage under explicit key allow-lists.
Reflection	Inspect native registered roots and built-in roots according to platform support and options.
React Inspection	Inspect React Fiber component trees, React Native host trees, navigation state, and optional component actions.
JavaScript Custom Tools	Expose narrow app-specific development operations.
Native Custom Tools	Expose narrow app-specific Swift or Kotlin operations.

Recommended Defaults

For most teams:

Start with installReactTools(...) without props, state, or actions.
Use withReadOnlyToolAccess() by default.
Add native VisualTree only when the local host workflow needs platform view hierarchy or native screenshots.
Add Database only when SQLite inspection is needed.
Use native file-descriptor diagnostics for resource-leak investigations when all-in-one defaults are active.
Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
Add Artifacts when app-specific output should become a streamed file or durable session artifact.
Add JavaScript or native custom tools only for narrow operations that packaged suites cannot cover.
Raise the maximum policy to write or critical only when the workflow genuinely depends on it.