Task API Reference

Reference for repository task descriptors, invocation types, host evidence APIs, app-tool suites, result envelopes, and named assertions.

CLI v0.23.1 21 August 2026

Repository tasks use the generated ansight/tasks/ansight-task.d.ts contract. That declaration file is the authoritative API for the installed Ansight version; this page is its navigable reference.

Run ansight workspace init . to create or refresh the declaration in a new workspace. Existing customized support files are preserved unless --force is supplied.

Module shape

Every task exports a JSON-compatible descriptor and one default function:

import type {
  TaskDefinition,
  TaskInvocation
} from "./ansight-task.d.ts";

type Input = { automationId: string };
type Output = { matchCount: number };

export const task = {
  schemaVersion: 1,
  title: "Verify home",
  description: "Proves that the signed-in home screen is visible."
} satisfies TaskDefinition;

export default async function run(
  { run, input, ansight, app, check }: TaskInvocation<Input>
): Promise<Output> {
  const result = await ansight.ui.assert({
    automationId: input.automationId,
    exists: true
  });

  check.ok(result.passed, "home-visible");
  return { matchCount: result.matchCount };
}

`TaskDefinition`

Field	Type	Required	Contract
`schemaVersion`	`1`	No	Defaults to version 1.
`appId`	`string`	No	Exact optional app scope.
`title`	`string`	Yes	Short discovery label.
`description`	`string`	Yes	Complete workflow and authoritative result.
`feature`	`string`	No	Focused discovery domain such as `map`.
`keywords`	`string[]`	No	At most 32 discovery terms.
`inputSchema`	`JsonSchema`	No	Validates the object supplied as `input` and applies defaults.
`outputSchema`	`JsonSchema`	No	Describes returned output; version 1 does not enforce it.
`hostTools`	`string[]`	No	Extra Studio tools callable through `ansight.callTool`; maximum 32.
`timeoutSeconds`	`number`	No	Whole run: 1–300 seconds; default 120.
`maximumActions`	`number`	No	Host and app calls: 1–100; default 64.

The descriptor must be a static object literal. Do not use functions, variables, spreads, or computed values inside it.

`TaskInvocation<TInput>`

Property	Type	Meaning
`run`	`Readonly<TaskRun>`	Host-owned run identity and effective limits.
`input`	`Readonly<TInput>`	Validated input after schema defaults are applied.
`ansight`	`AnsightHost`	Session-pinned host evidence and control methods.
`app`	`TaskAppContext`	Standard app-tool suites and custom-tool bridge.
`check`	`TaskCheckContext`	Named assertions that establish pass or failure.

`TaskRun`

Property	Type	Meaning
`runId`	`string`	Unique run ID.
`taskId`	`string`	Repository-relative task ID.
`appId`	`string`	Exact app scope enforced by the host.
`sessionId`	`string`	Live session enforced for every call.
`repositoryRootPath`	`string`	Absolute connected repository root.
`timeoutSeconds`	`number`	Effective whole-task timeout.
`maximumActions`	`number`	Effective action limit.

`ansight`: host API

Host methods are bound to run.sessionId. Target fields supplied by task code are discarded and the selected session is injected.

Namespace	Methods	Main result contracts
`ansight.session`	`getAppState()`, `getProperties<T>()`, `getTimeline(args?)`	`SessionAppStateResult`, `SessionPropertiesResult<T>`, `SessionTimelineResult`
`ansight.ui`	`find(args?)`, `waitFor(args?)`, `assert(args?)`, `tap(args?)`, `typeText(args)`, `swipe(args?)`, `scroll(args?)`, `back(args?)`, `getLiveVisualTree(args?)`, `getVisualTreeSnapshot(args?)`, `searchVisualTree(args?)`	`UiFindResult`, `UiWaitResult`, `UiAssertResult`, `UiActionResult`, visual-tree contracts
`ansight.logs`	`get(args?)`, `search(args)`, `getContext(args?)`, `getFacets(args?)`, `getTimeline(args?)`, `summarizeWindow(args?)`, `extractExceptions(args?)`	Captured log, context, facet, timeline, summary, and exception contracts
`ansight.artifacts`	`getNearest(args?)`, `getSession(args?)`, `listFiles(args?)`, `readFile(args)`	Artifact descriptor and file contracts
`ansight.screenshots`	`take(args?)`, `getFrame(args?)`, `assert(args?)`	Live capture envelope, persisted frame, and screenshot assertion
`ansight.database`	`assert(args)`	`DatabaseAssertResult`
`ansight.telemetry`	`get(args?)`, `getTimeline(args?)`, `summarizeWindow(args?)`	Telemetry samples, timeline, and summary
`ansight.touches`	`getTimeline(args?)`, `getContext(args?)`, `getGestureSegments(args?)`, `findTapTargets(args?)`, `getHeatmap(args?)`, `findDead(args?)`, `getArtifacts(args?)`, `summarizeFlow(args?)`	Touch, gesture, heatmap, dead-touch, evidence, and flow contracts
`ansight.annotations`	`get(args?)`	`AnnotationsResult`
`ansight.appTools`	`list()`	`AppToolListResult`
`ansight.lifecycle`	`launch()`, `terminate()`	`AppLifecycleResult`
`ansight.device`	`setLocation(args)`, `clearLocation()`	Device location results
`ansight`	`callTool<TResult>(name, args?)`	Structured result of an extra declared host tool

UI selectors

UiSelector is shared by find, wait, assert, and UI actions:

