ui-query

Instructions

Implementation Reference

• src/tools/ui-query.ts:41-58 (handler)

  The main handler function for the "ui-query" tool, which routes the request to appropriate internal operations (dump, find, or accessibility-check).

  export async function handleUiQueryTool(
    input: UiQueryInput,
    context: ServerContext,
    uiConfig?: UiConfig,
  ): Promise<Record<string, unknown>> {
    const device = await context.deviceState.ensureDevice(context.adb);
    const config = uiConfig ?? DEFAULT_CONFIG.ui;
  
    const handler = operations[input.operation];
    if (!handler) {
      throw new ReplicantError(
        ErrorCode.INVALID_OPERATION,
        `Unknown operation: ${input.operation}`,
        "Valid operations: dump, find, accessibility-check",
      );
    }
    return handler(input, context, config, device.id);
  }

• src/tools/ui-query.ts:8-24 (schema)

  Zod schema defining the input structure for the "ui-query" tool.

  export const uiQueryInputSchema = z.object({
    operation: z.enum(["dump", "find", "accessibility-check"]),
    selector: z.object({
      resourceId: z.string().optional(),
      text: z.string().optional(),
      textContains: z.string().optional(),
      className: z.string().optional(),
      nearestTo: z.string().optional(),
    }).optional(),
    debug: z.boolean().optional(),
    maxTier: z.number().min(1).max(5).optional(),
    gridCell: z.number().min(1).max(24).optional(),
    gridPosition: z.number().min(1).max(5).optional(),
    compact: z.boolean().optional(),
    limit: z.number().min(1).max(100).optional(),
    offset: z.number().min(0).optional(),
  });

• src/tools/ui-query.ts:161-202 (registration)

  The definition of the "ui-query" tool, including its name, description, and JSON schema for input validation.

  export const uiQueryToolDefinition = {
    name: "ui-query",
    description: "Query app UI. Accessibility-first.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["dump", "find", "accessibility-check"],
        },
        selector: {
          type: "object",
          properties: {
            resourceId: { type: "string" },
            text: { type: "string" },
            textContains: { type: "string" },
            className: { type: "string" },
            nearestTo: { type: "string", description: "Find elements nearest to this text (spatial proximity)" },
          },
        },
        debug: { type: "boolean" },
        maxTier: {
          type: "number",
          minimum: 1,
          maximum: 5,
          description: "Max fallback tier (1-5). Use 3 to stop before visual/grid payloads.",
        },
        gridCell: { type: "number", minimum: 1, maximum: 24 },
        gridPosition: { type: "number", minimum: 1, maximum: 5 },
        compact: { type: "boolean", description: "Paginated flat list (default: true). false for full tree." },
        limit: { type: "number", minimum: 1, maximum: 100, description: "Default: 20" },
        offset: { type: "number", minimum: 0 },
      },
      required: ["operation"],
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  };