Workspace App Tool API
When to use each app-tool method in repository tasks and triggers, and how live app results and actions differ.
app exposes tools registered by the connected app SDK. In a task, await app.<suite>.<method>(args) executes a tool and returns an AppToolCallResult. In a trigger, the same call shape builds an action; return exactly one action from the trigger function without awaiting it. The host pins both to the matched session and the app applies its normal tool guard and grants.
The arguments for most suites are app-tool JSON objects. Consult the connected app’s tool catalog for the exact schema, limits, and availability; the TypeScript method name alone cannot guarantee that the app registered that tool. app.available in tasks tells you whether an SDK provider exists. For a required tool, declare its ID in requires.appTools with schema version 2 so an unavailable app fails before task or trigger execution.
// In a task: execute, inspect the envelope, then make a named assertion.
const response = await app.data.listDatabases({});
if (response.responseType === "tool.error") {
throw new Error(`${response.payload.code}: ${response.payload.message}`);
}
expect(response.payload.success, { id: "databases-readable" }).toBe(true);The tables below describe what to use each method for. Read methods normally require a Read tool policy; mutations need Write or Critical as declared by the app. Use the live tool catalog to check a particular installation.
Artifacts and general UI
| Method | Use |
|---|---|
app.artifacts.query(args?) | Discover app-defined artifacts and provider IDs before requesting one. |
app.artifacts.request(args) | Ask a provider to create a particular artifact at the current session point; supply its providerId and artifactId. |
app.ui.getVisualTree(args?) | Read the SDK’s current native visual hierarchy when you need app-owned UI structure. |
app.ui.getScreenshot(args?) | Capture a current frame through the app SDK. For host-owned capture or retained frames, use ansight.screenshots. |
app.ui.inspectNode(args?) | Inspect one node after finding its ID in a visual tree. |
app.ui.showOverlay(args?) | Add a diagnostic overlay to highlight an app location or state. |
app.ui.getOverlay(args?) | Inspect one known overlay and its current settings. |
app.ui.queryOverlays(args?) | Find overlays before updating or removing them. |
app.ui.updateOverlay(args?) | Change an existing overlay rather than creating another. |
app.ui.removeOverlay(args?) | Remove one overlay when its diagnostic use is finished. |
app.ui.clearOverlays(args?) | Remove all app diagnostic overlays for a clean view. |
Files and runtime resources
app.files operates through the SDK inside the app sandbox. The host’s external ansight.files API has different capabilities and works without an SDK provider on supported sessions.
| Method | Use |
|---|---|
app.files.listDirectory(args?) | Discover sandbox entries before choosing a path. |
app.files.readFile(args?) | Read a small file through the app’s guarded file tool. |
app.files.getChecksum(args?) | Compare file content by hash without retrieving the full file. |
app.files.download(args?) | Request a file through the app tool’s normal download response. |
app.files.beginBinaryDownload(args?) | Start a binary transfer to the host; use for files that should be retained as session artifacts. |
app.files.push(args?) | Write supplied content into an allowed app sandbox location. |
app.files.copy(args?) | Duplicate an allowed sandbox file while keeping the original. |
app.files.move(args?) | Relocate or rename an allowed sandbox file. |
app.files.delete(args?) | Remove an allowed sandbox file after confirming the target. |
app.fileDescriptors.listOpen(args?) | List open descriptors when investigating leaks. |
app.fileDescriptors.countOpen(args?) | Get a lightweight open-descriptor count for comparison across steps. |
app.fileDescriptors.inspect(args?) | Examine one descriptor or related diagnostic value. |
app.fileDescriptors.getUsage(args?) | Read descriptor usage and limits to judge whether a count is concerning. |
app.jniReferences.captureGraph(args?) | Capture an Android JNI reference graph for leak diagnosis. |
App stores and reflection
| Method | Use |
|---|---|
app.preferences.listKeys(args?) | Discover keys in an app preferences store. |
app.preferences.get(args?) | Read selected preference values. |
app.preferences.set(args?) | Set a selected preference for a controlled test. |
app.preferences.remove(args?) | Remove a selected preference to test default behavior. |
app.clipboard.getText() | Read plain text from the native system clipboard; iOS may show a paste prompt. |
app.clipboard.hasText() | Check whether plain text is present without reading it. |
app.clipboard.setText({ text }) | Replace clipboard contents with test text. |
app.clipboard.clear() | Clear clipboard contents during cleanup. |
app.secureStorage.get(args?) | Inspect a selected secure-storage value when the app registers and permits this suite. |
app.secureStorage.set(args?) | Write a controlled secure-storage value for a test. |
app.secureStorage.remove(args?) | Remove a selected secure-storage value. |
app.data.listDatabases(args?) | Discover databases exposed by the app SDK. |
app.data.describeSchema(args?) | Inspect tables and columns before writing a read-only query. |
app.data.query(args?) | Run the app’s guarded database query to inspect domain state. |
app.reflection.listRoots(args?) | Discover roots that the app deliberately exposes for reflection. |
app.reflection.inspectObject(args?) | Read members of a selected exposed object. |
app.reflection.describeType(args?) | Inspect type members and signatures before invoking or setting one. |
app.reflection.setMemberValue(args?) | Change a member in a controlled development workflow. |
app.reflection.invokeMethod(args?) | Call an exposed method when a narrow app-specific tool is unavailable. |
Clipboard text is limited to 65,536 UTF-8 bytes. See Clipboard Tools. Secure storage and reflection can expose sensitive state; use the app’s guard and a narrowly selected target.
Framework inspection
These suites exist only when the matching framework adapter is registered in the app. Their argument shapes are defined by the app tools for that SDK version.
| Method | Use |
|---|---|
app.maui.getCurrentPage(args?) | Identify the active .NET MAUI page before inspecting its elements. |
app.maui.getVisualTree(args?) | Read the current MAUI element hierarchy. |
app.maui.findElements(args?) | Search MAUI elements by supported selectors. |
app.maui.getElement(args?) | Inspect a known MAUI element in detail. |
app.maui.getBindableProperty(args?) | Read one bindable property’s effective value. |
app.maui.setBindableProperty(args?) | Set a bindable property for a controlled UI test. |
app.maui.clearBindableProperty(args?) | Clear a local bindable value so its normal source applies. |
app.maui.inflateXaml(args?) | Create an element from supplied XAML for development diagnosis. |
app.maui.addElement(args?) | Insert an element into a selected MAUI container. |
app.maui.removeElement(args?) | Remove a selected inserted element. |
app.maui.setAppTheme(args?) | Switch app theme to reproduce a theme-specific issue. |
app.maui.getBindingContext(args?) | Inspect the view model bound to a selected element. |
app.maui.getBindings(args?) | Inspect binding expressions and sources for a selected element. |
app.maui.getResourceState(args?) | Inspect resolved resources and styles. |
app.maui.getNavigationState(args?) | Read the MAUI navigation stack or shell state. |
app.maui.invokeElementAction(args?) | Invoke an action on a selected MAUI element. |
app.maui.waitForUi(args?) | Poll MAUI UI state for a framework-specific condition. |
app.maui.getLayoutDiagnostics(args?) | Inspect layout measurements when a view is misplaced. |
app.maui.getHandlerDiagnostics(args?) | Inspect the native handler backing a MAUI view. |
app.maui.invokeBindingContextCommand(args?) | Invoke an exposed view-model command. |
app.maui.setBindingContextProperty(args?) | Change an exposed view-model property for a controlled test. |
app.react.getComponentTree(args?) | Read the React component hierarchy. |
app.react.getShadowTree(args?) | Read React Native’s layout/shadow hierarchy when geometry matters. |
app.react.findComponents(args?) | Search components before inspecting one. |
app.react.getComponent(args?) | Inspect a selected component and its exposed properties. |
app.react.getNavigationState(args?) | Read React Navigation state when a screen breadcrumb is insufficient. |
app.react.invokeComponentAction(args?) | Invoke an exposed React component action. |
app.flutter.getWidgetTree(args?) | Read the Flutter widget hierarchy. |
app.flutter.inspectWidget(args?) | Inspect a selected widget’s details. |
app.flutter.findWidgets(args?) | Search widgets before inspecting one. |
app.flutter.getNavigationState(args?) | Read Flutter route or navigation state. |
app.capacitor.getDocument(args?) | Read the current WebView DOM document. |
app.capacitor.inspectNode(args?) | Inspect a selected DOM node. |
app.capacitor.querySelector(args?) | Find DOM nodes with the adapter’s selector support. |
app.capacitor.invokeAction(args?) | Perform an allowed action on a selected DOM control. |
Custom tools and result handling
app.callTool<TResult>(toolId, args?) calls an app-defined tool that is not part of a standard suite. Discover the exact ID, schema, policy, and availability with ansight.appTools.list() in a task or the CLI’s tool catalog. Pass a type parameter only for the expected inner payload.result; the outer response is still an envelope that can report tool.error.
In a trigger, return app.callTool("app.capture_state", { reason: event.kind }) constructs one action. Do not await it or read a result inside the trigger function. The action runs later under the event’s session and correlation identity. See the Trigger API for timeout and retry behavior.