interface UiSelector {
  nodeId?: string;
  automationId?: string;
  text?: string;
  role?: string;
  type?: string;
  ancestorAutomationId?: string;
  action?: string;
  visible?: boolean;
  enabled?: boolean;
  exact?: boolean;
  caseSensitive?: boolean;
  index?: number;
}

Use ansight.ui.assert for evidence-producing expectations and waitFor for a bounded state transition. UiAssertArguments additionally supports expectedCount, expectedText, expectedValue, expectedVisible, expectedEnabled, and an optional actionId.

Time windows

Log, telemetry, touch, annotation, artifact, and timeline methods accept their typed argument contracts from ansight-task.d.ts. Time-bound contracts use ISO-8601 UTC timestamps and bounded result limits. Prefer typed methods over ansight.callTool because they inject the task session and return stable named contracts.

`app`: live app API

Every standard app method returns Promise<AppToolCallResult<TResult>>. The host pins the request to the task session, while the connected app enforces tool availability, grants, argument schemas, and critical-operation policy.

Namespace	Methods
`app.artifacts`	`query(args?)`, `request(args)`
`app.ui`	`getVisualTree(args?)`, `getScreenshot(args?)`, `inspectNode(args?)`, `showOverlay(args?)`, `getOverlay(args?)`, `queryOverlays(args?)`, `updateOverlay(args?)`, `removeOverlay(args?)`, `clearOverlays(args?)`
`app.files`	`listDirectory(args?)`, `readFile(args?)`, `getChecksum(args?)`, `download(args?)`, `beginBinaryDownload(args?)`, `push(args?)`, `copy(args?)`, `move(args?)`, `delete(args?)`
`app.fileDescriptors`	`listOpen(args?)`, `countOpen(args?)`, `inspect(args?)`, `getUsage(args?)`
`app.jniReferences`	`captureGraph(args?)`
`app.preferences`	`listKeys(args?)`, `get(args?)`, `set(args?)`, `remove(args?)`
`app.secureStorage`	`get(args?)`, `set(args?)`, `remove(args?)`
`app.data`	`listDatabases(args?)`, `describeSchema(args?)`, `query(args?)`
`app.reflection`	`listRoots(args?)`, `inspectObject(args?)`, `describeType(args?)`, `setMemberValue(args?)`, `invokeMethod(args?)`
`app.maui`	`getCurrentPage(args?)`, `getVisualTree(args?)`, `findElements(args?)`, `getElement(args?)`, `getBindableProperty(args?)`, `setBindableProperty(args?)`, `clearBindableProperty(args?)`, `inflateXaml(args?)`, `addElement(args?)`, `removeElement(args?)`, `setAppTheme(args?)`, `getBindingContext(args?)`, `getBindings(args?)`, `getResourceState(args?)`, `getNavigationState(args?)`, `invokeElementAction(args?)`, `waitForUi(args?)`, `getLayoutDiagnostics(args?)`, `getHandlerDiagnostics(args?)`, `invokeBindingContextCommand(args?)`, `setBindingContextProperty(args?)`
`app.react`	`getComponentTree(args?)`, `getShadowTree(args?)`, `findComponents(args?)`, `getComponent(args?)`, `getNavigationState(args?)`, `invokeComponentAction(args?)`
`app.flutter`	`getWidgetTree(args?)`, `inspectWidget(args?)`, `findWidgets(args?)`, `getNavigationState(args?)`
`app.capacitor`	`getDocument(args?)`, `inspectNode(args?)`, `querySelector(args?)`, `invokeAction(args?)`
`app`	`callTool<TResult>(toolId, args?)` for an app-defined tool

Standard suites require the corresponding SDK tool registration. A method can exist in the TypeScript contract while being unavailable in the selected app or denied by its runtime guard.

`AppToolCallResult<TResult>`

App results use a discriminated envelope:

type AppToolCallResult<TResult> =
  | {
      responseType: "tool.result";
      sessionId: string;
      appId: string;
      toolId: string;
      payload: {
        success: true;
        toolId: string;
        result: TResult;
        message?: string | null;
      };
    }
  | {
      responseType: "tool.error";
      sessionId: string;
      appId: string;
      toolId: string;
      payload: {
        success?: false;
        code: string;
        message: string;
        retryable: boolean;
        details?: JsonValue | null;
      };
    };

The full envelope can also contain Studio-applied defaults, associated artifacts, and persisted-visual-tree metadata. Narrow on responseType before reading the typed success result.

`check`: named assertions

Method	Behavior
`check.ok(actual, id, message?)`	Passes for a truthy value; returns the non-null value.
`check.equal(actual, expected, id, message?)`	Uses deterministic deep equality.
`check.notEqual(actual, expected, id, message?)`	Requires deterministic inequality.
`check.includes(actual, expected, id, message?)`	Checks string inclusion or exact array membership.
`check.fail(id, message, actual?)`	Records failure and terminates the function.

Assertion IDs must be stable and unique. At least one assertion must pass and none may fail for the task status to be Passed. Returning normally without an assertion produces Inconclusive.

Execution rules

Await host and app calls serially; overlapping calls are rejected.
Standard host APIs need no hostTools declaration.
ansight.callTool accepts only names declared in task.hostTools.
app.callTool targets app-defined tools and needs no descriptor declaration.
Every call counts toward maximumActions.
Tasks can access only the enforced live session through Ansight APIs.
Repository TypeScript is trusted local code, not a filesystem or network sandbox.

Module shape

TaskDefinition

TaskInvocation<TInput>

TaskRun

ansight: host API